Compound Docs: Solution Document Management

You are managing the project's solution documentation in docs/solutions/. This skill ensures documents follow the correct schema and are properly organized.

Auto-Invocation Triggers

This skill activates automatically when:

• •Creating a new file in docs/solutions/
• •Editing an existing solution document
• •Running /compound to capture a learning

Schema Validation

All solution documents must have valid YAML frontmatter matching this schema:

Required Fields

---
module: string           # Affected module/area (e.g., "authentication", "database")
date: YYYY-MM-DD        # Date the solution was documented
problem_type: enum      # One of the defined problem types
symptoms:               # List of observable symptoms
  - string
root_cause: enum        # One of the defined root causes
severity: enum          # One of: critical, high, medium, low
---

problem_type (required)

One of:

• •build-error - Compilation, bundling, dependency issues
• •test-failure - Test suite failures
• •runtime-error - Exceptions, crashes at runtime
• •performance - Slow operations, memory issues
• •database - Query issues, migrations, data integrity
• •security - Vulnerabilities, auth issues
• •integration - Third-party API, service communication
• •logic-error - Incorrect business logic
• •workflow - Development process, tooling issues

root_cause (required)

One of:

• •missing-dependency - Package not installed or wrong version
• •config-error - Configuration mistake
• •race-condition - Timing/concurrency issue
• •incorrect-assumption - Wrong understanding of behavior
• •api-change - External API changed
• •missing-validation - Input not validated
• •resource-exhaustion - Memory, connections, etc.
• •logic-flaw - Bug in business logic
• •documentation-gap - Missing or wrong docs
• •other - Doesn't fit other categories

severity (required)

• •critical - Production outage, data loss, security breach
• •high - Major feature broken, significant user impact
• •medium - Feature degraded, workaround exists
• •low - Minor issue, cosmetic, edge case

Optional Fields

tags:                   # Additional searchable tags
  - string
related:                # Links to related solutions/issues
  - string
prevention:             # How to prevent recurrence
  - string

Directory Structure

Solutions are organized by problem type:

docs/solutions/
├── build-errors/
├── test-failures/
├── runtime-errors/
├── performance/
├── database/
├── security/
├── integration/
├── logic-errors/
└── workflow/

Filename Convention

[symptom-slug]-[module]-YYYYMMDD.md

Examples:

• •import-error-auth-20260124.md
• •n-plus-one-query-orders-20260115.md
• •jwt-expiry-api-20260110.md

Rules:

• •All lowercase
• •Hyphens for spaces
• •Symptom keyword first (searchable)
• •Module second (context)
• •Date last (versioning)

Document Template

---
module: [module-name]
date: [YYYY-MM-DD]
problem_type: [type]
symptoms:
  - [symptom 1]
  - [symptom 2]
root_cause: [cause]
severity: [level]
tags:
  - [tag1]
  - [tag2]
---

# [Descriptive Title]

## Symptom

[What was observed - error messages, unexpected behavior]

## Investigation

[How the problem was diagnosed - what was checked, what was ruled out]

## Root Cause

[The actual underlying issue]

## Solution

[What fixed it - specific code changes, config updates]

```[language]
// Code example if applicable

Prevention

[How to avoid this in the future - tests, validations, patterns]

Related

• •[Link to related solution]
• •[Link to issue/PR]

## Validation Workflow

When creating or editing a solution document:

1. **Check Frontmatter**
   - All required fields present
   - Enum values are valid
   - Date format is correct

2. **Check Structure**
   - File is in correct category directory
   - Filename follows convention
   - All template sections present

3. **Report Issues**

Validation Issues:

• • Missing required field: severity
• • Invalid problem_type: "error" (should be one of: build-error, test-failure, ...)
• • File should be in docs/solutions/database/ based on problem_type

4. **Offer Fixes**
- Auto-fix obvious issues (date format, directory)
- Ask for input on semantic issues (problem_type, root_cause)

## Search Support

Help users find existing solutions:

```bash
# By module
grep -r "module: auth" docs/solutions/ --include="*.md" -l

# By problem type
grep -r "problem_type: test-failure" docs/solutions/ --include="*.md" -l

# By keyword in symptoms
grep -ri "timeout" docs/solutions/ --include="*.md" -l

# By date range
find docs/solutions/ -name "*2026*.md" -type f

Maintenance Tasks

Periodic maintenance for the solutions database:

1. •Check for duplicates: Similar symptoms in different docs
2. •Update stale solutions: Old solutions may need updating
3. •Add cross-references: Link related solutions
4. •Verify consistency: Ensure all docs match current schema