compound

name	compound
description	Document solved problems to compound team knowledge. Creates categorized docs with YAML frontmatter. Triggers on "that worked", "it's fixed", "compound".
allowed-tools	["Read","Write","Bash","Grep","Task","AskUserQuestion"]

Compound Skill

Document solved problems to build searchable institutional knowledge.

Why "compound"? Each documented solution compounds your team's knowledge like compound interest. First time solving a problem takes research. Document it, and the next occurrence takes minutes.

Compounding vs Compaction: Flywheel uses two strategies (see README):

• Compaction = Reduce context mid-work (atomic progress.json checkpoints, structured spec.json.context arrays)
• Compounding = Accumulate knowledge post-work (this skill)

Preconditions:

• Problem has been solved (not in-progress)
• Solution has been verified working

Organization: Single-file per problem in category directory (e.g., docs/solutions/performance-issues/n-plus-one-query.md).

---

Step 1: Detect Confirmation

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

OR manual: /compound command

Non-trivial problems only:

• Multiple investigation attempts needed
• Tricky debugging
• Non-obvious solution

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

Additional categories:

• pattern = Successful approach worth reusing → docs/solutions/patterns/
• mistake = Failed approach with prevention guidance → docs/solutions/mistakes/

---

Step 1.5: 3-Strike Integration

When invoked after 3-Strike escalation (error resolved with user help), capture:

• What failed: All 3 attempts (sanitized - remove credentials, API keys, PII, internal URLs)
• Why it failed: Root cause analysis
• What worked: User-provided solution
• How to prevent: Future guidance

This creates institutional memory from hard-won debugging sessions.

---

Step 2: Gather Context

Extract from conversation history:

• Module - Which component had the problem
• Symptom - Exact error messages, observable behavior
• Investigation - What was tried, what didn't work
• Root cause - Technical explanation
• Solution - Code/config changes that fixed it
• Prevention - How to avoid in future

If critical context missing, ask user:

I need a few details to document this:
1. Which module/component?
2. What was the exact error?
3. What environment?

---

Step 2.5: First-Use Discoverability Check

On first compound creation in a repo, offer to add a one-line pointer to docs/solutions/ in AGENTS.md or CLAUDE.md so future agents find the knowledge store.

Detection: ls docs/solutions/ 2>/dev/null | wc -l returns 0 AND neither AGENTS.md nor CLAUDE.md has a grep hit for docs/solutions.

If detected, AskUserQuestion: "No existing solutions directory detected. Add a one-line pointer to docs/solutions/ in AGENTS.md or CLAUDE.md so future agents find it?"

• Options: Add to AGENTS.md / Add to CLAUDE.md / Skip

On yes, Edit the chosen file to append: Past solutions & compound learnings live in `docs/solutions/`.

---

Step 3: Check Existing Docs

grep -r "exact error phrase" docs/solutions/

If similar found: Ask whether to create new doc with cross-reference or update existing.

If none: Proceed.

---

Step 4: Sanitize & Validate

Before documenting, sanitize sensitive data:

• Remove credentials, API keys, secrets
• Remove PII (names, emails, IDs)
• Replace internal URLs with [internal-url]
• Generalize environment-specific paths

Then validate against references/yaml-schema.md:

• All required fields present
• Enum values match exactly
• symptoms is array (1-5 items)

Determine category from problem_type, create file:

mkdir -p "docs/solutions/${CATEGORY}"

Write using template from references/resolution-template.md.

---

Step 5: Optional Specialized Review

For complex issues, invoke relevant reviewer:

Problem Type	Reviewer
performance_issue	reviewer-performance
database_issue	reviewer-data-integrity

Only if the problem was particularly tricky or affects critical systems.

---

Step 5.5: Standards Inference

After documenting the solution, check if this pattern generalizes:

# Search for solutions with similar tags or problem types
grep -rl "<root-cause-keyword>" docs/solutions/ | head -5

If 2+ solutions share the same root cause type or pattern (e.g., same type of fix in the same component area), suggest creating a standard:

AskUserQuestion: "This pattern appears in [N] solutions ([list filenames]). Capture as a reusable standard?"

• Yes — Draft standard from the shared pattern, write to docs/standards/<pattern-name>.md per the format in docs/standards/README.md, user confirms content
• Skip (Recommended) — Continue without creating a standard

Only suggest when the pattern is clearly reusable, not when solutions happen to touch the same file.

---

Step 6: Present Results

Per references/decision-menu.md:

✓ Solution documented

File: docs/solutions/[category]/[filename].md

What's next?
1. Continue workflow (recommended)
2. Add to Required Reading
3. Link related issues
4. View documentation
5. Other

---

Error Handling

• Missing context: Ask user, wait
• YAML validation failure: Show errors, block until valid
• Similar issue found: Present options

---

Anti-Patterns

• Document trivial fixes
• Document without verified solution
• Vague docs without code examples
• Skip cross-references

---

Detailed References

• references/yaml-schema.md - YAML fields, enums, category mapping
• references/resolution-template.md - File template, filename rules
• references/decision-menu.md - Post-documentation options