[2.9.0] Rename plugin to compound-engineering

BREAKING: Plugin renamed from compounding-engineering to compound-engineering. Users will need to reinstall with the new name: claude /plugin install compound-engineering Changes: - Renamed plugin directory and all references - Updated documentation counts (24 agents, 19 commands) - Added julik-frontend-races-reviewer to docs 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-12-02 17:32:04 -08:00
parent 4b49e5344d
commit 6c5b3e40db
121 changed files with 136 additions and 117 deletions
--- a/plugins/compound-engineering/skills/compound-docs/SKILL.md
+++ b/plugins/compound-engineering/skills/compound-docs/SKILL.md
@@ -0,0 +1,510 @@
+---
+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 CORA module 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:
+
+```bash
+# 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 `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, moderate, minor], got "high"
+- 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 `references/yaml-schema.md` (lines 49-61).
+
+**Create documentation file:**
+
+```bash
+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:**
+
+```bash
+# 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 applicable:**
+
+If this represents a common pattern (3+ similar issues):
+
+```bash
+# 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/cora-critical-patterns.md`.
+</step>
+
+</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 (cora-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:
+1. Extract pattern from the documentation
+2. Format as ❌ WRONG vs ✅ CORRECT with code examples
+3. Add to `docs/solutions/patterns/cora-critical-patterns.md`
+4. Add cross-reference back to this doc
+5. 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:
+1. Prompt: "Which skill? (hotwire-native, etc.)"
+2. Determine which reference file to update (resources.md, patterns.md, or examples.md)
+3. Add link and brief description to appropriate section
+4. Confirm: "✓ Added to [skill-name] skill in [file]"
+
+Example: For Hotwire Native Tailwind variants solution:
+- Add to `hotwire-native/references/resources.md` under "CORA-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:
+1. Prompt: "What should the new skill be called? (e.g., stripe-billing, email-processing)"
+2. Run `python3 .claude/skills/skill-creator/scripts/init_skill.py [skill-name]`
+3. Create initial reference files with this solution as first example
+4. 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 CORA-MODULES.md:**
+
+- Warn but don't block
+- Proceed with documentation
+- Suggest: "Add [Module] to CORA-MODULES.md 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:**
+
+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:**
+   ```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
+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 (cora-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