compound-workflow 0.1.1

package/src/.agents/skills/compound-docs/SKILL.md

@@ -0,0 +1,533 @@
+---
+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:** Primary capture writes one solution doc per problem in its symptom category directory (e.g., `docs/solutions/performance-issues/2026-02-19-email-processing-n-plus-one-in-brief-generation.md`). Files use YAML frontmatter for metadata and searchability.
+
+Post-capture actions (by explicit user choice) may update other references (e.g., patterns indexes).
+
+---
+
+<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:** `/workflow: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 (as applicable):**
+
+- Runtime/framework version
+- Environment/stage (dev/staging/prod)
+- OS version
+- File/line references
+- **Spike-origin:** If this solution came from a spike (timeboxed investigation from `/workflow:work` Spike Protocol), include `spike` in the doc's `tags` frontmatter when creating the documentation.
+
+**BLOCKING REQUIREMENT:** If critical context is missing (module name, exact error, environment/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 environment/stage were you in? (dev/staging/prod)
+
+[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 using Grep/Glob/Read tools.
+
+Search by:
+
+- exact error message keywords
+- module/component
+- root-cause phrases
+- tags
+
+**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 (separate action; 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: `YYYY-MM-DD-<module-slug>-<symptom-slug>.md`
+
+**Sanitization rules:**
+
+- Lowercase
+- Replace spaces with hyphens
+- Remove special characters except hyphens
+- Truncate to reasonable length (< 80 chars)
+
+**Examples:**
+
+- `2026-02-19-brief-system-missing-include-caused-n-plus-one.md`
+- `2026-02-19-email-processing-parameter-not-saving-state.md`
+- `2026-02-19-assistant-webview-crash-on-resize.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:**
+
+1. Load `.agents/skills/compound-docs/schema.yaml`.
+2. If `.agents/skills/compound-docs/schema.project.yaml` exists, validate against it as the repo-specific overlay.
+3. Use [yaml-schema.md](./references/yaml-schema.md) as the human-readable reference.
+
+Ensure all required fields are present and match allowed values exactly for enum fields.
+
+**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 [resolution-template.md](./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, include cross-references in the NEW doc.
+
+Do not modify existing docs automatically as part of documentation capture. If the user explicitly requests updating an existing doc, do it as a separate, deliberate action.
+
+**Pattern suggestions (optional):**
+
+If this represents a common pattern (3+ similar issues), suggest using Option 3 in the decision menu to add it to the common patterns index.
+
+**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 systems
+- 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 [critical-pattern-template.md](./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. Add to common patterns index - Append to docs/solutions/patterns/common-solutions.md
+4. Link related issues - Connect to similar problems
+5. Add to existing skill - Add to an existing learning skill
+6. Create new skill - Extract into new learning skill
+7. View documentation - See what was captured
+8. 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 (framework/runtime rules, safety practices, 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: Add to common patterns index**
+
+User selects this when:
+
+- This issue has occurred multiple times (e.g., 3+ similar issues)
+- The solution pattern should be quickly discoverable
+
+Action:
+
+1. Ensure directory exists: `docs/solutions/patterns/`
+2. Append a new entry to `docs/solutions/patterns/common-solutions.md` using the captured doc as an example.
+3. If the file does not exist, create it with a short header.
+4. Confirm: "✓ Added to common patterns index"
+
+Example append block:
+
+```bash
+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
+```
+
+NOTE: This is a post-capture action and will create/modify an additional file beyond the primary solution doc.
+
+**Option 4: 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 5: Add to existing skill**
+
+User selects this when the documented solution relates to an existing learning skill:
+
+Action:
+1. Prompt: "Which skill? (<skill-name>)"
+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:
+
+- Add to `.agents/skills/<skill-name>/references/resources.md` under "Project-Specific Resources" (if it exists)
+- Add to `.agents/skills/<skill-name>/references/examples.md` with a link to the solution doc (if it exists)
+
+**Option 6: 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. Create a new skill directory: `.agents/skills/<skill-name>/`
+3. Add `.agents/skills/<skill-name>/SKILL.md` with a clear description (what + when to use)
+4. Create initial reference files (optional) and add this solution doc as the first example
+5. Confirm: "✓ Created new <skill-name> skill with this solution as first example"
+
+**Option 7: View documentation**
+
+- Display the created documentation
+- Present decision menu again
+
+**Option 8: Other**
+
+- Ask what they'd like to do
+
+</decision_gate>
+
+---
+
+<integration_protocol>
+
+## Integration Points
+
+**Invoked by:**
+- /workflow: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 included in the new doc when related issues are found (bidirectional links are optional via the decision menu)
+- ✅ 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:** `2025-11-10-brief-system-n-plus-one-brief-generation.md`
+5. **Validate YAML:**
+   ```yaml
+   module: Brief System
+   date: 2025-11-10
+   problem_type: performance_issue
+   component: backend
+   symptoms:
+     - "N+1 query when loading email threads"
+     - "Brief generation taking >5 seconds"
+   root_cause: missing_include
+   framework: rails
+   framework_version: 7.1.2
+   severity: high
+   tags: [n-plus-one, eager-loading, performance]
+   ```
+   ✅ Valid
+6. **Create documentation:**
+   - `docs/solutions/performance-issues/2025-11-10-brief-system-n-plus-one-brief-generation.md`
+7. **Cross-reference:** None needed (no similar issues)
+
+**Output:**
+
+```
+✓ Solution documented
+
+File created:
+- docs/solutions/performance-issues/2025-11-10-brief-system-n-plus-one-brief-generation.md
+
+What's next?
+1. Continue workflow (recommended)
+2. Add to Required Reading - Promote to critical patterns (critical-patterns.md)
+3. Add to common patterns index - Append to docs/solutions/patterns/common-solutions.md
+4. Link related issues - Connect to similar problems
+5. Add to existing skill - Add to an existing learning skill
+6. Create new skill - Extract into new learning skill
+7. View documentation - See what was captured
+8. 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/src/.agents/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/src/.agents/skills/compound-docs/assets/resolution-template.md

@@ -0,0 +1,97 @@
+---
+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|developer_experience|workflow_issue|best_practice|documentation_gap]
+component: [e.g., backend|frontend|database|infra|ci|auth|api|docs|tooling]
+symptoms:
+  - [Observable symptom 1 - specific error message or behavior]
+  - [Observable symptom 2 - what user actually saw/experienced]
+root_cause: [Free text or stable slug describing actual cause]
+framework: [optional, e.g., rails|react|django]
+framework_version: [optional, X.Y.Z]
+runtime_version: [optional, e.g., ruby 3.3.1|node 20.11.0]
+environment: [optional, dev|staging|prod|other]
+resolution_type: [code_fix|migration|config_change|test_fix|dependency_update|environment_setup]
+severity: [critical|high|medium|low]
+tags: [keyword1, keyword2, keyword3]  # include "spike" when this doc originated from a spike
+---
+
+# 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/Runtime: [if relevant]
+- Environment/Stage: [dev|staging|prod|other]
+- 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):
+```text
+# Before (broken):
+[Show the problematic code]
+
+# After (fixed):
+[Show the corrected code with explanation]
+```
+
+**Database migration** (if applicable):
+```text
+# 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, version constraint, 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.