Skip to content
Michi v2026.11.16
Save the Tokens

michi-debrief

The debrief skill runs after an implementation session completes. It is how Michi iterates spirally rather than in circles — each debrief improves the next session by capturing learnings, evolving verification scenarios, and calibrating how much autonomy the agent has earned. It can run in the same session (benefits from retained context) or a fresh session (clean perspective, no compaction bias).

  • After completing a /michi-session milestone
  • After multiple milestones have accumulated without review
  • When you want to assess what was delivered versus what was planned
  • When decisions from a session need human review before the next milestone

Scaled to the work. A full debrief is the default for epic milestones. A short debrief, a summary entry in docs/journal.md (or the epic’s journal), fits workshops, freeform paired work and small sessions. Trivial changes can skip it. When the right depth is unclear, the agent asks you: full debrief in debriefs/, short summary in the journal, or skip. A full debrief runs three passes, all required: Capture, Invalidate, and Currency + Cleanup.

Delivery assessment. The agent compares what was planned against what was delivered, checking each acceptance criterion explicitly. It tallies results — test counts for code, exit criteria for non-code — and verifies all milestones are committed.

Decision and discussion review. The agent reads the Decisions and Discussion sections from each milestone’s plan doc. For decisions: were they reasonable? Should any be reversed or codified as patterns? If the epic has a north-stars.md, did a decision trade one of your fixed points for near-term expedience? The agent quotes the line it strains against. For discussion items: resolve now, defer with rationale, or promote to a project-level question.

Bug and gap analysis. For each bug found during the session, the agent asks what scenario would have caught it and writes that scenario in Given-When-Then format. This is how the verification set evolves — driven by actual failures, not imagined ones. Cross-package gaps get specific attention (missed schema updates, hardcoded assumptions).

Process observations. What worked, what didn’t, where the skill guidance helped or hindered. Scenario quality gets its own assessment — were Level A scenarios useful? Too granular or too vague? Did the agent execute them faithfully? The debrief also determines the lifecycle of verification artifacts: promote new scenarios to the catalog, update scenarios broken by intentional changes, retire ones no longer relevant.

Knowledge capture. Domain learnings go to the epic’s journal. Process learnings go to patterns. A contract-change that altered behavior something already relied on is recorded in the project-level journal as a Behavior change: paragraph: what it was, what it is now, and what relies on it. The journal outlives the epic’s spec, so one search finds every change. Human interventions on code quality get captured as applied examples in docs/reference/code-style.md. Memory-worthy content — collaboration patterns, corrections, confirmed approaches — updates docs/memory.md.

Invalidate. The second pass asks what the milestone broke. For every mechanism it changed, the agent greps docs/ and updates or removes references that are now wrong. It reads affected ARCHITECTURE.md sections cold and either refreshes their last-verified: stamp or fixes them. It updates or annotates superseded entries in docs/reference/key-decisions.md and patterns.md, and retires docs/memory.md entries that have aged out. These edits land outside the epic, so expect them in the diff.

Currency + Cleanup. The third pass reads root docs cold: STATUS.md always, and CLAUDE.md, PROJECT.md or ARCHITECTURE.md when the milestone might have affected them. It refreshes last-verified: stamps on sections it re-verified, and lists archive candidates (completed plan docs, landed sidebars, outdated debriefs) in the debrief for you to decide on; it doesn’t move them.

Trust calibration. The agent assesses signals that trust increased (all criteria met, decisions well-documented, no post-completion bugs) versus signals it decreased (premature “done” claims, skipped verification, unescalated decisions). It recommends an autonomy level for the next session.

  • Debrief artifact at docs/epics/<epic>/debriefs/mN-debrief.md — the primary output, holding the full assessment from all three passes and the trust calibration. It is named for the milestones debriefed (m3-m4-debrief.md for a combined session); a flat-file epic’s goes in docs/epics/<epic>/debriefs/<epic>-debrief.md. Chat gets only a short summary of the findings that change what happens next.
  • Journal entry in the epic’s journal.md (or docs/journal.md) — domain learnings, gotchas, and open questions worth preserving outside the debrief
  • Pattern updates to docs/reference/patterns.md — new patterns with high confidence
  • CLAUDE.md updates — durable, broadly applicable rules surfaced by the session
  • STATUS.md update reflecting current state and what’s next — and trimmed: finished work leaves the active list as one line and a pointer, so the file doesn’t grow every session
  • Scenario catalog updates — new scenarios from error analysis, updated or retired existing ones
  • Code-style updates to docs/reference/code-style.md — applied examples from human interventions; an existing entry is revised or retired before a new one is added, because the file is loaded into every session
  • Memory update to docs/memory.md — new collaboration patterns and mental model changes, plus retirement of entries the session superseded, so review deletions as well as additions
  • Reference-doc edits wherever the Invalidate pass found drift, with refreshed last-verified: stamps
  • Trust recommendation for the next session’s autonomy level
  • Long sessions benefit from a fresh-session debrief — the agent’s compacted context may have lost nuance from early in the session.
  • The most valuable scenarios come from actual failures. Error analysis during debrief is how the verification set gets stronger over time.
  • The debrief is where human code-quality interventions get captured. If you corrected the agent’s approach during the session, the debrief ensures that calibration persists.
  • The natural next step is /michi-planning for the next milestone, or /michi-sustainability if accumulated work needs a broader health check.

For the full agent instructions, see the SKILL.md source.