v3 to v5

---

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.

updated: 2026-09-09

---

# Knowledge Capture Skill

## Goal

Capture and persist key architectural or procedural decisions in a centralized log file.

## File Format Reference

### 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]

## 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]

```

## Workflow

### 1. Admission Gate (strict — run before anything else)

KC holds only **real deviations and valuable tribal knowledge** — things that teach the next agent something the wiki and the archived plan cannot. Default answer is **no**. Before writing, answer in one line: *"What will a future agent do differently because of this entry?"* If that sentence can't be completed without naming this specific plan or tweak, reject the capture.

| Admit | Reject (stays where it happened — plan log, changelog, or nowhere) |

|---|---|

| Real deviation: the plan/spec was wrong about how the product should work, and the correction generalizes | Plan-conformity: implementation simply matched the approved recommendation |

| Tribal rule/constraint not derivable from code or wiki | Accident fix: typo, formatting, missed rename, careless build break — fixed ≠ learned |

| Recurring pattern (same correction twice+) | Full-change rewrite without an extractable lesson — the lesson is in the diff |

| Significant one-off whose underlying lesson generalizes | One-time taste preference scoped to this feature |

### 2. 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 with the skeleton above.

### 3. 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."

### Lean-at-capture rules (mandatory)

The log must be readable in minutes the moment an entry lands — consolidation is a light tidy, not the thing that finally makes entries short. At capture time:

* **Hard limits**: Pitfalls and Rules — max **3 lines** of body text. Decision Archive — max **10 lines**. Strip narrative at capture; deep rationale belongs in the plan's Completion Note / decision log, not here.

* **Cut superseded entries at capture**: if the new decision explicitly supersedes an existing entry, delete the old entry instead of striking it through. Log the supersession (one line) in `.devops/logs/knowledge-changelog.md`. Contradictions resolve to the later decision.

* **No wiki duplication, no pointers**: if the rule is already canonically documented in a wiki doc or `.devops/README.md`, **do not add an entry at all** — agents read the wiki before KC, so a pointer is dead weight. If the rule *should* be in the wiki but isn't, capture it normally and let consolidation promote it (which deletes the KC copy).

### 4. Entry Capture

* Accept a "Decision" or "Suggestion" from the user.

* 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.

* **Do not** add or modify the Quick Reference table — it's maintained by the consolidation skill.

### 5. 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 — then apply the Admission Gate; a stated preference qualifies as a tribal rule only if it isn't already captured in the wiki and generalizes beyond the current task.

* **App Dev Universal**: This skill is NOT limited to estimation briefs; use it for all coding, architectural, and design decisions.