# Hook: Session Retrospective (Stop)

At the end of every Claude Code session, automatically asks Claude to summarise what was learned and categorise it into CLAUDE.md updates, new rules, skill ideas, and ADRs.

## What it does

- Fires on the `Stop` event
- Writes a retrospective prompt file to `.claude/retro-pending.md`
- On your next session, you can run `/retro` to process the learnings
- Captures: new patterns discovered, bugs encountered, decisions made, improvements to make

## settings.json entry

```json
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/session-retro.sh"
          }
        ]
      }
    ]
  }
}
```

## Hook script: session-retro.sh

```bash
#!/usr/bin/env bash
# Stop hook: write session retrospective prompt for next session
set -euo pipefail

INPUT=$(cat)
CWD=$(echo "$INPUT" | jq -r '.cwd // "."')
STOP_REASON=$(echo "$INPUT" | jq -r '.stop_reason // "normal"')
TIMESTAMP=$(date '+%Y-%m-%d %H:%M')
TOTAL_COST=$(echo "$INPUT" | jq -r '.total_cost_usd // 0')

# Only write retro for meaningful sessions (not immediate exits)
if [[ "$STOP_REASON" == "interrupt" ]]; then
  exit 0
fi

RETRO_FILE="$CWD/.claude/retro-pending.md"
mkdir -p "$(dirname "$RETRO_FILE")"

cat > "$RETRO_FILE" << EOF
# Session Retrospective — ${TIMESTAMP}
Cost: \$${TOTAL_COST} | Reason: ${STOP_REASON}

## Retrospective prompt (run at start of next session)

Ask Claude:
"Review the recent session history. Identify and categorise any learnings:

1. **CLAUDE.md updates** — new project conventions, commands, or context that should be persistent
2. **New rules** — coding standards or patterns worth adding to rules/
3. **Skill ideas** — repetitive workflows that deserve a /skill
4. **ADRs** — architecture decisions made that should be documented
5. **Bugs discovered** — issues found that aren't yet fixed

Format each item as a specific, actionable addition. Skip categories with nothing to add."

---
*Generated by session-retro hook. Delete this file after processing.*
EOF

echo "📝 Retrospective queued: $RETRO_FILE" >&2
exit 0
```

## Setup

```bash
mkdir -p ~/.claude/hooks
cp session-retro.sh ~/.claude/hooks/session-retro.sh
chmod +x ~/.claude/hooks/session-retro.sh

# Add .claude/retro-pending.md to gitignore
echo ".claude/retro-pending.md" >> .gitignore
```

## Processing the retrospective

At the start of your next session:
```bash
# Check if a retro is pending
cat .claude/retro-pending.md

# Then in Claude Code, paste the prompt and process the learnings
# After processing, delete the file:
rm .claude/retro-pending.md
```
