compound-docs

Each documented solution compounds your team's knowledge. The first time you solve a problem takes research. Document it, and the next occurrence takes minutes. Knowledge compounds.

This skill is inspired by Every.to's compound-engineering plugin.

Auto-Invoke Triggers

This skill auto-triggers when the user says:

• "that worked"
• "it's fixed"
• "working now"
• "problem solved"
• "that did it"

Manual command: /compound

Workflow

Step 1: Detect Trigger

When a trigger phrase is detected or /compound is invoked:

1. Confirm the problem is actually solved (not still in progress)
2. Check if the fix is worth documenting

Skip documentation for trivial fixes:

• Simple typos
• Obvious syntax errors (missing semicolon, bracket)
• Single-line fixes that were immediately obvious

If skipping, briefly explain why: "This was a simple typo fix - skipping documentation."

Step 2: Gather Context

Read schema.yaml to get valid enum values, then extract from the conversation:

If a value doesn't exist in schema.yaml:

1. Add the new value to the appropriate enum in schema.yaml
2. If it's a new category, create the directory: mkdir -p {output_dir}/{new-category}

If critical info is missing, ask:

To document this fix, I need a few details:

1. Category: What type of issue was this?
   [list current values from schema.yaml]
   Or suggest a new category if none fit

Step 3: Check for Similar Issues

Before creating a new doc, search for similar existing issues:

1. Keyword match - Search {output_dir}/ for error message fragments or key symptom phrases
2. File path match - Check if the same files are involved in existing docs
3. Import/dependency match - Check if the same libraries or modules are mentioned

# Example searches
grep -rl "ErrorMessage" docs/solutions/
grep -l "path/to/file" docs/solutions/**/*.md

If potential matches found:

Found potentially related issues:
- docs/solutions/integration/api-timeout-20250102.md
- docs/solutions/integration/auth-header-missing-20250105.md

Are any of these the same or related issue? (y/n)

If related, add to the related field in frontmatter.

Step 4: Create Documentation

Validate against schema.yaml:

1. Read schema.yaml for current valid enum values
2. Ensure all required fields are present
3. Ensure enum values exist (or add them first)

Generate filename:

• Format: {sanitized-symptom}-{YYYYMMDD}.md
• Sanitize: lowercase, replace spaces with hyphens, remove special chars, truncate to 80 chars

Create file at: {output_dir}/{category}/{filename}

Ensure directory exists:

mkdir -p {output_dir}/{category}

Use the Solution Doc Template below.

Step 5: Pattern Promotion

After creating the doc, check if this issue has occurred multiple times.

If similar issues >= threshold (default: 2):

This issue has occurred {N} times:
- {link to issue 1}
- {link to issue 2}
- {link to current issue}

Promote to patterns.md? This surfaces it prominently for future sessions.
1. Yes - Add to patterns
2. No - Keep as regular doc only

If yes: Append to {output_dir}/patterns.md using the Pattern Template below.

Solution Doc Template

---
date: {YYYY-MM-DD}
category: {category}
symptoms:
  - {symptom 1}
  - {symptom 2}
component: {component}
root_cause: {root_cause}
tags: [{keyword1}, {keyword2}]
related: []
---

# {Problem Title}

## Problem

{1-2 sentence description of what went wrong}

## Symptoms

- {What you observed - error messages, behavior, etc.}

## What Didn't Work

- {Attempted solution 1} - {Why it failed}
- {Attempted solution 2} - {Why it failed}

## Solution

{Description of the fix}

```{language}
# Before (broken)
{code before}

# After (fixed)
{code after}

Why This Works

{Technical explanation of the root cause and why the solution addresses it}

Prevention

{How to avoid this in the future - tests, linting rules, patterns to follow}

## Pattern Template

When adding to `patterns.md`:

```markdown
## {Pattern Name}

**Occurrences:** {N} times ({link1}, {link2}, ...)

### WRONG

```{language}
{code that causes the problem}

CORRECT

{code that fixes it}

Why: {Technical explanation}

When this applies: {Context or conditions when this pattern is relevant}

## Integration

### Reference in AGENTS.md

Add to your project's AGENTS.md to ensure patterns are checked:

```markdown
## Required Reading

Before making changes, review known patterns:
- [Solution Patterns](docs/solutions/patterns.md)

Consuming Solutions

Other workflows can discover and apply documented solutions:

Search by keyword:

grep -rl "keyword" docs/solutions/

Search by category:

ls docs/solutions/deployment/

Search by tag:

grep -l "tags:.*docker" docs/solutions/**/*.md

patterns.md is the primary integration point - check it first for critical patterns before making changes.

Example Scenario

User: "That worked! The Docker build was failing because of the cache issue."

Agent response:

Great! Let me document this fix.

**Reading schema.yaml...**
Current categories: developer-experience, deployment, ui, integration, performance, testing
Current components: (none yet)
Current root_causes: (none yet)

**Gathering context...**

From our conversation:
- Symptom: Docker build failing with "layer not found" error
- Category: deployment
- Component: docker (adding to schema.yaml)
- Root cause: stale-cache (adding to schema.yaml)
- Solution: Added `--no-cache` flag and updated base image tag
- Prevention: Pin base image versions, use `docker system prune` periodically

**Updating schema.yaml...**
Added 'docker' to component.values
Added 'stale-cache' to root_cause.values

**Checking for similar issues...**
No related issues found.

**Creating documentation...**
Created: docs/solutions/deployment/docker-layer-not-found-20250106.md

Documentation complete.