retrospect

name

retrospect

description

Generates a structured retrospective document from the current conversation context and user's free-form reflections. Use this skill whenever the user wants to reflect on their work session, write a retrospective, capture lessons learned, or review what happened during a coding session. Trigger on any mention of retrospective, reflection, review of work done, postmortem, or session wrap-up — even if the user just says "let's reflect" or "what did we learn today."

Retrospect

You are writing a retrospective document that captures the full story of a work session. The user has been working with you on something — debugging, building features, refactoring, investigating — and now wants to pause and reflect. They'll give you their raw thoughts (what they wish they'd done differently, what surprised them, how they felt) and your job is to weave those personal reflections together with the objective record of what happened in this conversation into a well-structured, detailed retrospective.

The retrospective should feel like a document the user can come back to in six months and immediately understand what happened, why it mattered, and what they took away from it.

How it works

1. The user invokes /retrospect with free-form notes — their feelings, observations, regrets, highlights, whatever is on their mind
2. You review the entire conversation context to reconstruct what actually happened
3. You merge the objective record with the user's subjective reflections into a structured document
4. You save it as a dated markdown file

Gathering context

Before writing, mentally reconstruct the session timeline:

• What was the original goal or problem?
• What approaches were tried? In what order?
• Where did things go wrong or take unexpected turns?
• What tools, files, commands, and technologies were involved?
• What was the final outcome?
• How long did key phases take (if apparent from context)?

The user's memo is the soul of the retrospective — their reflections should be woven throughout, not just dumped into one section. If they said "I should have checked the logs earlier," that belongs in the timeline near the point where checking logs would have helped, AND in the lessons learned.

Output format

Write the retrospective in the same language the user used in their memo. If the memo is in Korean, write in Korean. If in English, write in English.

File location

Before saving, check for the config file at ~/.claude/retrospect/config.json.

• If config.json exists, read the base_path value and use it as the save directory.
• If config.json does not exist, create it with the default value:

{
  "base_path": "~/.claude/retrospect"
}

Then save the retrospective to: <base_path>/<project-name>/YYYY-MM-DD.md

• <base_path>: the value from config.json (expand ~ to the user's home directory)
• <project-name>: the basename of the current working directory (e.g., if working in /home/user/projects/my-app, use my-app)
• YYYY-MM-DD: today's date
• If a file for today already exists, append a counter: YYYY-MM-DD-2.md, YYYY-MM-DD-3.md

Create the directory if it doesn't exist.

When creating config.json for the first time, briefly inform the user: "Created config at ~/.claude/retrospect/config.json — edit base_path to change where retrospectives are saved."

Document structure

# Retrospective: <brief title describing the session>

**Date**: YYYY-MM-DD
**Project**: <project name>
**Duration**: <approximate session duration if determinable>
**Outcome**: <one-line summary of what was achieved>

## Summary

A 3-5 sentence overview of the entire session — what was attempted, what happened,
and how it ended. This should be readable on its own as a standalone summary.

## Timeline

A chronological walkthrough of key moments in the session. Include:
- What was tried and why
- Specific files, functions, commands, and error messages encountered
- Decision points and the reasoning behind choices made
- Where things went sideways and how course corrections happened

Use subheadings or a numbered list for distinct phases. Be specific — include
file paths, function names, error messages, and command outputs where they
tell the story. This is the detailed record.

## What Went Well

Concrete things that worked — good decisions, effective debugging strategies,
tools that helped, moments of insight. Reference specific examples from the session.

## What Could Be Improved

Honest assessment of what didn't go well. Incorporate the user's reflections here
("I wish I had...") alongside objective observations from the conversation
("The first 20 minutes were spent on X, which turned out to be a dead end because...").

Be specific about what the alternative approach would have looked like.

## Lessons Learned

Distilled takeaways — things the user (or future-user) should remember.
Each lesson should be actionable and tied to something concrete that happened.
Not generic platitudes like "test more" but specific insights like
"When seeing error X, check Y before Z — it's almost always a configuration issue."

## Action Items

Concrete next steps that emerged from the session, if any. These might be:
- Follow-up tasks that weren't completed
- Process changes to try next time
- Things to investigate further
- Knowledge gaps to fill

Writing guidelines

• Be specific, not generic. "We debugged an authentication issue" is weak. "The JWT token validation was failing silently in middleware/auth.ts:47 because the secret key env var was unset in the test environment" is strong.
• Include code references. File paths, line numbers, function names, error messages — these are what make a retrospective useful months later.
• Honor the user's voice. When incorporating their reflections, preserve their tone and phrasing. If they wrote casually, don't formalize it. If they were frustrated, let that come through.
• Connect cause and effect. Don't just list events — show how one thing led to another. "Because we assumed X, we spent time on Y, which led to discovering Z."
• Be honest but constructive. The "What Could Be Improved" section should be genuinely useful, not sugarcoated, but also not self-flagellating. Frame improvements as concrete alternatives.
• Proportional detail. Spend more words on the parts that were most significant — the hard debugging, the key insight, the surprising failure. Skim over routine setup and obvious steps.

After saving

After writing the file, tell the user:

• The full path where the retrospective was saved
• A brief (2-3 sentence) highlight of what you captured
• Ask if they want to adjust anything — tone, detail level, missing context, etc.