session-insights

name	session-insights
description	Analyze past Claude Code sessions to extract patterns, metrics, and recommendations.

Session Insights

Analyze the current project's Claude Code usage patterns and generate actionable recommendations.

Step 1: Gather session data

Collect data from available sources in the current project:

1. Session metrics — ~/.claude/metrics/{project-slug}/*.json (structured JSON from session-report hook)
2. CLAUDE_ERRORS.md — error frequency by Area and Type
3. Git log — files most frequently modified in commits mentioning "fix", "bug", "error"
4. .claude/agent-memory/ — learnings accumulated by agents
5. Registry history — audit score trend from $DOTFORGE_DIR/registry/projects.yml

If a source doesn't exist, skip it and note as "unavailable".

Retroactive Analysis (no session metrics yet)

When ~/.claude/metrics/{project-slug}/ is empty or doesn't exist, reconstruct a pseudo-historical picture:

1. CLAUDE_ERRORS.md → parse dates and group errors by week/month to show trends
2. Git log → git log --name-only --since="60 days ago" to identify:
   • Hot files (most frequently changed)
   • Fix frequency (git log --grep="fix" --oneline | wc -l)
   • Commit cadence by week
3. Registry history → score progression over time
4. Rule glob coverage → cross-reference git log --name-only against .claude/rules/*.md globs to estimate historical rule coverage

Mark all retroactive data clearly as:

⚠ Inferred from git history — no session metrics available yet.
   Session metrics will accumulate automatically after /forge sync.

Step 2: Compute metrics

From available data, calculate:

Session Metrics (from ~/.claude/metrics/)

When JSON metrics files exist, aggregate across the last N sessions (default 20):

• Total sessions: count of metric files
• Avg files touched: mean files_touched per session
• Avg hook blocks: mean hook_blocks + lint_blocks (lower is better — team is learning)
• Rule coverage trend: plot rule_coverage over time (improving / stable / declining)
• Error rate: errors_added / sessions (target: < 0.5)

Error Patterns

• Top error areas: group CLAUDE_ERRORS.md entries by Area, rank by count
• Error types distribution: count by Type (syntax, logic, integration, config, security)
• Repeat offenders: areas with 3+ errors (candidates for rule creation)

File Activity

• Hot files: top 10 most-edited files (from git log)
• Churn rate: files edited > 5 times in last 30 days (may need refactoring)
• Untested hot files: hot files without corresponding test files

Agent Usage (from agent-memory/)

• Active agents: which agents have accumulated learnings
• Top learnings: most recent entries per agent
• Gaps: agents with memory enabled but no learnings (underused)

Score Trend (from registry)

• Current score: latest audit score
• Trend: improving, stable, or declining (compare last 3 audits)
• Projected: if declining, estimate when score drops below 7.0

Step 3: Generate recommendations

Based on metrics, produce actionable recommendations:

1. Repeat errors → suggest creating a rule in .claude/rules/ targeting that area
2. Hot untested files → suggest test creation
3. Score declining → suggest /forge sync to update configuration
4. Underused agents → suggest delegation patterns for common tasks
5. High churn files → suggest refactoring or better abstractions

Step 4: Feed practices pipeline

For the top 3 most impactful recommendations:

1. Check if a practice already exists in $DOTFORGE_DIR/practices/inbox/ or active/
2. If not, create a practice in practices/inbox/:
   • source_type: session-insights
   • tags: [insights, <area>]
3. Report which practices were created

Step 5: Generate report

Output format:

═══ SESSION INSIGHTS: {{project}} ═══
Fecha: {{YYYY-MM-DD}}
Data sources: {{list of available sources}}

── SESSION METRICS ──
Sessions tracked: {{N}} (since {{first date}})
Avg files/session: {{N}} | Avg commits/session: {{N}}
Hook blocks: {{N}} destructive, {{N}} lint (total across sessions)
Rule coverage: {{trend}} ({{current}}% — last 5: {{values}})
Error rate: {{N}} errors/session
{{if retroactive: "⚠ Inferred from git history"}}

── ERROR PATTERNS ──
Top areas: {{area}} ({{count}} errors), ...
Type distribution: logic {{N}}, config {{N}}, ...
Repeat offenders: {{areas with 3+ errors}}

── FILE ACTIVITY ──
Hot files (last 30 days):
  1. {{file}} — {{N}} edits
  2. ...
Untested hot files: {{list or "none"}}
High churn (>5 edits): {{list or "none"}}

── AGENT USAGE ──
Active: {{agents with learnings}}
Underused: {{agents with empty memory}}

── SCORE TREND ──
Current: {{score}}/10
Trend: {{improving|stable|declining}} ({{last 3 scores}})

── RECOMMENDATIONS ──
1. {{recommendation}} — impact: {{high|medium|low}}
2. ...

── PRACTICES CREATED ──
{{list of new practices or "none"}}