troubleshooting-docs（故障排除文档）

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

<critical_sequence name="documentation-capture" enforce_order="strict">

7-Step Process

Auto-invoke after phrases:

• "that worked"
• "it's fixed"
• "working now"
• "problem solved"
• "that did it"

OR manual: /doc-fix command

Document when:

• Multiple investigation attempts needed
• Non-obvious solution that future sessions would benefit from
• Tricky debugging or root cause analysis

Skip when:

• Single-attempt fixes (typos, syntax errors, obvious mistakes)

Extract from conversation: plugin name, symptom (exact error messages), stage (0-6 or post-implementation), solution (code/config changes), investigation attempts, root cause, JUCE version, OS version, file/line references.

BLOCKING REQUIREMENT: If critical context is missing (plugin name, exact error, stage, or resolution steps), ask user and WAIT for response before proceeding to Step 3.

Search target category directory first (based on problem_type), then expand to all categories if no matches:

grep -r "exact error phrase" troubleshooting/[category]/
# If no match, expand: grep -r "exact error phrase" troubleshooting/

IF similar issue found:

THEN present decision options:

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): _

WAIT for user response, then execute chosen action.

ELSE (no similar issue found):

Proceed directly to Step 4 (no user interaction needed).

Format: [sanitized-symptom]-[plugin]-[YYYYMMDD].md

Examples:

• missing-juce-dsp-module-DelayPlugin-20251110.md
• parameter-not-saving-state-ReverbPlugin-20251110.md
• webview-crash-on-resize-TapeAgePlugin-20251110.md

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

<validation_gate name="yaml-schema" blocking="true">

Validate against schema: Classify the problem against enum values defined in references/yaml-schema.md. Ensure all required fields present and match allowed values exactly.

BLOCK if validation fails: Load schema.yaml to show specific allowed enum values. Present errors and WAIT for corrected values.

GATE ENFORCEMENT: Do NOT proceed to Step 6 until YAML frontmatter passes all validation rules.

</validation_gate>

Category mapping from problem_type: See references/yaml-schema.md for problem_type to directory mapping.

Read assets/resolution-template.md and populate with Step 2 context in a single operation:

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

mkdir -p "troubleshooting/${CATEGORY}"
# Write documentation with Step 2 context + validated YAML frontmatter

Step 7a: Cross-Reference (REQUIRED if similar issues found in Step 3)

If similar issues were found in Step 3, add bidirectional cross-references:

Update existing doc:

# Add Related Issues link to similar doc
echo "- See also: [$FILENAME]($REAL_FILE)" >> [similar-doc.md]

Update new doc: Cross-reference already included from Step 6.

Update patterns if 3+ similar issues:

# 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

If no similar issues found in Step 3, skip to Step 7b.

Step 7b: Critical Pattern Detection (OPTIONAL - System Suggestion)

If automatic indicators suggest this might be a critical pattern:

• Severity: critical in YAML
• Affects multiple plugins OR foundational stage (Stage 1 or 3)
• Non-obvious solution

Then add suggestion in decision menu (Step 8):

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

User decides via decision menu - NEVER auto-promote to Required Reading.

Template for Required Reading addition:

When user selects Option 2, use template from assets/critical-pattern-template.md. Number sequentially based on existing patterns in troubleshooting/patterns/juce8-critical-patterns.md.

</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:
- 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

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 plugins
• Solution is non-obvious but must be followed every time
• Foundational requirement (CMake, JUCE API, threading, etc.)

Action:

1. Extract pattern from the documentation
2. Format as ❌ WRONG vs ✅ CORRECT with code examples
3. Add to troubleshooting/patterns/juce8-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."

Note: For direct addition without full documentation workflow, users can use /add-critical-pattern command.

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

</decision_gate>

<integration_protocol>

Integration Points

Invoked by:

• deep-research skill (after solution found)
• plugin-improve skill (after fix validated)
• /doc-fix command (manual user invocation)

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 troubleshooting/[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>

Example Walkthrough

See references/example-walkthrough.md for decision points and edge cases.