Compound Docs

compound-docs

Process

Single-file architecture -- one markdown file per problem in its symptom category directory (e.g., docs/solutions/performance-issues/n-plus-one-briefs.md), with YAML frontmatter for metadata.

Follow the 7-step documentation capture process. For full details, see documentation-process.md.

1. Detect confirmation -- Auto-invoke after "that worked", "it's fixed", etc. Skip trivial fixes. 2. Gather context -- Extract module, symptom, investigation attempts, root cause, solution, prevention. BLOCK if critical context missing. 3. Check existing docs -- Search docs/solutions/ for similar issues. If found, offer: new doc with cross-reference, update existing, or other. 4. Generate filename -- Format: [sanitized-symptom]-[module]-[YYYYMMDD].md 5. Validate YAML -- Run validate-frontmatter.sh against the file. If invalid, fix the frontmatter and re-run until it passes. 6. Create documentation -- Write file to docs/solutions/[category]/[filename].md using resolution-template.md. 7. Cross-reference -- Link related issues. Detect critical patterns (3+ similar issues).

---

Decision Menu

After successful documentation, present and WAIT for user response:

Solution documented

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

What's next?
1. Continue workflow (recommended)
2. Add to Required Reading - Promote to critical patterns
3. Link related issues - Connect to similar problems
4. Add to existing skill - Add to a learning skill
5. Create new skill - Extract into new learning skill
6. View documentation - See what was captured
7. Other

For detailed response handling, see documentation-process.md.

---

Success Criteria

• YAML frontmatter validated (all required fields, correct formats)
• File created in docs/solutions/[category]/[filename].md
• Enum values match schema exactly
• Code examples included in solution section
• Cross-references added if related issues found
• User presented with decision menu and action confirmed

---

References

• documentation-process.md - Full 7-step process with validation gates
• yaml-schema.md - YAML frontmatter schema and enum values
• quality-guidelines.md - Quality standards, execution rules, error handling
• example-scenario.md - Complete walkthrough of documenting an N+1 query fix
• resolution-template.md - Template for documentation files
• critical-pattern-template.md - Template for critical pattern entries
• validate-frontmatter.sh - Validate YAML frontmatter against schema

Integration

• /ia-compound-refresh command -- reviews docs/solutions/ for stale learnings

Critical Pattern Template

Use this template when adding a pattern to docs/solutions/patterns/critical-patterns.md:

---

N. [Pattern Name] (ALWAYS REQUIRED)

❌ WRONG ([Will cause X error])

```[language] [code showing wrong approach]

### ✅ CORRECT

[code showing correct approach]

**Why:** [Technical explanation of why this is required]

**Placement/Context:** [When this applies]

**Documented in:** `docs/solutions/[category]/[filename].md`

---

**Instructions:**
1. Replace N with the next pattern number
2. Replace [Pattern Name] with descriptive title
3. Fill in WRONG example with code that causes the problem
4. Fill in CORRECT example with the solution
5. Explain the technical reason in "Why"
6. Clarify when this pattern applies in "Placement/Context"
7. Link to the full troubleshooting doc where this was originally solved

Troubleshooting: [Clear Problem Title]

Problem

[1-2 sentence clear description of the issue and what the user experienced]

Environment

• Module: [Name or "System-wide"]
• Framework/Language Version: [e.g., Laravel 11.0, Python 3.12, Node 20.0]
• Affected Component: [e.g., "User model", "Payment service", "Auth controller"]
• Date: [YYYY-MM-DD when this was solved]

Symptoms

• [Observable symptom 1 - what the user saw/experienced]
• [Observable symptom 2 - error messages, visual issues, unexpected behavior]
• [Continue as needed - be specific]

What Didn't Work

Attempted Solution 1: [Description of what was tried]

• Why it failed: [Technical reason this didn't solve the problem]

Attempted Solution 2: [Description of second attempt]

• Why it failed: [Technical reason]

[Continue for all significant attempts that DIDN'T work]

[If nothing else was attempted first, write:] Direct solution: The problem was identified and fixed on the first attempt.

Solution

[The actual fix that worked - provide specific details]

Code changes (if applicable):

# Before (broken):
[Show the problematic code]

# After (fixed):
[Show the corrected code with explanation]

Database migration (if applicable):

# Migration change:
[Show what was changed in the migration]

Commands run (if applicable):

# Steps taken to fix:
[Commands or actions]

Why This Works

[Technical explanation of:] 1. What was the ROOT CAUSE of the problem? 2. Why does the solution address this root cause? 3. What was the underlying issue (API misuse, configuration error, version incompatibility, etc.)?

[Be detailed enough that future developers understand the "why", not just the "what"]

Prevention

[How to avoid this problem in future development:]

• [Specific coding practice, check, or pattern to follow]
• [What to watch out for]
• [How to catch this early]

Related Issues

[If any similar problems exist in docs/solutions/, link to them:]

• See also: another-related-issue.md
• Similar to: related-problem.md

[If no related issues, write:] No related issues documented yet.

Documentation Capture Process (Detailed)

<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: /ia-compound 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:

• Framework/language 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. 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.

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 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 patterns if applicable:

If this represents a common pattern (3+ similar issues):

# Add to docs/solutions/patterns/common-solutions.md
cat >> docs/solutions/patterns/common-solutions.md << 'EOF'

## [Pattern Name]

**Common symptom:** [Description]
**Root cause:** [Technical explanation]
**Solution pattern:** [General approach]

**Examples:**
- [Link to doc 1]
- [Link to doc 2]
- [Link to doc 3]
EOF

Critical Pattern Detection (Optional Proactive Suggestion):

If this issue has automatic indicators suggesting it might be critical:

• Severity: critical in YAML
• Affects multiple modules OR foundational stage (Stage 2 or 3)
• Non-obvious solution

Then in the decision menu, add a note suggesting it might be worth adding to Required Reading. But NEVER auto-promote. User decides via decision menu.

Template for critical pattern addition:

When user selects "Add to Required Reading", use the template from critical-pattern-template.md to structure the pattern entry. Number it sequentially based on existing patterns in docs/solutions/patterns/critical-patterns.md. </step>

</critical_sequence>

---

Decision Menu Response Handling

After successful documentation, present the decision menu and handle responses:

Option 1: Continue workflow - Return to calling skill/workflow. Documentation is complete.

Option 2: Add to Required Reading - Extract pattern, format as WRONG vs CORRECT with code examples, add to docs/solutions/patterns/critical-patterns.md, add cross-reference back to this doc.

Option 3: Link related issues - Prompt for doc to link, search docs/solutions/, add cross-reference to both docs.

Option 4: Add to existing skill - Prompt for skill name, determine which reference file to update, add link and brief description.

Option 5: Create new skill - Extract into new learning skill.

Option 6: View documentation - Display the created doc, then present decision menu again.

Option 7: Other - Ask what they'd like to do.

Example Scenario

User: "That worked! The N+1 query is fixed."

Skill activates:

1. Detect confirmation: "That worked!" triggers auto-invoke 2. Gather context:

• Module: Brief System
• Symptom: Brief generation taking >5 seconds, N+1 query when loading email threads
• Failed attempts: Added pagination (didn't help), checked background job performance
• Solution: Added eager loading with includes(:emails) on Brief model
• Root cause: Missing eager loading causing separate database query per email thread

3. Check existing: No similar issue found 4. Generate filename: n-plus-one-brief-generation-BriefSystem-20251110.md 5. Validate YAML:

   module: Brief System
   date: 2025-11-10
   problem_type: performance_issue
   component: database_model
   symptoms:
     - "N+1 query when loading email threads"
     - "Brief generation taking >5 seconds"
   root_cause: missing_include
   severity: high
   tags: [n-plus-one, eager-loading, performance]

Valid 6. Create documentation:

• docs/solutions/performance-issues/n-plus-one-brief-generation-BriefSystem-20251110.md

7. Cross-reference: None needed (no similar issues)

Output:

Solution documented

File created:
- docs/solutions/performance-issues/n-plus-one-brief-generation-BriefSystem-20251110.md

What's next?
1. Continue workflow (recommended)
2. Add to Required Reading - Promote to critical patterns (critical-patterns.md)
3. Link related issues - Connect to similar problems
4. Add to existing skill - Add to a learning skill (e.g., hotwire-native)
5. Create new skill - Extract into new learning skill
6. View documentation - See what was captured
7. Other

Quality Guidelines & Error Handling

Quality Guidelines

Good documentation has:

• Exact error messages (copy-paste from output)
• Specific file:line references
• Observable symptoms (what you saw, not interpretations)
• Failed attempts documented (helps avoid wrong paths)
• Technical explanation (not just "what" but "why")
• Code examples (before/after if applicable)
• Prevention guidance (how to catch early)
• Cross-references (related issues)

Avoid:

• Vague descriptions ("something was wrong")
• Missing technical details ("fixed the code")
• No context (which version? which file?)
• Just code dumps (explain why it works)
• No prevention guidance
• No cross-references

---

Execution Guidelines

MUST do:

• Validate YAML frontmatter (BLOCK if invalid per Step 5 validation gate)
• Extract exact error messages from conversation
• Include code examples in solution section
• Create directories before writing files (mkdir -p)
• Ask user and WAIT if critical context missing

MUST NOT do:

• Skip YAML validation (validation gate is blocking)
• Use vague descriptions (not searchable)
• Omit code examples or cross-references

---

Error Handling

Missing context:

• Ask user for missing details
• Don't proceed until critical info provided

YAML validation failure:

• Show specific errors
• Present retry with corrected values
• BLOCK until valid

Similar issue ambiguity:

• Present multiple matches
• Let user choose: new doc, update existing, or link as duplicate

Module not in modules documentation:

• Warn but don't block
• Proceed with documentation
• Suggest: "Add [Module] to modules documentation if not there"

YAML Frontmatter Schema

Schema specification for YAML frontmatter in solution documents.

Required Fields

• module (string): Module name (e.g., "EmailProcessing") or "System" for system-wide issues
• date (string): ISO 8601 date (YYYY-MM-DD)
• problem_type (enum): One of [build_error, test_failure, runtime_error, performance_issue, database_issue, security_issue, ui_bug, integration_issue, logic_error, developer_experience, workflow_issue, best_practice, documentation_gap]
• component (enum): One of [model, controller, view, service_object, background_job, database, frontend_component, api_endpoint, authentication, payments, development_workflow, testing_framework, documentation, tooling]
• symptoms (array): 1-5 specific observable symptoms
• root_cause (enum): One of [missing_association, missing_include, missing_index, wrong_api, scope_issue, thread_violation, async_timing, memory_leak, config_error, logic_error, test_isolation, missing_validation, missing_permission, missing_workflow_step, inadequate_documentation, missing_tooling, incomplete_setup]

• resolution_type (enum): One of [code_fix, migration, config_change, test_fix, dependency_update, environment_setup, workflow_improvement, documentation_update, tooling_addition, seed_data_update]
• severity (enum): One of [critical, high, medium, low]

Optional Fields

• framework_version (string): Framework or language version in X.Y.Z format
• tags (array): Searchable keywords (lowercase, hyphen-separated)

Validation Rules

1. All required fields must be present 2. Enum fields must match allowed values exactly (case-sensitive) 3. symptoms must be YAML array with 1-5 items 4. date must match YYYY-MM-DD format 5. framework_version (if provided) must match X.Y.Z format 6. tags should be lowercase, hyphen-separated

Example

---
module: Email Processing
date: 2025-11-12
problem_type: performance_issue
component: model
symptoms:
  - "N+1 query when loading email threads"
  - "Brief generation taking >5 seconds"
root_cause: missing_include
framework_version: 7.1.2
resolution_type: code_fix
severity: high
tags: [n-plus-one, eager-loading, performance]
---

Category Mapping

Based on problem_type, documentation is filed in:

• build_error → docs/solutions/build-errors/
• test_failure → docs/solutions/test-failures/
• runtime_error → docs/solutions/runtime-errors/
• performance_issue → docs/solutions/performance-issues/
• database_issue → docs/solutions/database-issues/
• security_issue → docs/solutions/security-issues/
• ui_bug → docs/solutions/ui-bugs/
• integration_issue → docs/solutions/integration-issues/
• logic_error → docs/solutions/logic-errors/
• developer_experience → docs/solutions/developer-experience/
• workflow_issue → docs/solutions/workflow-issues/
• best_practice → docs/solutions/best-practices/
• documentation_gap → docs/solutions/documentation-gaps/

ia-compound-docs Specification

Intent

ia-compound-docs is a workflow-class skill (a multi-step process producing concrete artifacts). Document solved problems for team reuse. Provides process knowledge for /ia-compound. Use when documenting a resolved issue, writing up lessons learned, capturing a post-mortem, adding to the knowledge base, or building searchable institutional knowledge after debugging.

Scope

In scope:

• Behaviors described in SKILL.md and routed via the should_trigger phrasings in distillery/tests/fixtures/triggers/ia-compound-docs.jsonl.
• Updates to runtime behavior, structure, trigger precision, references, and validation.

Out of scope:

• Acting as the runtime instructions themselves (those live in SKILL.md).
• Trigger phrasings already covered by adjacent ia-* skills (validate-plugin flags >70% description overlap as DUPLICATE_TRIGGER).
• <!-- to fill in: domain-specific exclusions when the skill drifts -->

Trigger Context

• Class: workflow
• Hook regex: plugins/whetstone/hooks/skill-patterns.sh -> SKILL_PATTERNS[ia-compound-docs]
• Common requests (from fixture should_trigger):
• "document the solution we found for the race condition"
• "capture the knowledge from debugging the cache invalidation bug"
• "write up the postmortem for the outage we just resolved"
• Should not trigger for (from fixture should_not_trigger):
• "write a new React hook for form state management"
• "configure the CI pipeline for the monorepo"
• "write the user-facing docs for this feature"

Source And Evidence Model

Authoritative sources:

• SKILL.md -- runtime instructions and reference routing.
• references/*.md -- bundled supplementary content (4 file(s)).
• distillery/tests/fixtures/triggers/ia-compound-docs.jsonl -- positive and negative trigger phrasings under regression test.
• plugins/whetstone/hooks/skill-patterns.sh -- regex pattern that fires this skill.
• distillery/.eval-data/ia-compound-docs/ -- harvested session examples (when present).

Data that must not be stored in this skill or its references:

• Secrets, credentials, tokens.
• Machine-specific filesystem paths (/home/..., /Users/..., ~/ai/...). The validator (MACHINE_PATH_LEAK) flags these as HIGH.
• Private URLs, customer data, or unredacted personal information.

Coverage matrix

Evaluation

Lightweight (run on every change):

python3 distillery/scripts/distiller.py validate-plugin --component ia-compound-docs
python3 distillery/scripts/distiller.py test-triggers --skill ia-compound-docs

Deeper (when behavior risk warrants):

python3 distillery/scripts/distiller.py dspy-eval ia-compound-docs
python3 distillery/scripts/distiller.py diagnose-negatives ia-compound-docs

Acceptance gates:

• validate-plugin --component ia-compound-docs returns 0 HIGH findings.
• test-triggers --skill ia-compound-docs returns F1 = 1.0 with floors of 5 should_trigger and 5 should_not_trigger.
• For dspy-eval, the composite score does not regress against the most recent saved baseline (see distillery/.eval-data/ia-compound-docs/history.json).

Known Limitations

<!-- to fill in over time as drift surfaces. Default rule: any time diagnose-negatives surfaces a recurring failure pattern, document it here so future maintainers understand the trade-off the current implementation accepts. -->

Maintenance Notes

• Update SKILL.md when the runtime workflow, branch conditions, or output contract changes.
• Update this SPEC.md when intent, scope, evidence model, evaluation gates, or maintenance expectations change.
• Update the trigger fixture when adding new positive phrasings, removing stale ones, or expanding scope (the 5/5 floor is a hard validator gate).
• Update the hook regex in skill-patterns.sh whenever fixture positives expose a missed phrasing; verify F1 = 1.0 with eval-triggers before committing.
• Run the full release pipeline via /release -- never bump versions or update CHANGELOG.md from a per-skill edit.