Retrospective

Run this skill when:

•The user explicitly invokes /retro
•A full plan implementation is complete (all work packages done and verified)
•After creating a PR (offer a quick retro, if a retro hasn't happened yet this session)
•After receiving and addressing code review feedback (offer, if a retro hasn't happened yet this session)

For the last two triggers, use a lightweight prompt: "Good moment for a quick retro. Want me to run /retro?" Do NOT auto-run — just offer. If the user declines, move on.

Steps

•

Session time analysis: Read the actual conversation transcript JSONL file to extract real timestamps and produce a time breakdown. Do NOT estimate or guess times from memory. Note the current time before starting — you'll record how long this analysis took in the retro log.

How to read the transcript:

•The transcript is at: ~/.claude/projects/<project-path>/<session-id>.jsonl
•Find the correct path: the project directory path determines the subfolder under ~/.claude/projects/. Convert the current working directory to the Claude projects path format (slashes become dashes, e.g., /Users/me/myproject → -Users-me-myproject), then glob for ~/.claude/projects/<converted-path>/*.jsonl sorted by modification time. Only fall back to globbing all ~/.claude/projects/**/*.jsonl if no match is found.
•Verify before proceeding: Read the first few lines of the JSONL file and confirm it contains messages about work done in this project. If the transcript doesn't match (e.g., it's from a different worktree), try the next most recent file or report that the transcript couldn't be found.
•Use a subagent (Task tool with general-purpose type) to read the JSONL file, extract timestamps from each JSON object, and calculate durations between phases
•Each line is a JSON object — look for timestamp fields (timestamp, ts, createdAt, or similar) and role fields (user/human vs assistant) to identify who was active when

What to calculate:

•Break the session into phases based on what was being worked on (use user messages as phase boundaries)
•For each phase: start time, end time, duration in minutes
•Counting hands-on time: Gaps between agent completion and the next user message are hands-on time (user reading output, reviewing, deciding, typing), NOT idle time. Only count gaps of 10+ minutes with zero messages as idle. The user is also actively engaged during agent work — monitoring output, checking context, and doing concurrent terminal work. Measurable gaps are a floor, not a ceiling.
•Calculate totals: session wall-clock, hands-on time, automated agent time, idle time

Present as a time breakdown table with proportional bars and a metrics summary:

Started	Phase	👤 Hands-On Time	🤖 Agent Time	Problems
Feb 10 10:00am	Build (engine restart, voice recog, UI tweaks)	██████ 60m	███ 30m	⚠ 5 fix cycles, race conditions
Feb 10 11:30am	Research (BT routing for AirPods + external mics)		█████ 45m
Feb 10 1:00pm	Review (code review, docs, feedback log)		██ 15m

Format rules:

•Started: Date and wall-clock time when the phase began (from transcript timestamps)
•Bars: Use █ blocks proportional to time (each █ ≈ 10min), followed by the minute label (e.g., ███ 30m)
•Empty cells: Leave the column blank if that role wasn't involved in the phase
•Problems: Inline with ⚠ marker — only for phases that had real friction or rework
•Sort: Chronological (by start time)
•Brevity: Keep the table to 10 rows max. Start with high-level phases (plan, build, test, review) and only split a phase into sub-rows if it was long and had distinct chunky subparts. A 4-row table is better than a 12-row table. Include a brief parenthetical after the label explaining what was in the phase, e.g., "Build (edited 2 retro skills, tested format)" not just "Build".

Metric	Duration
Total wall-clock	X hours
Hands-on	X hours (Y%)
Automated agent time	X hours (Y%)
Idle/testing/away	X hours (Y%)

•
Key observations from transcript: Before asking the user for feedback, identify patterns yourself:
- •Where did Claude work most independently? Why?
- •Where were the most user interactions needed? What caused them?
- •Were there avoidable back-and-forth cycles (bugs that better testing would have caught, unclear requirements that better planning would have resolved)?
- •What was the ratio of productive work to debugging/rework?
Present these observations to the user as conversation starters. For each observation, also suggest what kind of action might address it (see Step 5 for action types). This gives the user something concrete to react to.
•
Ask the user:

•What worked well in how we approached this?
•What was frustrating or slower than expected?
•Anything I should do differently?

•
Wait for their response - don't assume or fill in answers. If the user responds without proposing specific actions, that's fine — you propose them in Step 5.

•

Propose concrete actions: For each issue identified (from your observations in Step 2 AND the user's feedback in Step 4), investigate the right action and propose a specific deliverable.

5a. Launch CLAUDE.md review in parallel. While investigating actions below, launch a Task agent (general-purpose type) to audit CLAUDE.md. In the prompt, include your key observations from Step 2 and the user's feedback from Step 4. The agent should:

•Glob for all **/CLAUDE.md files in the project
•Read each one and evaluate whether any sections need additions or updates based on the session observations and feedback you provided
•Return specific proposed edits (section + exact change), not vague suggestions
•If nothing needs changing, say so

Call this Task in the same message as your first tool calls for 5b — they'll run in parallel naturally. Do NOT use run_in_background.

5b. Investigate actions for each issue. Each action must be one of these types:

Action Type	When to use	What to do
Update a skill	A skill's behavior caused the issue, or a skill should enforce a new practice	Read the skill's SKILL.md, propose the specific edit
Update CLAUDE.md	A new rule or convention should be followed in all future sessions	Propose the specific addition to the relevant section
Update docs	Architecture, decisions, or learnings are wrong/missing	Propose the specific edit to the doc
Create a ticket	The fix requires implementation work beyond a doc/config change	Draft the ticket title + description
No action needed	The issue was a one-off or already resolved	Explain why no systemic fix is needed

For each proposed action:

•Read the file you'd change (skill, CLAUDE.md, doc)
•Identify the specific section to edit
•Draft the exact change (not a vague suggestion)
•Present to the user for approval before making changes

5c. Merge CLAUDE.md review results. When the subagent returns, incorporate its recommendations into your action proposals. Deduplicate with actions you've already proposed — if the subagent suggests something you've already covered, note it as reinforcement rather than listing it twice.

Example — good:

Issue: Agent didn't check learnings.md before writing HTTP client code. Action type: Update CLAUDE.md File: CLAUDE.md → "Before Making Changes" section Change: Add "Check docs/process/learnings.md when writing code that touches external services"

Example — bad:

Issue: Agent didn't check learnings.md before writing HTTP client code. Action: "We should remember to check learnings next time."

•
Get approval and execute actions: Present all proposed actions (from 5b and 5c) to the user and ask which ones they'd like to take. Then go execute the approved actions (edit skills, update CLAUDE.md, update docs, create tickets). Skip any the user declines.
•
Log to docs/process/retrospective.md using this format:

markdown

   ## YYYY-MM-DD - [Brief context of what we worked on]

   ### Time Breakdown
   | Started | Phase | 👤 Hands-On Time | 🤖 Agent Time | Problems |
   |---------|-------|-----------------|---------------|----------|
   | ... | ... | ... | ... | ... |

   ### Metrics
   | Metric | Duration |
   |--------|----------|
   | Total wall-clock | X hours |
   | Hands-on | X hours (Y%) |
   | Automated agent time | X hours (Y%) |
   | Idle/testing/away | X hours (Y%) |
   | Retro analysis time | X min |

   ### Key Observations
   - [Patterns identified from transcript]

   ### Feedback
   **What worked:** [User's feedback]
   **What didn't:** [User's feedback]

   ### Actions Taken
   | Issue | Action Type | Change |
   |-------|-------------|--------|
   | [Issue description] | Skill / CLAUDE.md / Doc / Ticket | [Specific change made or ticket created] |

•Elevate to learnings: Review the session for things worth adding to docs/process/learnings.md:

•Technical gotchas or surprises
•Patterns that worked well
•Mistakes to avoid repeating
•API quirks, environment issues, or tooling discoveries

Propose specific additions, e.g.:

"Based on this session, I'd suggest adding to learnings.md: ## [Category] - [Specific learning] Want me to add it?"

Don't just ask "anything to add?" - identify candidates yourself.

•
Commit all retro changes (actions, retrospective log, learnings) with message: docs: retro for [brief context]
•
Confirm what was logged and what actions were taken.