/compound-docs

name: compound-docs
description: Capture solved problems as categorized documentation with YAML frontmatter for fast lookup
allowed-tools:
  - Read # Parse conversation context
  - Write # Create resolution docs
  - Bash # Create directories
  - Grep # Search existing docs
preconditions:
  - Problem has been solved (not in-progress)
  - Solution has been verified working

compound-docs Skill

**Purpose:** Automatically document solved problems to build searchable institutional knowledge with category-based organization (enum-validated problem types).

Overview

This skill captures problem solutions immediately after confirmation, creating structured documentation that serves as a searchable knowledge base for future sessions.

**Organization:** Single-file architecture - each problem documented as one markdown file in its symptom category directory (e.g., `docs/solutions/performance-issues/n-plus-one-briefs.md`). Files use YAML frontmatter for metadata and searchability.

---

<critical_sequence name="documentation-capture" enforce_order="strict">

7-Step Process

<step number="1" required="true">

Step 1: Detect Confirmation

**Auto-invoke after phrases:**

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

**OR manual:** `/doc-fix` command

**Non-trivial problems only:**

• Multiple investigation attempts needed
• Tricky debugging that took time
• Non-obvious solution
• Future sessions would benefit

**Skip documentation for:**

• Simple typos
• Obvious syntax errors
• Trivial fixes immediately corrected

</step>

<step number="2" required="true" depends_on="1">

Step 2: Gather Context

Extract from conversation history:

**Required information:**

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

**Environment details:**

• Rails version
• Stage (0-6 or post-implementation)
• OS version
• File/line references

**BLOCKING REQUIREMENT:** If critical context is missing (module name, exact error, stage, or resolution steps), ask user and WAIT for response before proceeding to Step 3:

I need a few details to document this properly:

1. Which module had this issue? [ModuleName]
2. What was the exact error message or symptom?
3. What stage were you in? (0-6 or post-implementation)

[Continue after user provides details]

</step>

<step number="3" required="false" depends_on="2">

Step 3: Check Existing Docs

Search docs/solutions/ for similar issues:

# Search by error message keywords
grep -r "exact error phrase" docs/solutions/

# Search by symptom category
ls docs/solutions/[category]/

**IF similar issue found:**

THEN present decision options:

Found similar issue: docs/solutions/[path]

What's next?
1. Create new doc with cross-reference (recommended)
2. Update existing doc (only if same root cause)
3. Other

Choose (1-3): _

WAIT for user response, then execute chosen action.

**ELSE** (no similar issue found):

Proceed directly to Step 4 (no user interaction needed). </step>

<step number="4" required="true" depends_on="2">

Step 4: Generate Filename

Format: `[sanitized-symptom]-[module]-[YYYYMMDD].md`

**Sanitization rules:**

• Lowercase
• Replace spaces with hyphens
• Remove special characters except hyphens
• Truncate to reasonable length (< 80 chars)

**Examples:**

• `missing-include-BriefSystem-20251110.md`
• `parameter-not-saving-state-EmailProcessing-20251110.md`
• `webview-crash-on-resize-Assistant-20251110.md`

</step>

<step number="5" required="true" depends_on="4" blocking="true">

Step 5: Validate YAML Schema

**CRITICAL:** All docs require validated YAML frontmatter with enum validation.

<validation_gate name="yaml-schema" blocking="true">

**Validate against schema:** Load `schema.yaml` and classify the problem against the enum values defined in [yaml-schema.md](./references/yaml-schema.md). Ensure all required fields are present and match allowed values exactly.

**BLOCK if validation fails:**

❌ YAML validation failed

Errors:
- problem_type: must be one of schema enums, got "compilation_error"
- severity: must be one of [critical, high, medium, low], got "invalid"
- symptoms: must be array with 1-5 items, got string

Please provide corrected values.

**GATE ENFORCEMENT:** Do NOT proceed to Step 6 (Create Documentation) until YAML frontmatter passes all validation rules defined in `schema.yaml`.

</validation_gate> </step>

<step number="6" required="true" depends_on="5">

Step 6: Create Documentation

**Determine category from problem_type:** Use the category mapping defined in [yaml-schema.md](./references/yaml-schema.md) (lines 49-61).

**Create documentation file:**

PROBLEM_TYPE="[from validated YAML]"
CATEGORY="[mapped from problem_type]"
FILENAME="[generated-filename].md"
DOC_PATH="docs/solutions/${CATEGORY}/${FILENAME}"

# Create directory if needed
mkdir -p "docs/solutions/${CATEGORY}"

# Write documentation using template from assets/resolution-template.md
# (Content populated with Step 2 context and validated YAML frontmatter)

**Result:**

• Single file in category directory
• Enum validation ensures consistent categorization

**Create documentation:** Populate the structure from `assets/resolution-template.md` with context gathered in Step 2 and validated YAML frontmatter from Step 5. </step>

<step number="7" required="false" depends_on="6">

Step 7: Cross-Reference & Critical Pattern Detection

If similar issues found in Step 3:

**Update existing doc:**

# Add Related Issues link to similar doc
echo "- See also: [$FILENAME]($REAL_FILE)" >> [similar-doc.md]

**Update new doc:** Already includes cross-reference from Step 6.

**Update patterns if app