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.