debrief

name	debrief
description	Debrief — Review the current session and persist lessons learned
disable-model-invocation	true

Debrief

Conduct a structured debrief of the current conversation to extract and persist lessons learned.

Instructions

Walk through the following steps as an interactive conversation with the user. Do NOT rush through all steps at once — ask questions, wait for answers, and discuss before saving anything.

Step 1: Session Recap

Briefly summarize what happened in this session (key tasks, decisions, surprises, blockers). Keep it to a few bullet points. Ask the user if you missed anything or got something wrong.

Step 2: Extract Lessons

Ask the user about each of these categories. Skip any that don't apply, but probe on the ones that do:

• What worked well? — Approaches, tools, patterns, or decisions that paid off.
• What didn't work? — Missteps, dead ends, or friction.
• What did we learn about the codebase or project? — Non-obvious context, gotchas, or architectural insights.
• What did we learn about your preferences or workflow? — How you like to work, communicate, or make decisions.
• Any external resources worth bookmarking? — Docs, dashboards, channels, tools discovered during the session.

Extract lessons without pre-assigning a persistence mechanism — that happens in Step 3. Focus here on what was learned, not where it should live.

Step 3: Plan Persistence

For each lesson or takeaway from Step 2, identify the right persistence mechanism. Load the codification-reference skill for the full mechanism taxonomy and selection principles. Then present a proposed plan to the user — a table or checklist mapping each item to its mechanism and a brief rationale. Discuss and refine before executing anything.

Guidelines:

• Match the mechanism to the lesson. For each item, evaluate where it naturally belongs based on: Who needs it? (just this agent, this project, all projects?) How durable is it? (session-specific insight vs. lasting convention?) Can it be enforced mechanically? (test, linter, hook vs. guidance that requires judgment?) Is there an existing place where someone would look for this? (a skill, a doc, a config file?) The best mechanism is the one whose scope, durability, and enforcement model match the lesson — not necessarily the "strongest" one on an abstract hierarchy.
• Show your reasoning. Before proposing a mechanism, walk through the evaluation criteria out loud for each item: state the scope, durability, enforceability, and where someone would look for it. This makes the reasoning visible and correctable — don't jump straight to a recommendation.
• Discuss tradeoffs. If the right mechanism isn't obvious, present options with pros/cons rather than assuming.
• Group related items where it makes sense (e.g., several related feedback points into one memory).
• Check for duplicates — read MEMORY.md, existing CLAUDE.md, and relevant config before proposing additions.
• Distinguish the fix from the pattern. A fix in code is self-documenting, but the pattern that caused the problem may recur in new code. Before marking a lesson as "None — fix is in the code," ask: will someone writing new code in this area hit this same class of problem? If so, the pattern deserves a home (guide, skill, doc) even though the specific fix doesn't.
• For memories: use the correct type, and include Why: / How to apply: for feedback and project types.

Step 4: Execute

Work through the approved plan, one item at a time. Show the user what you're writing/changing and get confirmation before each write. Mark items complete as you go.

Step 5: Wrap Up

Summarize what was persisted, grouped by mechanism. Call out anything that was discussed but intentionally not persisted (and why). Suggest any remaining follow-up actions.

Step 6: Check for Recursive Lessons

The debrief conversation itself often surfaces new lessons — about workflow preferences, mechanism selection, tooling gaps, or collaboration patterns. Before closing:

1. Review the debrief discussion for lessons that emerged during the debrief (not from the original session).
2. Corrections are a signal. If the user corrected your proposals during this loop — wrong mechanism, wrong framing, wrong scope — that correction itself is likely a lesson worth codifying. Default toward another iteration rather than closing out.
3. If there are lessons worth codifying, tell the user what you found and ask if they'd like to run another iteration starting from Step 1, scoped to the debrief conversation itself.
4. If nothing new surfaced and no corrections were needed, close out.