gh-cskiro-claudex-meta-tools/skills/insight-skill-generator/reference/troubleshooting.md

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