Smithery is now a part of Arcade.dev! Read more in our announcement here
Captures solved problems as categorized documentation with YAML frontmatter for fast lookup...
Purpose: Automatically document solved problems to build searchable institutional knowledge with category-based organization (enum-validated problem types).
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).
Auto-invoke after phrases:
OR manual: /doc-fix command
Document when:
Skip when:
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.mdparameter-not-saving-state-ReverbPlugin-20251110.mdwebview-crash-on-resize-TapeAgePlugin-20251110.mdCRITICAL: All docs require validated YAML frontmatter with enum validation.
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.
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
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.
If automatic indicators suggest this might be a critical pattern:
critical in YAMLThen 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.
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
Option 2: Add to Required Reading ā PRIMARY PATH FOR CRITICAL PATTERNS
User selects this when:
Action:
troubleshooting/patterns/juce8-critical-patterns.mdNote: For direct addition without full documentation workflow, users can use /add-critical-pattern command.
Option 3: Link related issues
Option 4: Update common patterns
Option 5: View documentation
Option 6: Other
Invoked by:
Invokes:
Handoff expectations: All context needed for documentation should be present in conversation history before invocation.
Documentation is successful when ALL of the following are true:
See references/example-walkthrough.md for decision points and edge cases.
