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 by error message keywords
grep -r "exact error phrase" troubleshooting/

# Search by symptom category
ls troubleshooting/[category]/

Found similar issue: troubleshooting/build-failures/similar-issue.md

What's next?
1. Create new doc with cross-reference (recommended)
2. Update existing doc - Add this case as variant
3. Link as duplicate - Don't create new doc
4. Other

problem_type:
  - build_error        # Compilation/linking failures
  - runtime_error      # Crashes, exceptions during execution
  - panel_issue        # SVG rendering, layout problems
  - cv_processing      # CV signal handling issues
  - dsp_issue          # Audio processing problems
  - parameter_issue    # Module parameter bugs
  - port_issue         # Input/output jack problems
  - performance        # CPU/memory optimization
  - sdk_integration    # Rack SDK API misuse

component:
  - rack_sdk           # Rack SDK core
  - plugin_json        # plugin.json configuration
  - helper_py          # helper.py script
  - svg_panel          # SVG panel artwork
  - module_widget      # ModuleWidget implementation
  - module_struct      # Module struct (DSP)
  - cmake              # CMake build system
  - dsp_processor      # DSP processing logic
  - cv_ports           # Input/output ports
  - parameters         # Module parameters

root_cause:
  - missing_sdk_path   # Rack SDK not found
  - wrong_api_usage    # Incorrect Rack API usage
  - svg_constraint     # SVG doesn't meet VCV requirements
  - cv_scaling         # Incorrect CV voltage scaling
  - missing_config     # Missing plugin.json entry
  - helper_py_error    # helper.py generation failure
  - memory_issue       # Memory leak or allocation
  - threading_issue    # Thread safety violation
  - logic_error        # DSP algorithm bug
  - version_mismatch   # SDK version incompatibility

resolution_type:
  - code_fix           # Code change required
  - config_change      # Configuration update
  - sdk_update         # SDK version upgrade
  - build_fix          # Build system correction

severity:
  - critical           # Blocks development completely
  - moderate           # Significant impact, workaround exists
  - minor              # Cosmetic or edge case

# Verify enum values against schema
# problem_type must be in: build_error, runtime_error, panel_issue, cv_processing,
#   dsp_issue, parameter_issue, port_issue, performance, sdk_integration

# component must be in: rack_sdk, plugin_json, helper_py, svg_panel, module_widget,
#   module_struct, cmake, dsp_processor, cv_ports, parameters

# root_cause must be in: missing_sdk_path, wrong_api_usage, svg_constraint,
#   cv_scaling, missing_config, helper_py_error, memory_issue, threading_issue,
#   logic_error, version_mismatch

# resolution_type must be in: code_fix, config_change, sdk_update, build_fix

# severity must be in: critical, moderate, minor

❌ 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.

PROBLEM_TYPE="[from validated YAML]"
CATEGORY="[mapped from problem_type]"
FILENAME="[generated-filename].md"
DOC_PATH="troubleshooting/${CATEGORY}/${FILENAME}"

# Create directory if needed
mkdir -p "troubleshooting/${CATEGORY}"

# Write documentation using template
cat > "$DOC_PATH" << 'EOF'
---
module: [ModuleName or "VCV_Rack"]
date: [YYYY-MM-DD]
problem_type: [validated enum value]
component: [validated enum value]
symptoms:
  - [Observable symptom 1]
  - [Observable symptom 2]
root_cause: [validated enum value]
resolution_type: [validated enum value]
severity: [validated enum value]
tags: [keywords]
---

[Documentation content from template]
EOF

---
module: SimpleOsc
date: 2025-11-12
problem_type: build_error
component: rack_sdk
symptoms:
  - "Linker error: undefined reference to 'rack::plugin'"
  - "Build fails at linking stage"
root_cause: missing_sdk_path
resolution_type: config_change
severity: critical
rack_sdk_version: 2.5.2
tags: [build, cmake, sdk]
---

# Rack SDK Linker Error - Undefined Reference

## Problem

Linker fails with undefined reference to Rack SDK symbols during module build.

## Symptom

**Error message:**

**Observable behavior:**
- Compilation succeeds
- Linking fails immediately
- No plugin binary generated

## Context

- **Module:** SimpleOsc
- **Stage:** Stage 2 (Foundation)
- **Rack SDK Version:** 2.5.2
- **OS:** macOS 14.3
- **Build system:** CMake via Rack SDK Makefile

## Investigation

**Attempts that didn't work:**

1. **Clean rebuild** - Ran `make clean && make`, same error
2. **Check Rack SDK installation** - SDK present in expected location
3. **Verify include paths** - Headers found correctly (compilation succeeds)

**What led to solution:**

- Noticed linker can't find libRack symbols
- Checked RACK_DIR environment variable
- Found RACK_DIR not set in shell environment

## Root Cause

**Technical explanation:**

Rack SDK Makefile expects `RACK_DIR` environment variable to locate SDK installation. Without it, linker doesn't know where to find libRack library for symbol resolution.

The SDK's `compile.mk` includes:
```make
RACK_DIR ?= /path/to/Rack-SDK
LDFLAGS += -L$(RACK_DIR)

# Add to ~/.zshrc or ~/.bashrc
export RACK_DIR="/Users/david/Projects/Rack-SDK"

# Reload shell configuration
source ~/.zshrc

# Verify
echo $RACK_DIR  # Should output: /Users/david/Projects/Rack-SDK

cd modules/SimpleOsc
make clean
make

if [ -z "$RACK_DIR" ]; then
    echo "ERROR: RACK_DIR not set"
    echo "Set with: export RACK_DIR=/path/to/Rack-SDK"
    exit 1
fi

### 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]($DOC_PATH)" >> [similar-doc.md]

# Add to troubleshooting/patterns/common-solutions.md
cat >> troubleshooting/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

💡 This might be worth adding to Required Reading (Option 2)

## N. [Pattern Name] (ALWAYS REQUIRED)

### ❌ WRONG ([Will cause X error])
```[language]
[code showing wrong approach]

[code showing correct approach]

---

## Decision Menu After Capture

After successful documentation:

**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 (Rack SDK, CMake, SVG panels, etc.)

Action:
1. Extract pattern from the documentation
2. Format as ❌ WRONG vs ✅ CORRECT with code examples
3. Add to `troubleshooting/patterns/vcv-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 troubleshooting/ for the doc
- Add cross-reference to both docs
- Confirm: "✓ Cross-reference added"

**Option 4: Update common patterns**

- Check if 3+ similar issues exist
- If yes: Add pattern to troubleshooting/patterns/common-solutions.md
- If no: "Need 3+ similar issues to establish pattern (currently N)"

**Option 5: View documentation**

- Display the created documentation
- Present decision menu again

**Option 6: Other**

- Ask what they'd like to do

---

## Integration Points

**Invoked by:**

- Auto-detection after success phrases
- `/doc-fix` command
- Any skill after solution confirmation
- Manual: "document this solution"

**Invokes:**

- None (terminal skill)

**Reads:**

- Conversation history (for context extraction)
- `MODULES.md` (validate module name)
- `troubleshooting/` (search existing docs)

**Creates:**

- `troubleshooting/[category]/[filename].md` (documentation file)
- Updates to `troubleshooting/patterns/common-solutions.md` (if pattern detected)
- Updates to `troubleshooting/patterns/vcv-critical-patterns.md` (if promoted to Required Reading)

**Updates:**

- Existing docs (cross-references)
- Pattern library (if applicable)

---

## Success Criteria

Documentation is successful when:

- ✅ YAML frontmatter validated (all required fields, correct formats)
- ✅ File created in troubleshooting/[category]/
- ✅ Documentation follows template structure
- ✅ All sections populated with relevant content
- ✅ Code examples included (if applicable)
- ✅ Cross-references added (if similar issues exist)
- ✅ File is searchable (descriptive filename, tags)

---

## 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.md:**

- Warn but don't block
- Proceed with documentation
- Suggest: "Add [Module] to MODULES.md if not there"

---

## Notes for Claude

**When executing this skill:**

1. Always validate YAML frontmatter - BLOCK if invalid
2. Extract exact error messages from conversation
3. Include code examples in solution section
4. Cross-reference similar issues automatically
5. Category detection is automatic from problem_type enum
6. Ask user if critical context missing
7. Be specific in documentation (exact file:line, versions)

**Common pitfalls:**

- Forgetting to create directories before writing files
- Missing YAML validation (creates invalid docs)
- Vague descriptions (not searchable)
- No code examples (harder to understand solution)
- No cross-references (knowledge stays siloed)

---

## 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

---

## VCV Rack Specific Categories

**Build Failures:**
- Rack SDK not found
- Linker errors
- CMake configuration issues
- helper.py failures

**Panel Issues:**
- SVG not loading
- Component positions wrong
- Panel dimensions incorrect
- helper.py parsing errors

**CV/Signal Issues:**
- Incorrect CV scaling (1V/oct)
- Port not responding
- Signal clipping
- DC offset problems

**DSP Issues:**
- Audio artifacts
- Buffer underruns
- Sample rate handling
- Polyphony bugs

**Parameter Issues:**
- State not saving
- Parameter ranges wrong
- CV modulation not working
- Parameter smoothing issues

**SDK Integration:**
- API misuse
- Version compatibility
- Missing module registration
- plugin.json errors