Compound Docs

Purpose: Document solved problems to build searchable institutional knowledge. Each documented solution compounds your team's knowledge — the first time takes research, the second time takes minutes.

When to Use

• •After solving a non-trivial problem (multiple investigation attempts, tricky debugging)
• •After making architectural decisions that should be recorded
• •When a solution has prevention value for future work

Skip for: Simple typos, obvious syntax errors, trivial fixes.

Process

Step 1: Detect Confirmation

Auto-invoke after phrases like "that worked", "it's fixed", "working now", "problem solved".

Or invoke manually: /skill:compound-docs

Step 2: Gather Context

Extract from conversation history:

• •Component: Which module or area had the problem
• •Symptom: Observable error/behavior (exact messages)
• •Investigation: What didn't work and why
• •Root cause: Technical explanation
• •Solution: What fixed it (code/config changes)
• •Prevention: How to avoid in future

If critical context is missing, ask the user before proceeding.

Step 3: Check Existing Docs

Search for similar documented issues:

grep -ril "keyword" docs/ specs/

If a similar issue exists, ask:

1. •Create new doc with cross-reference (recommended)
2. •Update existing doc (only if same root cause)

Step 4: Classify and Route

Determine the document type based on what was solved:

Step 5: Write Documentation

For ADRs (docs/adr/):

# ADR-NNN: [Title]

## Status
Accepted

## Context
[What issue motivated this decision]

## Decision
[What we decided and why]

## Consequences
### Positive
### Negative
### Neutral

## Alternatives Considered

For Learning Docs (docs/learnings/):

---
date: YYYY-MM-DD
component: [component name]
problem_type: [performance|security|correctness|config|integration]
severity: [critical|high|medium|low]
tags: [searchable keywords]
---

# [Title]

## Problem
[Exact error messages, observable behavior]

## Investigation
[What was tried and why it didn't work]

## Root Cause
[Technical explanation]

## Solution
[Code/config changes with examples]

## Prevention
[How to avoid in future]

## Related
[Links to related docs, issues, or ADRs]

Step 6: Cross-Reference

• •Link to related existing docs
• •If this is the 3rd+ instance of a pattern, create a pattern doc in docs/learnings/patterns/

Step 7: Offer Next Steps

✓ Documentation complete

File created: [path]

What's next?
1. Continue workflow (recommended)
2. Link related documentation
3. View documentation
4. Other

Categories for Learning Docs

Organized under docs/learnings/:

• •performance/ — N+1 queries, memory leaks, slow algorithms
• •security/ — Vulnerabilities, auth issues, data exposure
• •correctness/ — Logic errors, race conditions, data corruption
• •config/ — Configuration mistakes, environment issues
• •integration/ — External service issues, API changes
• •operations/ — Deployment issues, monitoring gaps

Quality Guidelines

Good documentation has:

• •✅ Exact error messages (copy-paste from output)
• •✅ Specific file/line references
• •✅ Observable symptoms (what you saw, not interpretations)
• •✅ Failed attempts documented (helps avoid wrong paths)
• •✅ Technical explanation (not just "what" but "why")
• •✅ Code examples (before/after if applicable)
• •✅ Prevention guidance

Avoid:

• •❌ Vague descriptions ("something was wrong")
• •❌ Missing technical details ("fixed the code")
• •❌ No context (which version? which file?)
• •❌ Just code dumps (explain why it works)