C² Method8 min read
What goes in a session brief: a template and three real briefs
The handoff template I use with Claude Code, section by section, and three real briefs from my repos with what each part bought the next session.
A good Claude Code session handoff answers one question for a reader who has nothing else: where is the work, really? In practice that means seven parts. The goal. What changed, with commits. The decisions and why. What was verified, with real numbers. What was not verified. Who owns any blocker. And a start state for the next session, down to the first action.
If you have never written one, start with write your first session brief, which covers the habit. This article is the next step: the full template I use in my own repos, section by section, and three real briefs from them, trimmed and annotated, showing what each part bought the session after it.
The session brief template, section by section
The C² Method ships a session brief template in its starter kit, at docs/02-working/session-briefs/session-brief.md. The header of that template says what it is for: this is AI memory. The async stand-up is a side effect.
Here are its sections and what each one is for.
| Section | What goes in it | What it buys the next session |
|---|---|---|
| Session goal | One sentence, plus links to the prompt brief and PRD | Knows what "done" was meant to mean |
| What was done | A table of items with status, files and commits | Can check the claims against git in seconds |
| Decisions made | Each decision with its reason | Doesn't re-argue a settled choice |
| Blockers | Each one, with the layer that owns it | Knows what it can't fix from here |
| Key discovery | Any trap found. If filled, a gotcha file goes in the same commit | Doesn't pay to find the trap again |
| Documentation obligations | Docs due now, at PR, or at release | Knows what is still owed |
| Test debt | Tests deferred, with the reason | Doesn't assume coverage that isn't there |
| Next session start state | Start here, context it needs, outstanding work, first action | Moves in the first minute, not the twentieth |
| Landing zone | Believed landing date, percent complete, confidence | Anyone can see progress without a meeting |
The template has a gate I'd keep even if you drop everything else: if the Key discovery section has content, a file in docs/03-knowledge/ is required in the same commit. Not later. A discovery that lives only in a session brief gets read once and then sinks under the next hundred briefs. A gotcha file gets read every time someone touches that area. (More on that in the gotchas folder.)
Real briefs rarely use every heading. The three below don't. What they all keep is the core: what changed, what's verified, what isn't, and what's next.
Real brief 1: an overnight run on this site
This one is from the repo for stuartleo.com, dated 17 to 18 November 2026. I'd asked an agent to fix a broken image on /c2, then review the whole site overnight. Trimmed and reflowed for width, with preview URLs and a server address removed:
# Session brief: overnight SEO fixes, content review, new articles (2026-11-17 → 18)
## Shipped to main (all verified live)
| Commit | What |
|---------|------|
| b4e0256 | /c2 terminal screenshot was never copied from the c2method.ai repo.
| Article OG: generateImageMetadata gave every article ~97 og:image
| tags (first = wrong article) ... Gotcha:
| docs/03-knowledge/gotchas/generate-image-metadata-fans-out-to-every-page.md |
| bbcf3d6 | IBM Plex self-hosted (app/fonts, next/font/local). The 8bf68f5 deploy
| failed fetching Google Fonts, the same as 2026-11-09.
| Gotcha: next-font-google-fails-host-builds.md |
Crawl: all 269 sitemap pages, no other broken <img>.
## Needs Stuart (outside the repo)
1. www.stuartleo.com serves "This is the default server vhost" from an old
origin. It is indexed (61 impressions). Fix in Cloudflare DNS or a redirect rule.
2. http:// isn't redirected to https://. Turn on Always Use HTTPS.
## Notes for next session
- Remove the worktree after merge: git worktree remove ../stuartleo-content
- The stuartleo CLAUDE.md is stale: it says Next.js 15.
## Morning follow-up (2026-11-18)
- www and http fixed by Stuart in Cloudflare. A redirect rule sends
https://www.stuartleo.com/* to https://stuartleo.com/${1} (301), and
Always Use HTTPS is on. Verified: http://, http://www. and https://www.
all end on the apex, with the path and query string kept.
What each part bought.
The shipped table carries a commit hash per row. When I read it in the morning I didn't take "fixed" on trust. I could open each commit. That matters more for overnight runs than any other kind, because nobody watched them happen.
"Crawl: all 269 sitemap pages" turns "I checked the images" into a claim with a size. A reader can tell the difference between checking one page and checking all of them.
Two rows point at gotcha files written in the same session. The font failure had already happened once, on 9 November. The second time, it got written down. The next agent that touches fonts on this site reads one short file instead of rediscovering a flaky build.
"Needs Stuart (outside the repo)" is the section I value most here. The agent couldn't reach the DNS zone, so instead of guessing it named the exact two settings and handed them to me. The morning follow-up, appended to the same brief, shows those two items closed and verified three ways. One file holds the problem, the owner, the fix and the proof.
Real brief 2: a Commander Desktop feature
Commander Desktop is the Mac app I'm building, where agents run in terminals beside your work. On 29 October 2026 I asked for a side-by-side layout: a note on the left, an agent's terminal on the right, for working on a 16-inch laptop. Trimmed:
# Session brief: terminals docked on the right (side by side with the page)
Lane: commander-desktop. Stuart, 2026-10-29: loves the stacked layout, but
wants a column side by side view when reading a note or a Spark while
chatting with an agent (16-inch laptop). This is step 1 of three (side by
side, then pop out a terminal into its own window, then content windows).
The stacked layout is the default and is unchanged.
## Verified
vitest 907 passed (1 skipped); tsc clean; cargo test --lib 927 passed + the
known termhost environment failure; Rust round-trip test (old layout loads
with no dock and saves without the keys). Browser harness: screenshots at
1440x900 stacked (unchanged), 1440x900 right, 1100x700 right ... One bug
found and fixed from them: the terminal list was clipped to 13px by a
percentage max-height.
## Not verified (needs the live app)
- A real terminal in the right dock: refit on drag and on toggle (the mock
has no terminals), agent TUIs at 25–30% width.
- The look with many terminals in the list under the terminal.
- windows.rs builds repository windows with a default layout, so a window
opened for one repository shows the stacked layout whatever the main
window chose.
## Next
Pop-out of a terminal into its own window (kept terminals first, since the
host lets a second window reattach by tag), then content windows.
What each part bought.
The opening paragraph keeps my words and my reason (the 16-inch laptop). A later session that wants to "tidy up" the layout knows the stacked view is the one I like, and the side-by-side dock is the extra.
"Step 1 of three" sets the order. The next brief, written the same day, is step 2: the pop-out terminal. Its first design decision builds the pop-out windows in windows.rs, the file the dock brief had flagged.
The verified section gives counts and a known failure by name. "+ the known termhost environment failure" stops the next session from losing an hour chasing a red test that was red before it started.
The "Not verified" list is the honest half. The mock has no terminals, so nothing proved a real terminal refits when dragged. Without that list, a reader sees green tests and screenshots and assumes the feature works in the app. With it, they know exactly what to try first in the live app, and why the tests couldn't cover it.
Real brief 3: a Host release change
Host is the part of Waymaker where apps are built and released. On 6 November 2026 I changed how new Solutions (groups of apps released together) ship: straight to production on push by default, with a gated release as an owner's opt-in. Trimmed, with internal names made generic:
# Session brief: new Solutions push to production by default again (option A), 2026-11-06
## Why
Stuart (2026-11-06): "i do not want our 'Solution Release' thing in Host to
be blocking a standard release process ..." He chose option A: new Solutions
push by default, and Release stays an owner opt-in.
## What changed
- A migration that changes the default to push, NOT APPLIED. Existing
rows are untouched. The rollback sits next to it.
## Not in this PR (files this lane can't touch), sent to the owner as lines
- The Host skill file says release is the default for every Solution.
After the migration, push is. Exact line given.
- The test workflow: add the new test file to the Host test step.
## Next
- The agent that owns migrations applies it on Stuart's word.
- Help has no article on how a Solution releases. Backlog entry added.
What each part bought.
"NOT APPLIED", in capitals, on the migration. In my repos a merge deploys code but doesn't apply migrations, so code and database can disagree for a while. The very next day, a different session building the plain-language release modes read this and wrote in its own brief that Help doesn't state the default for new Solutions, because the migration was headed NOT APPLIED and the lane couldn't check production. It didn't document a default that might not be live yet. That's one line in one brief preventing a wrong help page.
"Not in this PR, sent as lines" handles the files this agent wasn't allowed to touch. It doesn't skip them silently, and it doesn't break the rule. It writes the exact change for whoever owns those files, here the coordinating agent that merges and owns workflows and skills.
The last "Next" line, "Help has no article on how a Solution releases", became item 3 of the next day's prompt brief, which wrote that article.
What the three have in common
None of them is a transcript. None restates the prompt brief. None says how the session felt.
All three separate verified from believed. All three name what is outside the session's reach and who owns it. All three end with a next move specific enough to start on. That's the core of a handoff template. Everything else is optional.
The biggest single habit: write the "Not verified" list as carefully as the "Verified" one. Agents report success fluently. The brief is where you make them say what they didn't check.
A minimal handoff template you can copy
If the full template feels heavy, this is the shape all three briefs above share:
# Session brief: <topic> (YYYY-MM-DD)
## Why
<One paragraph: what was asked, by whom, in their words if possible.>
## What changed
| Item | Commit | What |
|---|---|---|
## Decisions
- <Decision>: <reason>
## Verified
<Commands run and their counts. Name known failures that were already red.>
## Not verified
- <What no test or check covered, and what would prove it.>
## Outside this session
- <Blocker or change someone else owns, with the exact ask.>
## Next
Start here: <file or task>. First action: <one instruction>.
Gotcha written: <path, or "none">.
Naming briefs so tools can find them
Name briefs by date, consistently: YYYY-MM-DD-topic.md. It sounds fussy. Here's why it isn't.
My main repo has a Claude Code SessionStart hook that lists the last 30 days of briefs at the start of every session. It once matched only names ending in -session-brief.md. From 19 August 2026 briefs dropped that suffix, and the hook went blind: every session booted showing an 18 August brief as the newest. The fix was a hook that tolerates every format in use, and a pre-commit check that refuses a new brief named any other way. That repo's 2026 folder holds more than 1,100 briefs, and the hook still puts the newest at the top of every session.
The template is the easy part. The habit is writing one every time the context is about to go: end of day, a meeting, a full window, a reboot. Five minutes at the end buys a running start at the next one.
Start here: write your first session brief, how to stop Claude Code losing context between sessions, or run your first C² session.
Questions people ask
- What should a Claude Code session handoff include?
- The goal of the session, what changed (with commits or files), the decisions made and why, what was verified with real counts, what was not verified, any blocker and who owns it, any trap discovered, and a start state for the next session: where to begin and the first action. The 'not verified' part is the one most often skipped and the one that saves the most time.
- How long should a session brief be?
- As long as the session's state needs. My briefs run from about 20 lines for a small change to a few hundred for a release with several review rounds. The test is whether a fresh session that reads only the brief can carry on without asking you anything.
- Where should session briefs live?
- In the repository, committed with the work, in a dated folder such as docs/02-working/session-briefs/ with names like YYYY-MM-DD-topic.md. A consistent name matters because hooks and scripts that list recent briefs sort by it.
- Is a session brief the same as a commit message or a PR description?
- No. A commit message explains one change. A PR description explains a diff to a reviewer. A session brief explains the state of the work to whoever picks it up next: what is done, what is only believed to be done, and what to do first.
- Can Claude Code write the session brief itself?
- Yes, and in my repos it usually does, at the end of the session, from a template. The pilot's job is to check the verified and not-verified sections are honest before it is committed.
Part of the C² Method. Start with the method
Put this in your repo
The C² Method is free and open. Point your agent at the kit and get started in minutes.