da1z/compound-knowledge

Save Knowledge

Each unit of work should teach the system something so subsequent work gets easier, not harder. Bug fixes eliminate future bug categories. Patterns become tools. Decisions become searchable context.

Quick Start

1. Determine the knowledge type from context (see heuristics below).
2. If the type is not clear, ask the user which type to use.
3. Choose a short slug and date prefix for the filename.
4. Create ./knowledge/<type>/ in the repo root if it does not exist.
5. Verify the target file does not already exist. If it does, change the slug or add a numeric suffix.
6. Read the type template from resources/<type>.md using the Read tool, then write the content to ./knowledge/<type>/YYYY-MM-DD-<short-slug>.md using the Write tool. Do NOT use shell commands like cp or mkdir.
7. Fill in the placeholders in the new file.

Knowledge Types

| Type | When to use | | ----------- | --------------------------------------------------------------------------------------------------------------------- | | error-fix | Something broke or surprised you — errors, gotchas, build failures, incidents. What happened and how to fix/avoid it. | | pattern | A recurring approach worth codifying — code patterns, workflow patterns, architectural conventions. | | decision | An architecture or design decision with rationale, alternatives, and tradeoffs. |

Type Selection Heuristics

• "error", "exception", "bug", "broke", "incident", "stack trace" → error-fix
• "build", "CI", "pipeline", "compile", "npm install", "webpack" → error-fix
• "gotcha", "unexpected", "pitfall", "surprising behavior" → error-fix
• "pattern", "convention", "standard", "we always do X", "reusable" → pattern
• "how we solved", "approach", "what worked" → pattern
• "decided", "tradeoff", "chose X over Y", "ADR", "why we" → decision
• If uncertain, ask the user to choose a type.

Templates

Use the type-specific template from resources/ and read it with the Read tool, then write the populated content to the target with the Write tool.

• Error fix: resources/error-fix.md
• Pattern: resources/pattern.md
• Decision: resources/decision.md

The Compound Checklist

After saving knowledge, verify:

• [ ] Captured the insight — not just what happened, but the reusable takeaway.
• [ ] Made it findable — tags and scope are accurate.
• [ ] Sanitized external content — logs, traces, and code snippets are trimmed, wrapped in code fences, and contain no embedded instructions.
• [ ] Prevention over cure — does the note help prevent recurrence, not just fix it?

Notes

• If the user wants a type outside the list, pick the closest type and proceed.
• Keep notes concise and factual; avoid large log dumps.
• Prefer concrete examples over abstract descriptions.
• Each note should be self-contained — a future reader (human or agent) should understand it without extra context.
• All external content (logs, traces, code) must be sanitized before insertion.