compound-docs

salavender's avatarfrom salavender

Document solved problems for knowledge persistence

⭐29stars🔀7forks📁View on GitHub🕐Updated Dec 27, 2025
[Knowledge Base]

When & Why to Use This Skill

The Compound Documentation Skill is a specialized tool designed for knowledge persistence and systematic solution tracking. It enables AI agents and developers to document solved problems, capture investigation journeys—including failed attempts and incorrect assumptions—and promote recurring issues into standardized patterns. By leveraging structured YAML frontmatter and a dedicated documentation directory, it ensures that technical insights are searchable, reusable, and validated, effectively building a long-term organizational memory that reduces redundant troubleshooting.

Use Cases

  • Technical Troubleshooting: Documenting the root cause and resolution of complex software bugs to prevent future team members or AI sessions from repeating the same investigation steps.
  • Pattern Recognition & Promotion: Identifying recurring issues that have occurred multiple times and formalizing them into 'Critical Patterns' to establish standardized best practices.
  • Failure Analysis & Learning: Recording failed hypotheses and key breakthroughs during an investigation to provide a comprehensive learning path and avoid repeating past mistakes.
  • Knowledge Handoff: Ensuring seamless knowledge transfer between different AI agent sessions or development teams by providing a searchable, schema-validated database of historical solutions.
namecompound-docs
descriptionDocument solved problems for knowledge persistence

Compound Documentation Skill

Manages solution documentation in docs/solutions/ for knowledge persistence across sessions.

Overview

When you solve a problem, document it so the solution can be found and reused later.

What do you want to do?

  1. Document a solution → Use /compound workflow
  2. Find existing solutions → See "Searching Solutions" below
  3. Promote to pattern → See "Pattern Promotion" below
  4. Validate schema → See "YAML Validation" below

Instrumentation

# Log usage when using this skill
./scripts/log-skill.sh "compound-docs" "manual" "$$"

Searching Solutions

# Search by keyword
grep -r "keyword" docs/solutions/

# Search by tag
grep -l "tags:.*performance" docs/solutions/**/*.md

# Search by problem type
ls docs/solutions/performance-issues/

Pattern Promotion

When an issue occurs 3+ times:

  1. Search for similar solutions:

    grep -r "similar terms" docs/solutions/

  2. Add to critical patterns:

    # Edit docs/solutions/patterns/critical-patterns.md

  3. Format:

    ### Pattern #{N}: {Name}

**Problem:** {What goes wrong}

**❌ WRONG:**
```code
{incorrect}

    ✅ CORRECT:

    {correct}

YAML Validation

All solutions must have valid frontmatter:

---
date: "YYYY-MM-DD"
problem_type: "{from schema.yaml}"
severity: "critical|high|medium|low"
symptoms:
  - "symptom 1"
root_cause: "{from schema.yaml}"
tags:
  - tag1
---

See docs/solutions/schema.yaml for valid enum values.

Documenting Failures & Learnings

When documenting solutions, capture the full journey:

What to Include

  • ✅ Failed attempts with explanations
  • ✅ Incorrect assumptions and corrections
  • ✅ Key insights from mistakes
  • ✅ Course corrections and why
  • ✅ Time investment (helps prioritize future similar issues)

Example Pattern

## Investigation Steps

| Attempt | Hypothesis | Result |
|---------|------------|--------|
| 1. Check API logs | API might be timing out | ❌ No timeouts found |
| 2. Review database queries | N+1 query suspected | ❌ Queries were optimized |
| 3. Check cache invalidation | Cache might be stale | ✅ Found cache not clearing |

## Lessons Learned

### Mistakes Made
- **Assumption:** Assumed the API was the bottleneck
  - **Why wrong:** Didn't check cache layer first
  - **Correction:** Should always check cache before API

### Key Breakthrough
- **Insight:** Realized cache invalidation logic was only running on UPDATE, not DELETE
  - **Impact:** Led directly to the solution

[!TIP] Document the journey, not just the destination. Future readers learn from understanding WHY failed approaches didn't work.

References

  • Schema: docs/solutions/schema.yaml
  • Template: docs/solutions/templates/solution-template.md
  • Patterns: docs/solutions/patterns/critical-patterns.md