Troubleshooting Docs

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 2: Gather Context

Extract from conversation history:

Required information:

• Module name: Which 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:

• Rack SDK version
• Stage (0-6 or post-implementation)
• OS version
• File/line references

Ask user if missing critical context:

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 3: Check Existing Docs

Search troubleshooting/ for similar issues:

# Search by error message keywords
grep -r "exact error phrase" troubleshooting/

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

If similar issue found:

Present options:

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

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:

• rack-sdk-linker-error-SimpleOsc-20251112.md
• svg-panel-not-loading-WaveShaper-20251112.md
• parameter-state-not-saving-Reverb-20251112.md

Step 5: Validate YAML Schema

CRITICAL: All docs require validated YAML frontmatter with enum validation.

VCV Rack Problem Types (enums):

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