Skip to main content
skill CX Codex

retrospective · glebis — Claude Code skill: what it does, how to install

retrospective analyzes session logs, extracts corrections and workflow failures, then writes approved lessons directly into memory files, skills, or CLAUDE.md.

MIT 135 installs ★ 414 updated 2026-10-23

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add glebis/claude-skills --skill retrospective -a claude-code
Open on GitHub

What retrospective does

This skill evaluates either the active conversation or day-old JSONL transcripts located in ~/.claude/projects. For brief tasks it runs a fast check with a single prompt. In longer conversations it switches to full mode, scanning for failed tools, user corrections, and recurring error patterns.

It ranks potential updates by importance and cross-checks them against existing records to avoid duplicates. Once you pick the items to keep in a single interactive prompt, the skill applies changes to MEMORY.md, project or global CLAUDE.md, or files under ~/.claude/skills/.

Exporting tasks to Linear requires the CLI script at ~/.claude/skills/linear/scripts/linear. Without that script present, the retro omits Linear action candidates entirely.

What it helps with

  • extract user corrections and recurring errors from transcripts
  • persist project learnings into MEMORY.md files
  • update skill instructions after runtime failures
  • create Linear task issues from session findings

Example prompts for the agent

  • /retrospective
  • /retrospective today
  • let's do a retro

How to install retrospective

1Skills CLI (Vercel)

npx skills add glebis/claude-skills --skill retrospective -a claude-code

2Manually: put the files in place

~/.claude/skills/retrospective/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/retrospective/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about retrospective

How to install retrospective in Claude Code?

Run npx skills add glebis/claude-skills --skill retrospective -a claude-code.

What does retrospective do?

It inspects current or past conversation transcripts, spots corrections and failure patterns, and updates your memory files or skills.

Can retrospective automatically log issues into Linear?

Yes, if the script at ~/.claude/skills/linear/scripts/linear is present. If it is not found, the skill skips creating Linear issues.

Source text

SKILL.md · MIT
---
name: retrospective
description: Interactive post-session retrospective that captures learnings, updates skills, and saves memories. Use when the user says "/retrospective", "let's do a retro", "what did we learn", "session review", "retro", or "wrap up". Also use at the end of long productive sessions when significant patterns or corrections emerged. Supports multi-session mode — by default processes all of today's sessions across projects.
---

# Retrospective

Interactive post-session retro. Scans sessions, asks focused questions, proposes concrete actions the user approves in one step.

## Modes

### Single-session mode (default when inside a substantial conversation)
Scans the current conversation only. This is the original behavior.

### Multi-session mode (default when invoked with no args, or with "today", or with a date)
Scans all sessions from a given day (default: today) across all projects. Extracts user corrections, skill failures, and patterns from JSONL transcripts.

**Trigger:** `/retrospective` at the start of a fresh session, or `/retrospective today`, or `/retrospective 2026-05-24`.

## Multi-Session Discovery

### Step 0 — Discover sessions

```bash
# Find today's sessions (default)
find ~/.claude/projects -maxdepth 2 -name "*.jsonl" -not -path "*/subagents/*" -mtime 0

# Or for a specific date, filter by file modification date
find ~/.claude/projects -maxdepth 2 -name "*.jsonl" -not -path "*/subagents/*" -newermt "YYYY-MM-DD" ! -newermt "YYYY-MM-DD + 1 day"
```

For each JSONL file found, extract a summary:
1. Parse the project name from the path (the directory name after `projects/`, decoded from the path-encoding)
2. Extract `user` and `assistant` messages (type `user` and `assistant`)
3. For user messages: `message.content` (may be string or array of `{type: "text", text: "..."}`)
4. For assistant messages: collect text blocks from `message.content` array where `type == "text"`
5. Build a condensed transcript: first 10 user messages + last 5 user messages (to capture corrections at the end)
6. Skip sessions with fewer than 3 user messages (too short to have learnings)

### Step 0b — Present session list

Show the user what was found:

```
Found N sessions today:
- project-name-1 (session-id[:8]) — "first user message preview..."
- project-name-2 (session-id[:8]) — "first user message preview..."
```

Then continue to Step 1a with the combined findings from all sessions. Each candidate action should note which session it came from (project name + short ID).

## Single-Session Process

### Step 0 — Gate Check (silent)

Scan the conversation and estimate session depth. Look for tool calls (Read, Edit, Write, Bash, Skill invocations), errors encountered, and back-and-forth exchanges. Don't try to count exactly — judge by feel:

- **Short session** (a quick question and answer, ~1-2 tasks) → **Fast mode** (Step 1b)
- **Substantial session** (multiple tasks, skill usage, errors, corrections) → **Full mode** (Step 1a)

### Step 1a — Full Mode

Silently scan the conversation and collect:

1. **Skills invoked** — which succeeded, which failed, workarounds applied
2. **User corrections** — explicit "no, do it this way" moments (highest signal)
3. **Repeated patterns** — same error hit multiple times, same workaround applied
4. **Cross-skill workflows** — 3+ skills chained in sequence

Then read existing state:
- Find the current project's memory directory: `glob ~/.claude/projects/*/memory/MEMORY.md` and read it plus relevant memory files
- Read skill files for any skills that were invoked (`~/.claude/skills/{name}/skill.md`)
- Check if Linear CLI exists: `test -f ~/.claude/skills/linear/scripts/linear && echo "configured" || echo "not configured"`

Generate up to **5 candidate actions**, ranked by signal strength:
1. User corrections (highest priority)
2. Failed/workarounded skills
3. Repeated patterns
4. Error patterns
5. Workflow patterns (lowest)

**Dedup rules:**
- If a candidate's content overlaps with an existing memory file → drop it
- If a skill update candidate overlaps with existing skill file content → drop it
- If Linear is not configured → omit any Linear task candidates

Present everything in a **single AskUserQuestion call** (up to 4 questions):

| # | Question | Type |
|---|----------|------|
| 1 | "Quick session check?" | Single select: `Productive / Mixed / Rough / Skip retro` |
| 2 | "What felt slow or broken?" | Free text via Other (optional) |
| 3 | "Anything to carry forward as a rule?" | Free text via Other (optional) |
| 4 | "Which of these should I save?" | Multi-select: generated candidates with descriptions. Always include a "Nothing / skip all" option. |

If Q1 = "Skip retro" → exit immediately.

If Q1 = "Rough" and Q2/Q3 are empty → exit with "Nothing to save — session closed." Don't add another question after the user already signaled they're done.

### Step 1b — Fast Mode

Single AskUserQuestion call with one question:
- "Anything worth remembering from this session?" with options:
  - "Nothing, we're done" (default)
  - Other (free text)

If "Nothing" → exit. If free text → save as memory, exit.

### Step 2 — Execute (silent, no re-confirmation)

For each approved item from Q4 (plus any insights from Q2/Q3 free text):

1. **Read the target file** before writing
2. **Check for conflicts/duplicates** against current content
3. **Write the change** if clean
4. **Skip with warning** if conflict detected

Action types and their targets:

| Type | Target | Tool |
|------|--------|------|
| Skill update | `~/.claude/skills/{name}/skill.md` | Edit |
| Memory (feedback) | Current project's `memory/feedback_*.md` + MEMORY.md | Write |
| Memory (project) | Current project's `memory/project_*.md` + MEMORY.md | Write |
| CLAUDE.md rule | `~/.claude/CLAUDE.md` or project CLAUDE.md | Edit |
| Linear task | `~/.claude/skills/linear/scripts/linear issue create --title "..." --description "..."` | Bash |

### Step 3 — Summary (brief)

One-line per action taken:
```
Updated telegram skill — added chat type mismatch note
Saved memory — Qwen /api/chat not /api/generate
Skipped: pdf-generation update (already documented)
```

Done. No trailing commentary.

## JSONL Transcript Format

Session transcripts are stored as JSONL files at `~/.claude/projects/{project-path}/{session-id}.jsonl`.

Each line is a JSON object with a `type` field. Relevant types:
- `user` — user message. Content at `message.content` (string or array of `{type: "text", text: "..."}`)
- `assistant` — Claude's response. Content at `message.content` (array of content blocks; extract where `type == "text"`)
- `ai-title` — auto-generated session title

To extract a readable transcript from a JSONL file, use a Python one-liner or read the file and filter for `user`/`assistant` types.

**Project name decoding:** The directory name uses the absolute path with slashes replaced by dashes, e.g., `-Users-glebkalinin-ai-projects-foo` → `~/ai_projects/foo`.

## Mode Selection Logic

When `/retrospective` is invoked:
1. If the current conversation has 10+ user messages → **single-session mode** (retro this conversation)
2. If the current conversation is short (just the `/retrospective` invocation) → **multi-session mode** (scan today's sessions)
3. If args contain a date (e.g., "today", "yesterday", "2026-05-24") → **multi-session mode** for that date
4. If args contain "all" → **multi-session mode** for today

## Candidate Description Format

Each candidate in Q4 must have a description showing the **exact proposed content**, not just a title. The user judges candidates by reading descriptions, not by opening files.

Good: `"Add to telegram skill: get_chat_type() misclassifies private chats as channels — use Telethon client.send_message() directly for DMs"`

Bad: `"Update telegram skill with DM fix"`

## What This Skill Does NOT Do

This skill only captures session learnings. It does not review code quality, analyze PRs, create documentation, or run tests. For those, use the appropriate dedicated skills.

## Rules

- Never write learnings into this skill file itself — distribute to relevant skills or memory
- Cap candidates at 5 even if more findings exist
- User corrections always rank above tool failures
- The multi-select in Step 1a IS the approval — do not ask again per action
- If the session used no skills, only offer memory and CLAUDE.md candidates
- Keep the entire interaction to 2 moments: one question call, then silent execution

## Tools

- AskUserQuestion: Interactive questions (1-4 per call, single/multi select)
- Read: Check existing memory and skill files before proposing changes
- Edit: Update existing skill files and CLAUDE.md
- Write: Create new memory files
- Bash: Linear task creation, skill directory listing
- Glob: Find skill and memory files

## Testing

Engine logic is tested in `retro_engine.py` with 9 scenario fixtures and 30 pytest tests.
Run: `cd ~/.claude/skills/retrospective && python3 -m pytest test_retro_engine.py -v`

© glebis · MIT · glebis/claude-skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

retrospective by other authors comes first.

retrospective Donchitos A skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode that runs a sprint or milestone retrospective from commit history, sprint plans, and task statuses. Produces a concrete action list for the next iteration. CX Codex +1 659installs retrospective haabe Runs a structured retrospective after every completed delivery cycle. It records the cycle in cycle-history.yml, captures prediction calibration, and feeds the learning loop. CX Codex +1 ★ 54repo stars retrospective-analyzer davila7 retrospective-analyzer runs retrospective analysis on sprint git commits and Linear completion data. Helps engineering teams track metrics and plan concrete action items. CX Codex +1 196installs groove-utilities-memory-retrospective andreadellacorte groove-utilities-memory-retrospective summarizes workflow trends from .groove/memory/ by analyzing session ratings, mistake patterns, and recorded learnings. Helpful for weekly or monthly development check-ins. CX Codex +1 517installs run-learning-retrospective cursor The run-learning-retrospective skill runs a learning retrospective: checks finished work against goals, finds recurring blockers and adjusts the plan. Handy after a milestone closes. CX Codex +1 937installs iterate-retrospective product-on-purpose iterate-retrospective is a Claude Code skill that facilitates and documents team retrospectives after sprints or milestones, capturing successes, failures, and follow-up owners. CX Codex +1 832installs sprint-retrospective akillness sprint-retrospective runs a sprint or milestone retrospective and turns it into a few owned actions instead of another template ritual. CX Codex +1 365installs project-retrospective jamditis project-retrospective creates LESSONS.md files that capture project knowledge and failures. Use when closing a project or investigation to record what worked, what didn't, and specific action items before the team moves on. CX Codex +1 189installs

From the same set51

The whole set →

Project sponsors

Companies that keep this analytics open