knowledge-capture · diff
v1.0 to v1.1
53 added, 15 removed. Audit A to A.
---
name: knowledge-capture
description: Automates the recording of user decisions, feedback, and tribal knowledge to ensure project consistency and long-term learning across all development tasks.
- version: "1.0"
+ version: "1.1"
author: "Antigravity Team"
---
# Knowledge Capture Skill
## Goal
Capture and persist key architectural or procedural decisions in a centralized log file.
+ ## File Format Reference
+
+ This skill adds entries to `.wiki/core/18-knowledge-capture.md`, which is periodically restructured by the **knowledge-consolidation** skill into a canonical 4-section layout. Write entries in the format that matches the section below — it matches what consolidation Phase 9 produces.
+
+ ### Current file sections
+
+ ```
+ ## Quick Reference — Top 10 Rules
+ (compact table of highest-signal rules — updated by consolidation only, not by capture)
+
+ ## Pitfalls to Avoid
+ _Mistakes that cost time or broke things._
+ - **[Short title]**: [One-line rule]. *Why:* [One-line consequence]. *Do instead:* [One-line fix].
+
+ ## Rules & Constraints
+ _Stable rules derived from prior decisions. Grouped by theme._
+
+ ### [Theme Name]
+ - **[Short title]**: [One-line rule]. *See also:* [wiki doc link if applicable].
+
+ ## Decision Archive
+ _Full context for decisions that need historical rationale._
+
+ ### [Decision Title]
+ - **Context**: [1–2 lines max]
+ - **Action**: [1–2 lines max]
+ - **Rationale**: [1–2 lines max]
+ - **Wiki ref**: [link]
+ ```
+
## Workflow
### 1. Discovery & Initialization
* The canonical knowledge capture file is **always** located at:
```
.wiki/core/18-knowledge-capture.md
```
Resolve the absolute path relative to the active workspace root. **Do not search for alternative filenames or locations.**
- * If the file **does not exist**, create it using the Initial Content Template below.
- * **Entry Format (Hybrid Attribution):**
- Each entry MUST follow the structure in `.wiki/templates/knowledge-capture-template.md`:
- - Category header (e.g. `## [Emoji] [Category]`)
- - `### [Decision Title]`
- - Optional `> **Sources:**` / `> **Raw:**` blockquote (only for any future local file refs)
- - `* **PR(s):** [list]` and `* **External Refs:** [list]` (inline link lists)
- - `* **Context:**` / `* **Action:**` / `* **Rationale:**` with sub-bullets
- * See `.wiki/examples/knowledge-capture-example.md` for a worked example.
+ * If the file **does not exist**, create it with the skeleton above.
- ### 2. Entry Capture
+ ### 2. Section Classification
+ Classify the decision into one of three sections based on its nature:
+
+ | Section | Use when | Format max |
+ |---------|----------|------------|
+ | **Pitfalls to Avoid** | A bug, config issue, or design mistake that cost time. Must have a clear "do instead" fix. | 3 lines |
+ | **Rules & Constraints** | A stable pattern, naming convention, or constraint. Actionable — tells future agents what to do or avoid. | 3 lines |
+ | **Decision Archive** | A decision with significant historical rationale behind it. Needs Context + Action + Rationale to explain *why* over other options. | 10 lines |
+
+ When in doubt between **Pitfall** and **Rule**: a Pitfall answers "what broke and how to fix it"; a Rule answers "how things work and what to follow."
+
+ ### 3. Entry Capture
* Accept a "Decision" or "Suggestion" from the user.
- * Determine the current project context and assign a **Theme** that best categorises the entry. Common themes include:
- - `UI/UX Preferences`, `Architecture & Patterns`, `Data & State Management`, `Tooling & DevOps`, `Business Logic & Rules`, `Performance & Constraints`, `Testing & QA`, `Naming Conventions & Style`
- * Append a new entry to the appropriate category section using the **hybrid format above**. Do NOT use the legacy 4-column table format for new entries. Old entries may remain in the table format.
+ * Assign a **Theme** that best categorises the entry (used as a grouping heading in Rules & Constraints). Common themes: `Architecture & Patterns`, `UI/UX & Design Aesthetic`, `Testing & QA`, `Tooling & Code Quality`, `Product & Process`
+ * Append the new entry to the appropriate section using the exact format from §File Format Reference.
+ * If adding to **Rules & Constraints**, place under the correct `### [Theme]` subsection. Create a new theme subsection if none fits.
+ * If adding to **Pitfalls**, no theme subsection — entries are flat under the section header.
+ * If adding to **Decision Archive**, use the `### [Title]` format with `- **Context:**` / `- **Action:**` / `- **Rationale:**` / `- **Wiki ref:**` bullet points.
+ * **Do not** add or modify the Quick Reference table — it's maintained by the consolidation skill.
- ### 3. Validation
+ ### 4. Validation
* Confirm to the user that the knowledge has been persisted.
* Summarize the impact of the decision.
+ * Note if the entry is eligible for wiki promotion (stable, cross-cutting, survived multiple plans) — consolidation will handle the actual promotion.
## Usage Guidelines
* **Proactive Recording**: If a user says "I prefer X over Y" or "Always do Z in this project", activate this skill immediately.
* **App Dev Universal**: This skill is NOT limited to estimation briefs; use it for all coding, architectural, and design decisions.
+ * **Consolidation boundary**: This skill captures raw knowledge. The `knowledge-consolidation` skill handles deduplication, tightening, promotion to wiki, and restructuring. Do not self-edit existing entries — leave reorganization to consolidation.