compound-engineering-pi 0.2.3

package/plugins/compound-engineering/skills/brainstorming/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: brainstorming
+description: This skill should be used before implementing features, building components, or making changes. It guides exploring user intent, approaches, and design decisions before planning. Triggers on "let's brainstorm", "help me think through", "what should we build", "explore approaches", ambiguous feature requests, or when the user's request has multiple valid interpretations that need clarification.
+---
+
+# Brainstorming
+
+This skill provides detailed process knowledge for effective brainstorming sessions that clarify **WHAT** to build before diving into **HOW** to build it.
+
+## When to Use This Skill
+
+Brainstorming is valuable when:
+- Requirements are unclear or ambiguous
+- Multiple approaches could solve the problem
+- Trade-offs need to be explored with the user
+- The user hasn't fully articulated what they want
+- The feature scope needs refinement
+
+Brainstorming can be skipped when:
+- Requirements are explicit and detailed
+- The user knows exactly what they want
+- The task is a straightforward bug fix or well-defined change
+
+## Core Process
+
+### Phase 0: Assess Requirement Clarity
+
+Before diving into questions, assess whether brainstorming is needed.
+
+**Signals that requirements are clear:**
+- User provided specific acceptance criteria
+- User referenced existing patterns to follow
+- User described exact behavior expected
+- Scope is constrained and well-defined
+
+**Signals that brainstorming is needed:**
+- User used vague terms ("make it better", "add something like")
+- Multiple reasonable interpretations exist
+- Trade-offs haven't been discussed
+- User seems unsure about the approach
+
+If requirements are clear, suggest: "Your requirements seem clear. Consider proceeding directly to planning or implementation."
+
+### Phase 1: Understand the Idea
+
+Ask questions **one at a time** to understand the user's intent. Avoid overwhelming with multiple questions.
+
+**Question Techniques:**
+
+1. **Prefer multiple choice when natural options exist**
+   - Good: "Should the notification be: (a) email only, (b) in-app only, or (c) both?"
+   - Avoid: "How should users be notified?"
+
+2. **Start broad, then narrow**
+   - First: What is the core purpose?
+   - Then: Who are the users?
+   - Finally: What constraints exist?
+
+3. **Validate assumptions explicitly**
+   - "I'm assuming users will be logged in. Is that correct?"
+
+4. **Ask about success criteria early**
+   - "How will you know this feature is working well?"
+
+**Key Topics to Explore:**
+
+| Topic | Example Questions |
+|-------|-------------------|
+| Purpose | What problem does this solve? What's the motivation? |
+| Users | Who uses this? What's their context? |
+| Constraints | Any technical limitations? Timeline? Dependencies? |
+| Success | How will you measure success? What's the happy path? |
+| Edge Cases | What shouldn't happen? Any error states to consider? |
+| Existing Patterns | Are there similar features in the codebase to follow? |
+
+**Exit Condition:** Continue until the idea is clear OR user says "proceed" or "let's move on"
+
+### Phase 2: Explore Approaches
+
+After understanding the idea, propose 2-3 concrete approaches.
+
+**Structure for Each Approach:**
+
+```markdown
+### Approach A: [Name]
+
+[2-3 sentence description]
+
+**Pros:**
+- [Benefit 1]
+- [Benefit 2]
+
+**Cons:**
+- [Drawback 1]
+- [Drawback 2]
+
+**Best when:** [Circumstances where this approach shines]
+```
+
+**Guidelines:**
+- Lead with a recommendation and explain why
+- Be honest about trade-offs
+- Consider YAGNI—simpler is usually better
+- Reference codebase patterns when relevant
+
+### Phase 3: Capture the Design
+
+Summarize key decisions in a structured format.
+
+**Design Doc Structure:**
+
+```markdown
+---
+date: YYYY-MM-DD
+topic: <kebab-case-topic>
+---
+
+# <Topic Title>
+
+## What We're Building
+[Concise description—1-2 paragraphs max]
+
+## Why This Approach
+[Brief explanation of approaches considered and why this one was chosen]
+
+## Key Decisions
+- [Decision 1]: [Rationale]
+- [Decision 2]: [Rationale]
+
+## Open Questions
+- [Any unresolved questions for the planning phase]
+
+## Next Steps
+→ `/workflows:plan` for implementation details
+```
+
+**Output Location:** `docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md`
+
+### Phase 4: Handoff
+
+Present clear options for what to do next:
+
+1. **Proceed to planning** → Run `/workflows:plan`
+2. **Refine further** → Continue exploring the design
+3. **Done for now** → User will return later
+
+## YAGNI Principles
+
+During brainstorming, actively resist complexity:
+
+- **Don't design for hypothetical future requirements**
+- **Choose the simplest approach that solves the stated problem**
+- **Prefer boring, proven patterns over clever solutions**
+- **Ask "Do we really need this?" when complexity emerges**
+- **Defer decisions that don't need to be made now**
+
+## Incremental Validation
+
+Keep sections short—200-300 words maximum. After each section of output, pause to validate understanding:
+
+- "Does this match what you had in mind?"
+- "Any adjustments before we continue?"
+- "Is this the direction you want to go?"
+
+This prevents wasted effort on misaligned designs.
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Better Approach |
+|--------------|-----------------|
+| Asking 5 questions at once | Ask one at a time |
+| Jumping to implementation details | Stay focused on WHAT, not HOW |
+| Proposing overly complex solutions | Start simple, add complexity only if needed |
+| Ignoring existing codebase patterns | Research what exists first |
+| Making assumptions without validating | State assumptions explicitly and confirm |
+| Creating lengthy design documents | Keep it concise—details go in the plan |
+
+## Integration with Planning
+
+Brainstorming answers **WHAT** to build:
+- Requirements and acceptance criteria
+- Chosen approach and rationale
+- Key decisions and trade-offs
+
+Planning answers **HOW** to build it:
+- Implementation steps and file changes
+- Technical details and code patterns
+- Testing strategy and verification
+
+When brainstorm output exists, `/workflows:plan` should detect it and use it as input, skipping its own idea refinement phase.

package/plugins/compound-engineering/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