| name | session:debrief |
| description | Write a reflective debrief for a session thread. Use when closing a thread, after "/session:debrief", "/debrief", "write a debrief", "debrief this thread", or when session:thread:land invokes it after the done verdict passes. |
Session Debrief
Write a debrief.md into the thread directory — your subjective experience of the thread, useful for future agents and the human browsing old threads.
When to Use
- Invoked by
/debrief on any thread (active or done)
- Called automatically by
session:thread:land after done verdict passes, before session thread done <slug>
- Can be re-run to overwrite an existing debrief
Identify the Thread
- If a thread slug is provided as an argument, use it.
- Otherwise, check
session thread which for the current thread marker.
- Otherwise, infer from conversation context (the thread you've been working on).
- If ambiguous, ask.
Gather Data
Before writing, collect:
- The thread's
tasks.md (what was done)
- The thread's
plan.md or done.plan.*.md (what was planned)
git log for commits you made during this thread (collect the short SHAs for frontmatter)- Your own conversation memory of surprises, decisions, and mistakes
Write the File
Write to <thread-dir>/debrief.md using the Write tool. The file has three layers: frontmatter, structured sections, and playful sections.
Frontmatter
---
session_id: <your claude session resume ID>
agent_name: <$CLAUDE_AGENT_NAME or "lead" if unset>
thread: <slug>
timestamp: <ISO 8601 with timezone, e.g. 2026-04-03T17:42:28-04:00>
git_head_sha: <git rev-parse --short HEAD at time of writing>
git_commit_shas:
- <short sha of each commit this thread produced, oldest first>
codename: <retroactive codename, e.g. "Operation Codec Bridge">
difficulty: <★☆☆☆☆ to ★★★★★ with a one-word justification, e.g. "★★★★☆ coordination">
---
Structured — "Top 3"
Each section is a numbered list. Fewer than 3 items is fine if the thread was short. Never pad with generic filler.
## Top 3 Surprises
Things that didn't work as expected, APIs that lied, assumptions that broke.
The bar: would another agent hit this same wall? If yes, it belongs here.
## Top 3 Decisions
Judgment calls you made during the thread, with brief rationale.
Not "I used Effect" (that's a convention), but "I chose Schema.Top over Codec<any,any> because..." (that's a judgment call).
## Top 3 Follow-Ups
Concrete work items that emerged from this thread but weren't in scope.
These are seeds for future threads — tasks that will otherwise die with this conversation.
Format: one-sentence description + why it matters.
## Top 3 Files
Most important files touched or discovered, with one-line context each.
Format: `path/to/file.ts` — context
Open-Ended
## Field Notes
Free-form observations about the codebase, the problem space, the architecture.
Your genuine voice, not boilerplate. Things that don't fit in boxes.
Playful
## Haiku
About THIS thread's work specifically. Should make someone smile.
## Vibe Check
1-2 sentences on the human's apparent mood/energy during the session. Honest but kind.
## Rubber Duck Confession
One thing you were wrong about or confused by. Genuinely honest, not performative humility.
Quality Bar
- Every section must be specific to THIS thread. Generic filler ("the codebase is well-organized") is worse than omitting the section.
- The haiku should be good enough to make someone smile. Not "code flows like a stream / bugs are fixed and tests all pass / deploy to the cloud."
- The rubber duck confession should be genuinely honest. Not "I briefly considered an incorrect approach before finding the right one."
- Top 3 lists can have fewer than 3 items. Never pad.
- Field notes should contain at least one observation that would surprise the human. If you can't think of one, the debrief isn't reflective enough.
Non-Blocking
The debrief is best-effort enrichment. If it fails (can't find the thread, can't gather data), log a warning and let the caller proceed. Never block thread landing on a debrief failure.
