compound-engineering-pi 0.2.3

package/skills/compound-docs/SKILL.md

@@ -0,0 +1,511 @@
+---
+name: compound-docs
+description: Capture solved problems as categorized documentation with YAML frontmatter for fast lookup
+disable-model-invocation: true
+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:
+
+```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 [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:**
+
+```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/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 (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/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 "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:
+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 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:**
+
+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 (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

package/skills/compound-docs/assets/critical-pattern-template.md

@@ -0,0 +1,34 @@
+# 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
+```[language]
+[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

package/skills/compound-docs/assets/resolution-template.md

@@ -0,0 +1,93 @@
+---
+module: [Module name or "System" for system-wide]
+date: [YYYY-MM-DD]
+problem_type: [build_error|test_failure|runtime_error|performance_issue|database_issue|security_issue|ui_bug|integration_issue|logic_error]
+component: [rails_model|rails_controller|rails_view|service_object|background_job|database|frontend_stimulus|hotwire_turbo|email_processing|brief_system|assistant|authentication|payments]
+symptoms:
+  - [Observable symptom 1 - specific error message or behavior]
+  - [Observable symptom 2 - what user actually saw/experienced]
+root_cause: [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]
+rails_version: [7.1.2 - optional]
+resolution_type: [code_fix|migration|config_change|test_fix|dependency_update|environment_setup]
+severity: [critical|high|medium|low]
+tags: [keyword1, keyword2, keyword3]
+---
+
+# Troubleshooting: [Clear Problem Title]
+
+## Problem
+[1-2 sentence clear description of the issue and what the user experienced]
+
+## Environment
+- Module: [Name or "System-wide"]
+- Rails Version: [e.g., 7.1.2]
+- Affected Component: [e.g., "Email Processing model", "Brief System service", "Authentication 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):
+```ruby
+# Before (broken):
+[Show the problematic code]
+
+# After (fixed):
+[Show the corrected code with explanation]
+```
+
+**Database migration** (if applicable):
+```ruby
+# Migration change:
+[Show what was changed in the migration]
+```
+
+**Commands run** (if applicable):
+```bash
+# 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, Rails version issue, 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](../category/another-related-issue.md)
+- Similar to: [related-problem.md](../category/related-problem.md)
+
+[If no related issues, write:]
+No related issues documented yet.

package/skills/compound-docs/references/yaml-schema.md

@@ -0,0 +1,65 @@
+# YAML Frontmatter Schema
+
+**See `.claude/skills/codify-docs/schema.yaml` for the complete schema specification.**
+
+## 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 [rails_model, rails_controller, rails_view, service_object, background_job, database, frontend_stimulus, hotwire_turbo, email_processing, brief_system, assistant, 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
+
+- **rails_version** (string): Rails 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. rails_version (if provided) must match X.Y.Z format
+6. tags should be lowercase, hyphen-separated
+
+## Example
+
+```yaml
+---
+module: Email Processing
+date: 2025-11-12
+problem_type: performance_issue
+component: rails_model
+symptoms:
+  - "N+1 query when loading email threads"
+  - "Brief generation taking >5 seconds"
+root_cause: missing_include
+rails_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/`