Session Review

Session Review Skill

You are performing a cross-session AI assistant analysis for a software project. The scripts you need are bundled alongside this SKILL.md in scripts/.

~/.claude/skills/session-review/
├── SKILL.md          ← you are here
└── scripts/
    ├── retro.ts      ← orchestrator (run this)
    ├── get_hist.ts   ← raw session collector
    └── normalize_hist.ts ← normalizer

Set SKILL_SCRIPTS="$HOME/.claude/skills/session-review/scripts" at the start of any bash commands you run, so you can refer to scripts as $SKILL_SCRIPTS/retro.ts.

Follow each phase in order. Do not skip phases.

---

Phase 0 — Determine the project

1. If the user invoked this skill with an argument (e.g. /session-review ~/workspace/crab),

use that path as PROJECT_PATH.

1. Otherwise check the current working directory: if it has Cargo.toml, package.json,

src/, or similar project markers, use $PWD.

1. If still ambiguous, ask: "Which project path should I analyze?"

PROJECT_NAME is the directory's basename. Storage lives at ~/.retro//.

---

Phase 1 — Collect and normalize (the pipeline)

SKILL_SCRIPTS="$HOME/.claude/skills/session-review/scripts"
npx tsx "$SKILL_SCRIPTS/retro.ts" "$PROJECT_PATH" run

This runs two steps automatically:

• collect — get_hist.ts copies raw sessions from Copilot CLI

(~/.copilot/session-state), Claude Code (~/.claude/projects/), and VS Code to ~/.retro//raw/

• normalize — normalize_hist.ts --incremental converts sessions to unified

Markdown in ~/.retro//normalized/

On the first run, all sessions are collected. On subsequent runs, only sessions newer than lastCollectedAt in the manifest are added.

If the user wants a full re-analysis from scratch, add --full:

npx tsx "$SKILL_SCRIPTS/retro.ts" "$PROJECT_PATH" run --full

If the pipeline exits non-zero, read its stderr to diagnose before continuing.

Check progress anytime:

npx tsx "$SKILL_SCRIPTS/retro.ts" "$PROJECT_PATH" status

---

Phase 2 — Orient: read the index

Read ~/.retro//normalized/index.json.

From the sessions array, compute:

• Total sessions, date range (first and last timestamp)
• Source breakdown (copilot-cli, claude-code, vscode)
• Total tool calls: sum of toolCallCount
• Total errors: sum of errorCount
• Top 5 sessions by errorCount (ID, date, count)

Print a brief summary:

Sessions: N  •  Date range: YYYY-MM-DD – YYYY-MM-DD
Sources: copilot-cli(N)  claude-code(N)  vscode(N)
Tool calls: N  •  Errors: N
Top error sessions: [list]

---

Phase 3 — Deep read: strategic sampling

Do not read combined.md in full — it will overflow context. Read individual session .md files from ~/.retro//normalized/sessions/.

Sampling order:

1. The 5 sessions with the highest errorCount
2. The 5 most recent sessions by timestamp
3. The 2 oldest sessions (detect long-standing patterns)
4. 3 sessions evenly spread across the date range

If total session count ≤ 15, read them all.

For each session note:

• What the user was trying to accomplish (first user message)
• Which tools were called most often
• What errors occurred and whether they repeat across sessions
• Explicit user corrections ("no, don't", "this is wrong", "stop X")
• Tasks marked done before they were actually tested or verified

---

Phase 4 — Read project context

If present, read these files (they're essential for judging whether a pattern is a known limitation vs. an actionable gap):

• /AGENTS.md — coding agent instructions (highest priority)
• /ARCHITECTURE.md
• /README.md (first 80 lines only)
• /openspec/changes/ directory listing (if it exists)

---

Phase 5 — Write the report

Write to:

~/.retro//reports/-report.md

Also write/overwrite ~/.retro//reports/latest-report.md with the same content. Create the reports/ directory if it doesn't exist.

After writing, update the manifest's lastReportAt by editing the file directly:

~/.retro//manifest.json

Report template

Use this structure exactly. Omit sections with no findings.

#  — Session Analysis Report

**Period:**  – 
**Sessions analyzed:** N (M tool calls · K errors)
**Sources:** 

---

## Executive Summary

---

## 1. Recurring Bugs — Demand Regression Tests

### 1.N 

Observed in sessions ****. 

**Action:** 

---

## 2. Critical Unresolved Issues (open as of )

### 2.N   *(P0|P1)*

> ""

**Action:**
1. 
2. 

---

## 3. Tool Error Tax — Documentation-Preventable Failures

| Category | Count | Root cause |
|---|---|---|

Add to AGENTS.md under **"Known Tool Behavior"**:
\`\`\`markdown
### 

\`\`\`

---

## 4. Code Refactoring

### 4.N   *(P1|P2)*

---

## 5. Missing Tests — Specific Gaps

| File | Missing test |
|---|---|

---

## 6. Process Improvements

### 6.N 

**Add to AGENTS.md `## `:**
> 

---

## 7. Documentation Updates Required

---

## 8. OpenSpec Gaps

---

## Priority Summary

| Priority | Item | Owner area |
|---|---|---|
| **P0** | ... | ... |
| **P1** | ... | ... |
| **P2** | ... | ... |
| **P3** | ... | ... |

---

Phase 6 — Storage management

After writing the report, tell the user:

• Report location: ~/.retro//reports/-report.md
• To re-run incrementally next time: /session-review
• Storage usage: npx tsx "$SKILL_SCRIPTS/retro.ts" status
• To free space (raw data is safe to delete after normalizing):

``bash npx tsx "$SKILL_SCRIPTS/retro.ts" cleanup --clean=raw ` Options: --clean=raw (largest), --clean=normalized, --clean=reports, --clean=all`

---

Analysis rules

These exist so the report is trustworthy and actionable, not just voluminous.

• Never fabricate. Every claim must come from a session you actually read.
• Name files and functions. "Add more tests" is useless. "Add a test in

crab-agents/src/system_agent.rs asserting that agent_send_message returns an error when sender_id == receiver_id" is actionable.

• Quote the session. For critical bugs include a short direct quote.
• Distinguish recurrence from first occurrence. One session = finding. Three or

more sessions across weeks = systemic gap requiring a process fix.

• Tool errors need root cause. "grep exits 1 on no match" is a misuse pattern

preventable by documentation. "Network timeout" is environment noise. Treat them differently.

• Cross-reference project docs. If AGENTS.md already covers a pattern, note it.

If it doesn't but should, that's the gap to document in §6/§7.

• No trailing summaries. The report is a punch list. Don't add a "what went well"

section or restate what the code does correctly.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cyberelf
• Source: cyberelf/agent_skills
• License: MIT

Install and usage instructions live in the source repository linked above.