73 lines
2.2 KiB
Markdown
73 lines
2.2 KiB
Markdown
# 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
|