From compound-knowledge
Captures solved non-trivial problems and engineering principles as structured YAML-frontmatter markdown files for grep-based retrieval. Triggers after debugging success, user confirmation, or phrases like 'document this solution'.
npx claudepluginhub joshuaoliphant/claude-plugins --plugin compound-knowledgeThis skill is limited to using the following tools:
Capture solved problems and engineering principles as searchable YAML-frontmatter markdown files. Every capture creates a structured file that enables fast grep-based retrieval in future sessions, across projects.
Capture knowledge — solutions, context docs, learnings, and principles. Use after fixing non-trivial bugs, creating context for AI, or discovering patterns worth preserving. Triggers: compound, document solution, capture fix, save solution, knowledge compound, document this, save this fix, context, create context, update context, build context, learn, save learning, remember this.
Captures verified solutions to non-trivial problems as categorized markdown files with YAML frontmatter in symptom directories for grep-searchable knowledge base. Auto-triggers on phrases like 'that worked' or /doc-fix command.
Coordinates parallel subagents to document recently solved problems into searchable YAML-frontmatter Markdown files in docs/solutions/. Offers full research/cross-reference mode or lightweight single-pass.
Share bugs, ideas, or general feedback.
Capture solved problems and engineering principles as searchable YAML-frontmatter markdown files. Every capture creates a structured file that enables fast grep-based retrieval in future sessions, across projects.
{project_root}/knowledge/solutions/~/.claude/compound-knowledge-registry.md. Tracks all knowledge bases on the machine.Resolve the solutions directory before any operation. First match wins:
{project_root}/.claude/compound-knowledge.local.md — extract solutions_path value~/.claude/compound-knowledge.local.md — extract solutions_path value{project_root}/knowledge/solutions/If the resolved directory does not exist:
"Solutions directory not found at
{solutions_path}. Run/compound-knowledge:setupto initialize it."
Skip capture for: typos, syntax errors, missing imports, one-line fixes with no investigation, obvious bugs caught immediately.
Proceed with capture for: problems requiring multiple investigation attempts, non-obvious root causes, solutions involving code examples or architecture decisions, issues likely to recur.
| Solution | Principle | |
|---|---|---|
| Has | symptoms (required) | statement + confidence (required) |
| Lives in | Category directory (debugging/, patterns/, etc.) | principles/ directory |
| Documents | A specific problem and its fix | Generalizable engineering wisdom |
| Heuristic | Someone could grep for an error message and find this | Advice that applies across many situations |
{solutions_path}/
├── debugging/ # Service failures, error diagnosis
├── infrastructure/ # Networking, storage, resource issues
├── patterns/ # Design patterns, architectural approaches
├── workflow/ # Process improvements, scope management
├── performance/ # Speed, resource optimization
├── security/ # Vulnerability fixes, secrets management
├── ci-cd/ # Pipeline issues, publishing, deployment
├── configuration/ # Config management, env vars, settings
├── migration/ # System transitions, format changes
├── integration/ # Cross-system compatibility
├── principles/ # Engineering wisdom and governing principles
└── critical-patterns.md # High-severity patterns (always read)
For field definitions, enum values, and validation rules:
→ references/yaml-schema.md
For file templates:
→ references/solution-template.md
→ references/principle-template.md
For cross-project registry schema:
→ references/registry-format.md
Load any stored feedback preferences before starting:
python ${PLUGIN_ROOT}/scripts/feedback_manager.py compound-knowledge show-feedback
If feedback entries exist, apply them throughout the capture process:
Follow the Path Resolution algorithm from Context. Store as {solutions_path}.
If the problem is trivial (see filter in Context), skip capture.
If unsure:
"This seems like a solution worth documenting. Want me to capture it?"
Determine whether this is a solution or a principle (see Context table).
For solutions, extract from the conversation:
| Field | Required? |
|---|---|
title — Clear problem description | Yes |
date — Auto-populated as YYYY-MM-DD | Yes |
project — Current working directory or explicit mention | Yes |
problem_type — Maps to category directory (see yaml-schema.md) | Yes |
component — Technology involved | Yes |
symptoms — Error messages, observable behavior | Yes |
solution_summary — One-line fix description | Yes |
severity — critical, high, medium, low | Yes |
root_cause, resolution_type, tags, environment | No |
For principles, extract:
| Field | Required? |
|---|---|
title — Principle name | Yes |
date — Auto-populated as YYYY-MM-DD | Yes |
project — Where validated, or "cross-project" | Yes |
problem_type — Always principles | Yes |
component — Technology domain | Yes |
statement — Concise, generalizable rule (1-2 sentences) | Yes |
confidence — high, medium, low | Yes |
solution_summary — One-line description | Yes |
severity — Impact if ignored | Yes |
If critical fields are missing, ask and wait:
"I need a few details to capture this properly: What project is this for? What were the symptoms?"
Search {solutions_path} for similar existing solutions:
Grep(pattern="symptoms:.*{key_symptom}", path="{solutions_path}", output_mode="files_with_matches")
Grep(pattern="title:.*{similar_term}", path="{solutions_path}", output_mode="files_with_matches")
related_solutions cross-referenceRead references/yaml-schema.md and validate all enum fields. Block creation if validation fails. Report which fields are invalid and suggest corrections.
Before writing, present:
Capturing: {solution|principle}
Title: {title}
Project: {project}
Component: {component}
Category: {problem_type} → {solutions_path}/{category}/
Severity: {severity}
File: {filename}.md
Proceed?
Wait for user confirmation before writing.
{sanitized-symptom}-{project}-{YYYYMMDD}.md (lowercase, hyphens, max 80 chars)solution-template.md or principle-template.md)Links must be bidirectional — if file A references file B, file B must reference file A.
related_solutions entries to the new file pointing to matches from Step 4category/filename.md format for all paths (never absolute paths)Present summary:
Created: {solutions_path}/{category}/{filename}.md
Related solutions:
- [title](path) — {why related}
Updated backlinks in:
- {path1}
- {path2}
Update ~/.claude/compound-knowledge-registry.md so this knowledge base is discoverable from other projects.
references/registry-format.md header if missing)A structured markdown file in {solutions_path}/{category}/ with:
references/yaml-schema.mdreferences/solution-template.md or references/principle-template.md