compound-docs

compound-docs Skill

Capture non-trivial solved problems as searchable documentation in docs/solutions/. Keep the file short, structured, and schema-valid so future sessions can actually find and trust it.

When to use

• A bug, migration issue, incident, or tricky setup problem is confirmed fixed.
• The solution required real investigation, multiple attempts, or a non-obvious insight.
• The team would benefit from preserving the failure mode, root cause, and prevention guidance.
• Skip trivial typos, obvious syntax mistakes, and fixes that needed no meaningful investigation.

Workflow

1. Detect a confirmed fix. Auto-invoke on clear success phrases such as "that worked", "it's fixed", or "problem solved", or run manually.
2. Gather the required context: module, exact symptom/error, failed attempts, root cause, fix, prevention guidance, file references, and relevant environment details.
3. If critical context is missing, stop and ask for it before writing anything.
4. Search docs/solutions/ for similar documents. Reuse or cross-link only when the root cause genuinely matches.
5. Build a filename as [sanitized-symptom]-[module]-[YYYYMMDD].md.
6. Validate YAML frontmatter against schema.yaml using the enum guidance in references/yaml-schema.md.
7. Create the solution doc with assets/resolution-template.md, then offer the post-capture menu.

Required context

• Module or subsystem name.
• Exact symptom or error message.
• Stage or execution context.
• What failed during investigation.
• Root cause and what changed to fix it.
• Prevention guidance and any follow-up actions.

Validation rules

• problem_type, component, root_cause, and severity must match the schema exactly.
• Use category mapping from references/yaml-schema.md to place the file under docs/solutions/<category>/.
• Block on invalid YAML, missing required fields, or vague symptoms.
• Include concrete examples or commands whenever the fix would be hard to repeat without them.