compound-docs

compound-docs

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 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 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] 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). 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 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> Determine category from problem_type: Use the category mapping defined in 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. If similar issues found in Step 3: Update existing doc: # Add Related Issues link to similar doc echo "- See also: $FILENAME" >> [similar-doc.md] Update new doc: Already includes cross-reference from Step 6. 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 (Step 8), add a note: 💡 This might be worth adding to Required Reading (Option 2) But NEVER auto-promote. User decides via decision menu (Option 2). Template for critical pattern addition: When user selects Option 2 (Add to Required Reading), use the template from assets/critical-pattern-template.md to structure the pattern entry. Number it sequentially based on existing patterns in docs/solutions/patterns/critical-patterns.md. </critical_sequence> <decision_gate name="post-documentation" wait_for_user="true"> Decision Menu After Capture After successful documentation, present options 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 (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 Handle responses: Option 1: Continue workflow Return to calling skill/workflow Documentation is complete Option 2: Add to Required Reading ⭐ PRIMARY PATH FOR CRITICAL PATTERNS User selects this when: System made this mistake multiple times across different modules Solution is non-obvious but must be followed every time Foundational requirement (Rails, Rails API, threading, etc.) Action: Extract pattern from the documentation Format as ❌ WRONG vs ✅ CORRECT with code examples Add to docs/solutions/patterns/critical-patterns.md Add cross-reference back to this doc Confirm: "✓ Added to Required Reading. All subagents will see this pattern before code generation." Option 3: Link related issues Prompt: "Which doc to link? (provide filename or describe)" Search docs/solutions/ for the doc Add cross-reference to both docs Confirm: "✓ Cross-reference added" Option 4: Add to existing skill User selects this when the documented solution relates to an existing learning skill: Action: Prompt: "Which skill? (hotwire-native, etc.)" Determine which reference file to update (resources.md, patterns.md, or examples.md) Add link and brief description to appropriate section Confirm: "✓ Added to [skill-name] skill in [file]" Example: For Hotwire Native Tailwind variants solution: Add to hotwire-native/references/resources.md under "Project-Specific Resources" Add to hotwire-native/references/examples.md with link to solution doc Option 5: Create new skill User selects this when the solution represents the start of a new learning domain: Action: Prompt: "What should the new skill be called? (e.g., stripe-billing, email-processing)" Run python3 .claude/skills/skill-creator/scripts/init_skill.py [skill-name] Create initial reference files with this solution as first example Confirm: "✓ Created new [skill-name] skill with this solution as first example" Option 6: View documentation Display the created documentation Present decision menu again Option 7: Other Ask what they'd like to do </decision_gate> <integration_protocol> Integration Points Invoked by: /compound command (primary interface) Manual invocation in conversation after solution confirmed Can be triggered by detecting confirmation phrases like "that worked", "it's fixed", etc. Invokes: None (terminal skill - does not delegate to other skills) Handoff expectations: All context needed for documentation should be present in conversation history before invocation. </integration_protocol> <success_criteria> Success Criteria Documentation is successful when ALL of the following are true: ✅ YAML frontmatter validated (all required fields, correct formats) ✅ File created in docs/solutions/[category]/[filename].md ✅ Enum values match schema.yaml exactly ✅ Code examples included in solution section ✅ Cross-references added if related issues found ✅ User presented with decision menu and action confirmed </success_criteria> 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" 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 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 Example Scenario User: "That worked! The N+1 query is fixed." Skill activates: Detect confirmation: "That worked!" triggers auto-invoke 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 Check existing: No similar issue found Generate filename: n-plus-one-brief-generation-BriefSystem-20251110.md Validate YAML: module: Brief System date: 2025-11-10 problem_type: performance_issue component: rails_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 Create documentation: docs/solutions/performance-issues/n-plus-one-brief-generation-BriefSystem-20251110.md 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 Future Enhancements Not in Phase 7 scope, but potential: Search by date range Filter by severity Tag-based search interface Metrics (most common issues, resolution time) Export to shareable format (community knowledge sharing) Import community solutions Weekly Installs1.4KRepositoryeveryinc/compou…g-pluginGitHub Stars10.5KFirst SeenJan 20, 2026Security AuditsGen Agent Trust HubPassSocketPassSnykPassInstalled onopencode1.1Kcodex1.1Kgemini-cli1.1Kgithub-copilot1.1Kamp1.1Kkimi-cli1.1K