| name | kn-extract |
| description | Use when extracting reusable patterns, decisions, failures, or knowledge into documentation |
Extracting Knowledge
Announce: "Using kn-extract to extract knowledge."
Core principle: CAPTURE ONLY GENERALIZABLE KNOWLEDGE, WITH PROVENANCE.
Inputs and Modes
- Completed task ID, code change, repeated pattern, or recurring failure
--consolidate to review existing learning docs instead of extracting one source
Use Knowns APIs for managed tasks, docs, memories, and decisions. Do not edit their markdown directly.
Normal Extraction
1. Read the Source
Read the task or referenced work and identify genuine findings in three categories:
| Category | Capture when |
|---|
| Pattern | A reusable implementation, architecture, integration, or process approach exists |
| Retrospective learning | A good call, bad call, surprise, trade-off, or failure can improve future work |
| System Decision | Stable guidance future work must follow: architecture, behavior, naming, storage, API contract, workflow convention, or explicit trade-off |
Do not fabricate findings. A valid no-op is better than generic advice.
2. Search Before Creating
Search docs, memories, and current Decisions for overlap. Prefer updating a canonical doc over creating a duplicate.
mcp_knowns_search({ "action": "search", "query": "<topic>", "type": "doc" })
mcp_knowns_search({ "action": "search", "query": "<topic>", "type": "memory" })
3. Persist the Right Artifact
- Pattern or detailed learning: create/update a Knowns doc and link the source task/doc.
- Fast recall: save a concise project Memory that links the canonical doc. Use only
pattern, convention, preference, or failure categories.
- Stable guidance: create a first-class draft System Decision candidate with task/doc/source provenance. Never auto-accept it.
- Generatable pattern: create a template only when repeated generation is genuinely useful and a linked pattern doc exists.
Never create Memory category decision. Spec Decisions remain canonical in an approved spec's Locked Decisions section and must not be copied into the System Decision ledger.
A System Decision candidate must remain non-current until explicit verified resolution. If it replaces current guidance, use the reviewed supersession flow rather than overwriting the old Decision.
4. Promote Sparingly
Promote a learning to learnings/critical-patterns only when it:
- applies to multiple future features
- would avoid at least substantial repeated effort
- is concrete and generalizable
Keep promoted entries concise and link the full canonical doc. Avoid turning the critical list into a second knowledge dump.
5. Validate and Link Back
Validate every created or updated doc/template/Decision ref. Append one concise source-task note containing the canonical refs. Do not mark unrelated task ACs or change task status.
Consolidation Mode
When --consolidate is present:
- List learning docs and inspect likely duplicate/outdated/orphan clusters; do not load every full document before narrowing candidates.
- Classify proposed actions as merge, update, promote, repair ref, archive, or no-op.
- Present a compact preview with reasons and target canonical paths.
- Require explicit user approval before destructive, archival, supersession, or broad rewrite actions.
- Apply approved changes through Knowns APIs and validate affected entities.
- Report merged/updated/promoted/repaired counts and unresolved candidates.
Never delete or overwrite a document merely because titles look similar. Compare content and provenance first.
Shared Output Contract
Return information in this order:
- Goal/result — what was extracted, consolidated, or intentionally left as a no-op.
- Key details — canonical docs, memories, Decision candidates, templates, provenance, and validation.
- Next action — one command only when a natural handoff exists.
Include what now serves as the canonical knowledge source. If nothing generalizable was found, say so plainly.
Checklist
