insights

Skill: insights

When to Use

Run this skill:

• After 5+ sessions to surface meaningful patterns
• When deciding where to invest in tests or tooling
• When repeating errors and wanting a data-driven view of why
• As part of a planning session to understand the codebase's hot spots

---

Instructions

Step 1 — File change heatmap (which files change most)

# Top 20 most-changed files in git history
git log --name-only --format="" | grep '\.py$' | sort | uniq -c | sort -rn | head -20

Interpret: High-churn files are either:

• Core abstractions that evolve frequently (expected)
• Files with unclear responsibility (refactor candidate)
• Risky files where instability = risk (add tests)

Step 2 — Failure pattern analysis

# Extract failed steps from checkpoint log
grep '"status":"failed"' .claude/state/checkpoint.jsonl | \
  python3 -c "import sys,json; [print(json.loads(l).get('step','?')) for l in sys.stdin]" | \
  sort | uniq -c | sort -rn

Interpret: Steps that fail repeatedly indicate:

• Unclear acceptance criteria in the plan
• A dependency that needs better documentation
• A missing test that should catch the failure earlier

Step 3 — Retry analysis

# Steps that appeared more than once (retried)
grep '"status"' .claude/state/checkpoint.jsonl | \
  python3 -c "
import sys, json, collections
steps = []
for line in sys.stdin:
    try:
        d = json.loads(line)
        steps.append(d.get('step', '?'))
    except:
        pass
counts = collections.Counter(steps)
for step, count in counts.most_common():
    if count > 1:
        print(f'{count}x  {step}')
"

Step 4 — Learnings frequency analysis

# Count learnings by module/topic
grep -c "##" .claude/state/learnings.md 2>/dev/null || echo "0 learnings recorded."
grep "^## " .claude/state/learnings.md 2>/dev/null || echo "No learnings file."

Interpret: Clusters of learnings around the same module suggest:

• The module needs clearer documentation
• CLAUDE.md for that module is missing or outdated
• The module should be refactored for clarity