---

name: reflect description: >- Runs a structured retrospective over a work session: reports problems, solutions, insights, and friction; derives an improvement plan categorized as memory, rule, skill, documentation, or tooling/process; and applies only the items the user picks. Use as a deliberate end-of-session ritual to capture learnings before they evaporate. argument-hint: "[last N sessions | last N commits | <rev>..<rev>] (default: current session)" disable-model-invocation: true

Reflect

Run a retrospective over the evidence in scope, report what happened in the chat, and turn the learnings the user picks into durable improvements. The report is ephemeral — the durable output is the applied items.

Workflow

1. Resolve scope

Argument: $ARGUMENTS

• No argument → the current session. The evidence is the in-context conversation itself — do not read the session's own transcript file; the conversation is already in context, and this works on surfaces that have no local transcripts.
• last N sessions → the N most recent past session transcripts. Locate, cap, and summarize them per sources.md — one subagent per transcript, each returning problems, solutions, insights, and friction.
• last N commits or an explicit revision range (e.g. v1.2..HEAD) → git history per sources.md — works in repos and on machines with no transcripts at all.

2. Analyze the evidence

For the current session, mine the conversation directly; for transcript and git scopes, synthesize across the subagent summaries. Either way, extract:

• problems and issues that arose (errors, wrong turns, rework, misunderstandings)
• solutions that worked (fixes, commands, approaches worth repeating)
• notable insights (repo quirks, clarified conventions, facts worth remembering)
• recurring friction (anything that slowed work down more than once)

3. Report in the chat

Fixed sections, in this order:

1. Problems & issues
2. Solutions found
3. Notable insights
4. Recurring friction

Chat output only — never write a report file, journal, or reflections directory.

4. Derive plan items

Derive a short improvement plan from the report. Each item:

• cites the observation it derives from (report section + entry)
• is categorized per targets.md — memory, rule, skill, documentation, or tooling/process; when several categories fit, the most automatable wins
• names its concrete target (file or directory) from the target map

5. Dedup against existing artifacts

Before proposing, check each candidate for existing coverage:

• memory — the memory directory's MEMORY.md index and the memory files it links
• rules — AGENTS.md and .claude/rules/*.md
• docs — the README.md-indexed files in guides/ and cheatsheets/

(In a non-handbook repo, check the discovered artifacts from targets.md instead.) An already-covered learning is dropped, or — when the new evidence adds something — converted into an update-proposal for the existing artifact. Never propose a duplicate.

6. Present the plan — gated multi-select

Present the surviving items as a multi-select: use a structured question tool if the surface has one, otherwise format the options clearly in the conversation (the fallback rule in ../clarify/question-rules.md). Each option shows category, target, and the cited observation. Selecting nothing is a valid outcome.

7. Apply picked items only

• Write each picked item to its target per targets.md; write nothing else.
• A tooling/process item beyond a trivial edit (new CI job, refactor, test suite) is never implemented inline — recommend running write-prd / create-plan for it and leave it at that.
• Never commit. Committing stays a separate, user-approved step (/commit).

Constraints

• Reflection is a deliberate user ritual — never auto-trigger it mid-task.
• Declining every plan item means zero writes; the skill ends with no file changes.
• The report is chat-only; no persisted reflection artifact of any kind.
• Never write to a target the current repo does not actually have — see the resolution rules in targets.md.

Quality

Run the shared self-review checklist on every applied item before presenting the result.