knowledge-consolidation · diff
v2.0 to v3.0
58 added, 10 removed. Audit A to A.
---
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: "2.0"
+ version: "3.0"
author: "Antigravity Team"
---
# 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 you can replace the entry with `"See [wiki doc] §[section]"` and an agent reading only KC would still be effective, it belongs in the wiki. If the agent needs the full story to avoid repeating a mistake, it stays tribal.
+
+ **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.
+
+ ---
+
## Trigger Conditions
Activate this skill whenever:
1. **Primary trigger — Parcel plan completion.** Whenever a parcel plan in `.devops/plans/` is being marked complete (after tweaks, wiki updates, and tests are done), as the final step before archiving the plan to `.devops/archive/`.
2. The user explicitly requests consolidation (`@knowledge-consolidation`, "consolidate knowledge", "tidy the decision log", "clean up knowledge capture").
3. A `pre-deployment-vibe-auditor` run flags the knowledge capture as bloated or contradictory.
---
## 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:
- **Pitfalls hit** — bugs, config issues, or design mistakes that cost time.
- **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.
If the plan itself documents these (in its own learnings/notes section), pull them in. If not, infer them from the plan's diffs and changelog.
### Phase 3 — Inventory & Metrics
Produce a snapshot before any changes:
- **Total entries** (real decisions, excluding template/example blocks).
- **Rough size** (line count, distinguishing real content from template boilerplate).
- **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.
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. `06-design-system.md`, `13-security-standards.md`)? If yes, link to the wiki doc instead of duplicating.
+ 5. **Is this duplicated by a wiki doc** (e.g. `09-design-system.md`, `12-security-standards.md`)? If yes, mark `link-to-wiki` — replace the entry with a one-line pointer and a wiki link.
+ 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`.
- Mark each entry with one of: `keep`, `tighten`, `merge`, `cut`, `link-to-wiki`.
+ Mark each entry with one of: `keep`, `tighten`, `merge`, `cut`, `link-to-wiki`, `promote`.
### 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 — Auto-Apply Safe Changes
+ ### 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. **Replace in KC**: Replace the full entry with a 1-3 line pointer + wiki link:
+ `- **[Title]**: [One-line rule]. *See:* [path/to/wiki/doc.md]`
+ The canonical detail now lives in the wiki. KC is the index; the wiki is the reference.
+
+ 4. **Track promotions**: Maintain a running list of promotions for 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.
- **Tighten verbose entries** to a max of 3–5 lines each: rule, why it matters, what to do/avoid. Strip narrative.
- **Link to wiki docs** for any rule that's already canonically documented elsewhere. The knowledge capture should reference, not duplicate.
+ - **Promote entries** marked `promote`: extract the actionable rule to the target wiki doc via the `@wiki-writer` discipline (integrate + rebalance, never append), replace the KC entry with a 1-line pointer (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 7 — User Clarification (Ambiguous Items)
+ ### 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`, `link to wiki doc Y`.
+ - A recommendation: `keep`, `tighten`, `cut`, `merge with X`, `link to wiki doc Y`, `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 8 — Rewrite as Actionable Reference
+ ### 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 10 Rules
| # | 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
_(Stable rules derived from prior decisions. Grouped by theme.)_
### [Theme Name]
- **[Date] [Short title]**: [One-line rule]. *See also:* [wiki doc link if applicable].
## Decision Archive
_(Full context for decisions that need historical rationale. Link here from Quick Reference.)_
### [Date] [Decision Title]
- **Context**: [1–2 lines max]
- **Action**: [1–2 lines max]
- **Rationale**: [1–2 lines max]
- **Wiki ref**: [link]
```
+ _NOTE: Entries promoted to wiki docs appear as pointers in the "Rules & Constraints" section or in "See Also" with a wiki link. Their full canonical content lives in the wiki._
+
**Hard limits:**
- Every entry in *Pitfalls* and *Rules* sections: **max 3 lines** of body text.
- Every entry in *Decision Archive*: **max 10 lines** of body text.
- 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.
- ### Phase 9 — Validation & Report
+ ### Phase 10 — Validation & Report
Present a final report:
| Metric | Count |
|---|---|
| Entries before | _n_ |
| Entries after | _n_ |
| Cut (obsolete/superseded) | _n_ |
| Merged (duplicates) | _n_ |
| Tightened (verbose → sharp) | _n_ |
| Linked to wiki docs | _n_ |
+ | Promoted to wiki docs | _n_ |
| New entries from current plan | _n_ |
| User decisions requested | _n_ |
Confirm the user is satisfied with the result.
- ### Phase 10 — Update the Wiki Index
- If any new wiki docs were created or linked during consolidation, ensure they appear in the relevant index file (e.g. `.wiki/core/00-system-index.md`, `.wiki/features/features-index.md`).
+ ### 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 without confirmation.** Auto-merge combines entries; it never removes information. Only user-confirmed cuts are allowed.
- **No template/example bloat.** The living log must contain real entries only. Move templates to `.wiki/templates/`.
- **Link, don't duplicate.** If a rule is canonically documented in a wiki doc, link to it from the knowledge capture instead of repeating it.
+ - **Proactive promotion, not passive linking.** "Link, don't duplicate" is reactive — it only fires when a wiki doc already exists. If a stable, cross-cutting pattern lives only in KC, it's a knowledge silo. Promote it to the wiki. KC is the decision log; the wiki is the canon. An entry that never graduates to the wiki is a signal that either (a) it's not stable enough to be a rule, or (b) consolidation left a silo.
+ - **Repetition is a promotion signal, not just a dedup signal.** If the same rule appears under different dates from different plans, don't just merge it tighter in KC — promote it to the wiki. The frequency tells you the wiki is missing that entry. Collapse to one canonical wiki entry and one KC pointer.
- **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.