troubleshooting-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., troubleshooting/build-failures/cmake-version-mismatch.md). Files use YAML frontmatter for metadata and searchability.

I need a few details to document this properly:

1. Which plugin had this issue? [PluginName]
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/[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): _

❌ 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 from assets/resolution-template.md
# (Content populated with Step 2 context and validated YAML frontmatter)

# Add Related Issues link to similar doc
echo "- See also: [$FILENAME]($REAL_FILE)" >> [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)

✓ Solution documented

File created:
- troubleshooting/[category]/[filename].md

What's next?
1. Continue workflow (recommended)
2. Add to Required Reading - Promote to critical patterns (juce8-critical-patterns.md)
3. Link related issues - Connect to similar problems
4. Update common patterns - Add to pattern library
5. View documentation - See what was captured
6. Other

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

Plugin not in PLUGINS.md:

• Warn but don't block
• Proceed with documentation
• Suggest: "Add [Plugin] to PLUGINS.md 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 parameter is saving correctly now."

Skill activates:

1. Detect confirmation: "That worked!" triggers auto-invoke
2. Gather context:
   • Plugin: ReverbPlugin
   • Symptom: DECAY parameter not persisting after DAW reload
   • Failed attempts: Checked APVTS creation, verified parameter ID
   • Solution: Added parameterValueChanged() to update processor state
   • Root cause: State only saved from APVTS, not reflecting UI changes
3. Check existing: No similar issue found
4. Generate filename: parameter-not-saving-decay-ReverbPlugin-20251110.md
5. Validate YAML:

   plugin: ReverbPlugin
   date: 2025-11-10
   symptom: DECAY parameter not persisting after DAW reload
   severity: medium
   tags: [parameters, runtime]
   

   ✅ Valid
6. Create documentation:
   • troubleshooting/parameter-issues/parameter-not-saving-decay-ReverbPlugin-20251110.md
7. Cross-reference: None needed (no similar issues)

Output:

✓ Solution documented

File created:
- troubleshooting/parameter-issues/parameter-not-saving-decay-ReverbPlugin-20251110.md

What's next?
1. Continue workflow (recommended)
2. Add to Required Reading - Promote to critical patterns (juce8-critical-patterns.md)
3. Link related issues - Connect to similar problems
4. Update common patterns - Add to pattern library
5. View documentation - See what was captured
6. 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