Initial commit

skills/insight-skill-generator/reference/troubleshooting.md

@@ -0,0 +1,72 @@
+# Troubleshooting Guide
+
+## No insights found
+
+**Symptoms**: Phase 1 reports 0 insights
+
+**Solution**:
+1. Verify `docs/lessons-learned/` exists in project
+2. Check for alternative locations (ask user)
+3. Verify insights were actually generated by extract-explanatory-insights hook
+4. Check file naming pattern matches YYYY-MM-DD-*.md
+
+**Prevention**: Set up extract-explanatory-insights hook if not already configured
+
+---
+
+## All insights cluster into one giant skill
+
+**Symptoms**: Phase 2 creates one cluster with 10+ insights
+
+**Solution**:
+1. Increase clustering threshold (e.g., 0.6 → 0.7)
+2. Enable sub-clustering (split by sub-topics or time periods)
+3. Manually split cluster in Phase 2 user review
+4. Create mode-based skill with different modes for different sub-topics
+
+**Prevention**: Tune clustering-config.yaml thresholds for your domain
+
+---
+
+## Generated skill doesn't load
+
+**Symptoms**: Skill not recognized by Claude Code after installation
+
+**Solution**:
+1. Check YAML frontmatter syntax (no tabs, proper dashes)
+2. Verify name field is lowercase kebab-case
+3. Check description doesn't contain special characters that break parsing
+4. Restart Claude Code session
+5. Check skill file permissions (should be readable)
+
+**Prevention**: Always run validation in Phase 4 before installation
+
+---
+
+## Trigger phrases don't activate skill
+
+**Symptoms**: Using trigger phrase doesn't invoke the skill
+
+**Solution**:
+1. Make trigger phrases more specific (avoid overly generic phrases)
+2. Include domain keywords in trigger phrases
+3. Add "PROACTIVELY when" to description for auto-triggering
+4. Try exact phrase match vs. semantic match
+5. Check for conflicts with built-in commands or other skills
+
+**Prevention**: Test trigger phrases in Phase 5 before finalizing
+
+---
+
+## Generated content quality is low
+
+**Symptoms**: SKILL.md is vague, missing details, or poorly organized
+
+**Solution**:
+1. Check insight quality (garbage in, garbage out)
+2. Manually edit SKILL.md to improve clarity
+3. Add more examples and context
+4. Reorganize sections for better flow
+5. Iterate to version 0.2.0 with improvements
+
+**Prevention**: Filter low-quality insights in Phase 2, prioritize insights with clear action items