retrospective

What this skill does

# Retrospective — Developer-AI Workflow Analysis

Analyze Claude Code session logs to understand **how the developer-AI collaboration is
working** — what went well, what didn't, and what can be improved. Produce actionable
suggestions for new skills, subagents, slash commands, hooks, and workflow changes based
on actual usage patterns.

This is a true retrospective in the agile sense: looking back at past sessions to
improve future ones. The analysis examines real session logs, not hypothetical best
practices. Each retrospective builds on previous ones — tracking whether past
recommendations were acted on and whether the collaboration is actually improving.

## Dimensions

Five dimensions, each targeting a different axis of workflow improvement:

| Dimension | Question It Answers | Reference |
|-----------|-------------------|-----------|
| **What Went Well** | Which interactions were efficient, successful, and worth repeating? What strengths can be applied to recurring problems? | `references/success-patterns.md` |
| **What Didn't Go Well** | Where did the collaboration break down, waste time, or produce poor results? What is the root cause? | `references/failure-patterns.md` |
| **Skill Opportunities** | What repeated requests or workflows should become reusable skills or slash commands? | `references/skill-opportunities.md` |
| **Workflow Optimization** | How can subagents, hooks, and automation reduce manual effort? | `references/workflow-optimization.md` |
| **Collaboration Antipatterns** | What common developer-AI pitfalls are showing up in these sessions? | `references/collaboration-antipatterns.md` |
| **Session Inventory** | What happened in each session? Which sessions need attention? | `references/session-inventory.md` |

## Subcommands

| Command Pattern | Scope | Reference |
|----------------|-------|-----------|
| `retrospective` / `retrospective all` | All five dimensions | All references |
| `retrospective wins` / `retrospective good` | What Went Well | `references/success-patterns.md` |
| `retrospective problems` / `retrospective bad` | What Didn't Go Well | `references/failure-patterns.md` |
| `retrospective skills` | Skill & Slash Command Opportunities | `references/skill-opportunities.md` |
| `retrospective workflow` / `retrospective automation` | Workflow Optimization | `references/workflow-optimization.md` |
| `retrospective antipatterns` | Collaboration Antipatterns | `references/collaboration-antipatterns.md` |

| `retrospective inventory` / `retrospective sessions` | Session catalog only | `references/session-inventory.md` |

When no subcommand is specified, default to all dimensions plus session inventory.
When a dimension is mentioned by name (even without "retrospective"), match it.

## Execution Principle: One Script Per Agent, Zero Raw Bash Calls

**MANDATORY. Every agent (main context and every subagent) MUST use a dedicated shell
script for ALL Bash operations. No agent may run raw Bash commands like grep, find, jq,
cat, rg, or any data extraction directly. Every command goes into the script.**

Each Bash tool call requires user approval. Running dozens of individual commands causes
confirmation fatigue — the exact antipattern this skill detects. The fix: each agent
creates one script and only ever runs that script. When the agent
needs different data, it edits the script and re-runs it.

### Session directory

Each retrospective run writes all scripts and intermediate output to a **session-scoped
directory** to avoid write conflicts when multiple agents run in parallel:

`/tmp/retro-$$` (where `$$` is the shell PID of the main context)

The main context must create this directory (`mkdir -p /tmp/retro-$$`) before launching
any subagents, and pass the path to every subagent in its prompt.

### How every agent must work

1. **Write** a shell script using the Write tool (no approval needed):
   `/tmp/retro-$$/<agent-name>.sh`
2. **Run it:** `bash /tmp/retro-$$/<agent-name>.sh` (one approval)
3. **Need different data?** Edit the script with the Edit tool (no approval), then
   re-run `bash /tmp/retro-$$/<agent-name>.sh` (one approval). Never create a new Bash call.

### Script assignments (one per agent, no sharing)

| Agent | Script path |
|-------|------------|
| Main context (step 1) | `/tmp/retro-$$/analyze.sh` |
| Inventory subagent (step 4) | `/tmp/retro-$$/inventory.sh` |
| Success patterns subagent (step 5) | `/tmp/retro-$$/success-patterns.sh` |
| Failure patterns subagent (step 5) | `/tmp/retro-$$/failure-patterns.sh` |
| Skill opportunities subagent (step 5) | `/tmp/retro-$$/skill-opportunities.sh` |
| Workflow optimization subagent (step 5) | `/tmp/retro-$$/workflow-optimization.sh` |
| Collaboration antipatterns subagent (step 5) | `/tmp/retro-$$/collaboration-antipatterns.sh` |
| Feedback loop subagent (step 8) | `/tmp/retro-$$/feedback.sh` |

### What goes in the script

Everything. File discovery, JSONL parsing, grep/rg searches, jq queries, line counting,
pattern extraction — all of it. The script outputs structured results to stdout. The
agent reads the output, thinks about it, edits the script for the next query, re-runs.

### Violations (NEVER do these)

- Running `grep`, `rg`, `find`, `jq`, `cat`, `wc`, `sort`, or `awk` as direct Bash calls
- Reading log files one at a time with individual Read or Bash calls
- Creating multiple different Bash commands instead of editing the script
- Asking the user to run commands manually ("run ls", "run wc -l", "run this grep")
- Any Bash tool call that is not executing the agent's own script

## Workflow

### 1. Locate and Read Session Logs

Session logs are JSONL files stored at:
`~/.claude/projects/<project-path-encoded>/<session-id>.jsonl`

To find logs for the current project:
- Encode the current working directory path (replace `/` with `-`, strip leading `-`)
- Look in `~/.claude/projects/<encoded-path>/`
- Each `.jsonl` file is one session

Read all session logs from the last 3 months. Each `.jsonl` file has a modification
timestamp — include every file modified within the last 90 days. Each line in a file
is a JSON object representing one event.

**Use the single-script approach** (see "Execution Principle" above). Write the
analysis script to `/tmp/retro-$$/analyze.sh`, execute it once, then edit and re-run it
as needed to drill into specific patterns. Do not read log files one at a time.

**Key event types to extract:**
- `"type": "user"` — user messages (requests, corrections, interruptions, feedback)
- `"type": "assistant"` — Claude's responses (tool calls, text, thinking)
- `"type": "progress"` — hook events, subagent events
- Tool use results — success/failure of each tool call

**Key fields to examine:**
- `message.content` — what the user asked or what Claude said
- Tool use `name` and `input` — which tools were called and how
- `"is_error": true` — tool calls that were rejected or failed
- User messages containing corrections ("no", "not that", "instead", "wrong")
- Session duration and turn count — session length and density
- `"isSidechain": true` — branched/abandoned conversation paths

**Emotional signal detection:**
Pay attention to user frustration and satisfaction markers in messages:
- ALL CAPS or exclamation-heavy language indicating frustration
- Increasingly terse messages (detailed instructions degrading to one-word corrections)
- Explicit frustration ("this is frustrating", "why can't you", "I give up")
- Resignation signals (user does the task themselves, or says "never mind", "forget it")
- Sarcasm or exasperation ("sure, whatever", "fine")
- Rapid topic switches (user abandons a task without resolution)
- Positive signals: "perfect", "exactly", "nice", "that's great" — mark what worked

A user who silently gives up is a worse outcome than one who corrects Claude five times
and gets the right result. Frustration and resignation are the highest-priority signals
because they represent problems the user stopped trying to fix.

### 2.