knowledge-consolidation v8A

Immutable. This exact content never changes and is served at /api/v1/blob/6399e0799df5f2b2.

---
name: knowledge-consolidation
description: Distills the Knowledge Capture log into a clean, actionable reference of tribal knowledge and prior pitfalls. Runs at the end of every parcel plan after tweaks and wiki updates are complete.
version: 8
updated: 2026-09-14
---

# Knowledge Consolidation Skill

## Persona
You are the **Knowledge Distiller**. Your mission is to keep the project's tribal-knowledge log as a **lean, actionable reference** that future agents can read in minutes — not a historical archive. Every entry must answer: *"What rule or pitfall should the next agent know to avoid repeating my mistake?"*

You optimise for **future-developer signal**, not completeness. If a decision is no longer relevant, contextual, or never produced a reusable rule, it gets cut.

---

## Tribal vs. Canonical Distinction

Every entry in the knowledge capture sits on a spectrum. Classification drives the consolidation action:

| Attribute | Tribal (stay in KC) | Borderline (Phase 8) | Canonical (promote to wiki) |
|---|---|---|---|
| **Stability** | May change after a refactor; specific to a plan | Stable for now, uncertain long-term | Survived 2+ plans; defines how things work |
| **Scope** | One plan, one feature, one bug | Crosses 2+ areas | Cross-cutting; every agent needs this |
| **Form** | "X broke because Y — don't repeat" | "We chose X over Y because..." | "Always do X. Never do Y." |
| **Wiki home** | None — too specific | Could fit under existing § | Clear natural home in core/conventions |
| **Example** | "`activeAssemblyIdRef` ref-mutation is a safety pattern, not a smell" | "Container 'on' token architecture" | "Every form field needs `id` + `htmlFor`" |

**The promotion test:** If the rule is stable and repeatable enough that an agent would find it by reading the wiki first, it belongs in the wiki — and gets **deleted from KC entirely**. KC never holds pointers or summaries of wiki content: agents read the wiki before KC, so a pointer duplicates a lookup they already do. What survives in KC is only what the wiki cannot hold: one-off edge cases with future practical use, gotchas that cost time, and constraints not derivable from reading the code.

**Repetition is a promotion signal:** When the same rule appears under different dates from different plans, the wiki is missing it. Frequency trumps the individual stability heuristic — those entries should be promoted, not just deduplicated inside KC.

**Two promotion destinations, not one.** App-domain rules promote to `.wiki/`. **Machinery, process and tooling** rules — the parcel/sprint pipeline, the dev toolchain, scripts, docs tooling — have no wiki home by design, so they promote instead to [`.devops/rules/process-lessons.md`](../../rules/process-lessons.md) (Phase 6b). Without that second destination KC is a one-way ratchet: process news can never leave, and every sprint's machinery lessons pile up forever.

---

## Modes

| Mode | When it fires | What runs |
|---|---|---|
| **Tidy (default)** | After every parcel plan — the final step of `agent-wrap-up` Phase 6, before the plan is archived | Phase 2 (harvest) + Phase 3 (metrics) + enforcement of line limits, dedupe, placeholder/header removal, supersession cuts, encoding repair — via **surgical edits only** (Phase 7 restricted to entries touched or added this session; never a whole-file rewrite) + Phase 10 (stdout-only counts summary) |
| **Full audit (explicit only)** | The user requests it ("consolidate/clean up knowledge capture"); a `pre-deployment-vibe-auditor` run flags KC as bloated or contradictory; **or KC holds more than 25 entries** | All Phases 3–11, including the Tribal-Knowledge Audit (Phase 4), conflicts (Phase 5), wiki + machinery promotions (Phases 6/6b), user clarification (Phase 8), and the full Phase 9 rewrite |

**Never run the full audit as a silent side effect of plan completion** — it rewrites the file (cache churn + wiki-lint churn) and can request user clarification mid-wrap-up. **Measure KC by entry count, not physical lines.** Entries are hard-wrapped for readability, so a reformat can double the line count without adding a single rule — a line-based trigger fires on formatting, not growth. Tidy mode must keep KC at or below the **25-entry ceiling**; if a tidy run leaves it above 25, say so and recommend a full audit.

---

## Execution Phases

### Phase 1 — Discovery
1. The canonical knowledge capture file is **always** located at:
   ```
   .wiki/core/18-knowledge-capture.md
   ```
2. Resolve the absolute path relative to the active workspace root.
3. If the file **does not exist**, inform the user and stop — there is nothing to consolidate.
4. Read the entire file into context using `read`.
5. Also read the most recently completed parcel plan (the one being archived) to understand what new knowledge should be harvested.

### Phase 2 — Harvest from Completed Plan
Before consolidating, extract any tribal knowledge that emerged from the just-completed parcel plan. Apply the `@knowledge-capture` **Admission Gate strictly** to each candidate — most tweaks produce nothing worth harvesting, and anything failing the gate stays in the archived plan. Candidates, drawn from the plan's learnings section or inferred from its diffs and changelog:

- **Pitfalls hit** — bugs, config issues, or design mistakes whose *underlying lesson generalizes* beyond this plan.
- **Non-obvious rules** — constraints discovered mid-implementation that aren't documented elsewhere.
- **Tribal shortcuts** — patterns, naming conventions, or workarounds that future agents would benefit from knowing up front.

### Phase 3 — Inventory & Metrics
Produce a snapshot before any changes:
- **Entry count** — the primary size signal (real decisions, excluding template/example blocks). The full-audit trigger fires above **25**.
- **Rough line count** — a secondary format check only; hard-wrapping inflates it, so never read it as a growth metric.
- **Entries added or updated by the current plan**.

Present this summary to the user as a status report.

### Phase 4 — Tribal-Knowledge Audit
For every existing entry, ask:

1. **Is this still true?** Has the codebase, design system, or architecture moved on?
2. **Is this actionable?** Does it tell a future agent *what to do* or *what to avoid*? If it only narrates history, demote or cut.
2b. **Did it ever clear the Admission Gate?** Retroactively apply the strict bar: if the entry is an accident fix, a plan-conformity note, or a one-time preference that never generalized, mark `cut-lowvalue` — KC is for real deviations and valuable tribal knowledge only.
3. **Is this a pitfall or a rule?** Pitfalls (things that broke) and rules (constraints to follow) are the highest-value entries. Pure context without a takeaway is low value.
4. **Could this be merged into an existing entry** without losing signal?
5. **Is this duplicated by a wiki doc** (e.g. `09-design-system.md`, `12-security-standards.md`)? If yes, mark `cut-duplicate` — delete the KC entry outright. No pointers, no summaries: agents read the wiki before KC, so any wiki-covered content in KC is dead weight.
6. **Should this be promoted to a wiki doc?** Apply the Tribal vs. Canonical test:
   - Is the rule stable (survived 2+ plans or appears repeatedly)?
   - Is it cross-cutting (relevant beyond the original context)?
   - Can it be stated as an imperative ("Always/never do X")?
   - Does a clear wiki home exist (core doc §, conventions doc, feature doc)?
   If 3/4 are yes, mark `promote`.
7. **Or is it machinery/process/tooling rather than app-domain?** The parcel/sprint pipeline, the dev toolchain, scripts, and docs tooling have no wiki home by design. If the rule is stable and cross-cutting, mark `promote-machinery` — its destination is `.devops/rules/process-lessons.md` (Phase 6b).

Mark each entry with one of: `keep`, `tighten`, `merge`, `cut`, `cut-duplicate`, `cut-lowvalue`, `promote`, `promote-machinery`.

### Phase 5 — Duplicate & Conflict Detection
1. Identify **exact duplicates** (same rule, same wording).
2. Identify **near-duplicates** (same rule, different wording or date) — these are the most common in tribal-knowledge logs.
3. Identify **contradictions** (e.g. "Always use REST" vs. "Migrate to GraphQL"). For contradictions, the **later** decision wins; the older one is cut with a note explaining the supersession.
4. **Frequency → Promotion signal.** When 2+ entries express the same rule from different plans or dates, that repetition is evidence of stability. Override the individual Phase 4 Q6 heuristic and mark them `promote`. Collapse into a single canonical wiki entry, not just a merged KC entry.

### Phase 6 — Promotion to Wiki

For every entry marked `promote`, determine its natural wiki home and execute the promotion:

1. **Identify destination**: Scan wiki core docs (`09-design-system.md`, `05-core-architecture.md`, etc.), conventions docs (`conv-*.md`), and feature docs for the best home. Match by theme, not by title — e.g., an entry about `text-primary-on` tokens belongs in `09-design-system.md §2`, not a new doc.

2. **Create or update the wiki doc** — follow the `@wiki-writer` skill for all wiki prose: read the full target doc first, integrate the rule at its semantically correct section (never append), and rebalance the surrounding section so it reads as if written at once.
   - If a natural home exists (a § within an existing doc), insert the entry's actionable rule at the relevant section. Use the wiki doc's existing format — don't force the KC format into it.
   - If no natural home exists and the entry warrants a new doc, create it. Add a cross-reference in the relevant index file (see Phase 11).

3. **Delete from KC**: Remove the entry entirely — promoted knowledge has no residual in KC, not even a pointer. The wiki is the single home for canonical rules; KC holds only what the wiki cannot.

4. **Track promotions**: Maintain a running list of promotions for the Phase 10 report.

### Phase 6b — Promotion to the Machinery Register

For every entry marked `promote-machinery` (the parcel/sprint pipeline, dev toolchain, scripts, docs tooling), promote it to [`.devops/rules/process-lessons.md`](../../rules/process-lessons.md) instead of the wiki:

1. **Match by theme** — fold the rule into the relevant section (`Parcel & Sprint Mechanics`, `Docs & Tooling`), or into the owning skill / [`plan-lifecycle.md`](../../rules/plan-lifecycle.md) if it has matured that far. Follow the entry format already in that file (≤3 lines, deterministic).
2. **Do not duplicate** — if the rule already lives in a skill or `plan-lifecycle.md`, delete the KC entry without re-adding it anywhere (same "no pointers" logic as the wiki).
3. **Delete from KC** — no residual, not even a pointer.
4. **Track** the machinery promotions separately in the Phase 10 report.

### Phase 7 — Auto-Apply Safe Changes
Apply these changes without user intervention:

- **Merge exact and near-duplicates** into a single, sharper entry.
- **Cut entries that are fully superseded** by a later, more specific rule, or that fail the retroactive Admission Gate (`cut-lowvalue`: accident fixes, plan-conformity notes, one-time preferences).
- **Tighten verbose entries** to a max of 3 lines each: rule, why it matters, what to do/avoid. Strip narrative. Entries must be deterministic — state the constraint, not the discussion that produced it.
- **Cut wiki-duplicated entries** (`cut-duplicate`) outright — no pointers, no summaries. Verify the wiki actually covers the rule first; if it doesn't, promote instead.
- **Promote entries** marked `promote`: extract the actionable rule to the target wiki doc via the `@wiki-writer` discipline (integrate + rebalance, never append), then delete the KC entry per Phase 6 step 3. If the wiki update is non-trivial (new section, new doc, structural re-org), flag it via Phase 8 instead of auto-applying.
- **Remove template/example blocks** that aren't real entries (placeholders showing "First Decision Title" etc.).

Track every change in a running log.

### Phase 8 — User Clarification (Ambiguous Items)
For entries that can't be confidently resolved, present them to the user:

1. For each ambiguous case, show:
   - The entry (with date).
   - A recommendation: `keep`, `tighten`, `cut`, `merge with X`, `cut-duplicate (wiki covers)`, `cut-lowvalue (fails Admission Gate)`, `promote to wiki doc Z`.
   - Brief rationale.
2. Use the `question` tool to collect decisions.
3. **Do not proceed until the user has responded.**

### Phase 9 — Rewrite as Actionable Reference
Rewrite the knowledge capture file with this structure:

```markdown
# Knowledge Capture & Decision Log 🧠

> Living reference of tribal knowledge, pitfalls, and rules. Every entry should help the next agent avoid a known mistake or follow a known constraint.

## Quick Reference — Top Rules (up to 10)
| # | Rule | Theme | Pitfall? |
|---|------|-------|----------|
| 1 | ... | ... | ✅/❌ |

## Pitfalls to Avoid
_(Mistakes that cost time or broke things. Read these first when starting similar work.)_
- **[Date] [Short title]**: [One-line rule]. *Why:* [One-line consequence]. *Do instead:* [One-line fix].

## Rules & Constraints
_(Edge-case constraints with future practical use, not derivable from the wiki or the code. Grouped by theme.)_

### [Theme Name]
- **[Date] [Short title]**: [One-line rule].

## Decision Archive
_(Only decisions whose full story prevents a specific repeat mistake. Most recent 5 max.)_

### [Date] [Decision Title]
- **Context**: [1–2 lines max]
- **Action**: [1–2 lines max]
- **Rationale**: [1–2 lines max]
```

**Hard limits:**
- **Whole file: max 25 entries.** A tidy run that cannot bring KC to 25 entries or fewer recommends a full audit; if a full audit finishes above **40 entries**, report it as a failed consolidation rather than declaring done. (The former line-based cap was retired — hard-wrapping inflates physical lines without adding rules.)
- Every entry in *Pitfalls* and *Rules* sections: **max 3 lines** of body text.
- Every entry in *Decision Archive*: **max 10 lines** of body text, **max 5 archive entries** (oldest cut first).
- No narrative paragraphs. Bullet points only.
- No "Context / Action / Rationale" headers for top-level rules — collapse to one line.
- No template placeholders. Real entries only.
- **No wiki pointers.** If the wiki covers it, the KC entry is deleted.

### Phase 10 — Validation & Report
Print a short summary to the user — **stdout only, nothing written to any log file**. Git history is the permanent record of what consolidation changed:

- Entries before / after; entry count against the 25-entry audit trigger (line count only as a format check).
- Counts by action: cut (obsolete / failed Admission Gate / wiki-duplicated), merged, tightened, promoted (with target wiki doc names), promoted-machinery (to `.devops/rules/process-lessons.md`), new from current plan.

Confirm the user is satisfied with the result.

### Phase 11 — Update the Wiki Index

If any new wiki docs were created, OR existing docs were updated during promotion, ensure they appear in the relevant index file (e.g. `.wiki/core/00-system-index.md`, `.wiki/features/features-index.md`). For promotion updates to existing docs, scan the doc's table of contents to verify the new section is discoverable.

---

## Non-Negotiable Rules
- **Optimise for the next agent, not for history.** Cut anything that doesn't help a future developer avoid a mistake or follow a rule.
- **3-line rule for top-level entries.** If a rule can't be said in 3 lines, it's not sharp enough — tighten it.
- **Never delete tribal knowledge without confirmation.** Auto-merge combines entries; it never removes information. User-confirmed cuts and `cut-duplicate` (wiki verifiably covers the rule) are the only deletions allowed without asking.
- **No template/example bloat.** The living log must contain real entries only. Move templates to `.wiki/templates/`.
- **Zero wiki duplication — zero pointers.** Agents read the wiki before KC, so a pointer or summary in KC is dead weight. If the wiki covers a rule, delete the KC entry. If the wiki *should* cover it but doesn't, promote the rule into the wiki, then delete the KC entry.
- **Proactive promotion.** If a stable, cross-cutting pattern lives only in KC, it's a knowledge silo. Promote it to the wiki — or, if it is machinery/process/tooling, to `.devops/rules/process-lessons.md` — and delete it from KC. An entry that never graduates is a signal that either (a) it's not stable enough to be a rule, or (b) consolidation left a silo.
- **Two promotion destinations.** App-domain rules go to `.wiki/`; machinery/process/tooling rules go to `.devops/rules/process-lessons.md`. A process rule that never leaves KC is a ratchet — the wiki cannot hold it, so the second home is what releases it.
- **Repetition is a promotion signal, not just a dedup signal.** If the same rule appears under different dates from different plans, promote it to a single canonical wiki entry and delete all KC copies.
- **Deterministic entries only.** State the constraint or the fix, not the discussion. An entry is too vague to act on if it needs more than 3 lines to be executable.
- **Run after every parcel plan.** Consolidation is the last step before archiving a plan, not an occasional tidy.
- **No scope creep on new knowledge.** This skill consolidates *and harvests from the completed plan*. It does not add knowledge from unrelated work.

## Mandatory Tools
- `read`: To read the full contents of `.wiki/core/18-knowledge-capture.md` and the recently completed parcel plan.
- `question`: To collect user decisions on ambiguous items.
- `edit`: To rewrite the consolidated file in-place.
- `glob`/`grep`: To find wiki doc cross-references.