# Session Review

> >

- **Type:** Skill
- **Install:** `agentstack add skill-cyberelf-agent-skills-session-review`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [cyberelf](https://agentstack.voostack.com/s/cyberelf)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [cyberelf](https://github.com/cyberelf)
- **Source:** https://github.com/cyberelf/agent_skills/tree/main/skills/session-review

## Install

```sh
agentstack add skill-cyberelf-agent-skills-session-review
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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`.
2. Otherwise check the current working directory: if it has `Cargo.toml`, `package.json`,
   `src/`, or similar project markers, use `$PWD`.
3. 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)

```bash
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`:
```bash
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:
```bash
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.

```markdown
#  — 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](https://github.com/cyberelf)
- **Source:** [cyberelf/agent_skills](https://github.com/cyberelf/agent_skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-cyberelf-agent-skills-session-review
- Seller: https://agentstack.voostack.com/s/cyberelf
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.