Phase continuity brief — handoff between sessions

Why

One Claude session = one context in memory. Next session = blank. Without a brief, the next agent spends 20 minutes searching for "where did we leave off". With the brief, it starts in 2 minutes.

When to trigger

Before the session ends, when:

• A phase has been closed (DoD met) → create brief for Phase N+1
• Session is ending mid-phase → update the existing Phase N brief
• Strategy / order / credentials changed → brief must reflect that

Location

docs/session-briefs/next-session-phase{N}-brief.md

Commit to the repo (on the working feature/* branch, not main). Only files with credentials stay gitignored — the brief shows paths to creds, not the values themselves.

Structure (template)

See examples/next-session-phase1-brief.md.example in the bundle — ready template with sections:

1. Reading order
2. Where we are (TL;DR)
3. Key insights / gotchas
4. First task — Phase {N} start
5. Phase {N+1..N+3} rough refs
6. Infra quick-check
7. Harness (brief reminder)
8. After closing the phase
9. Sources of truth

Anti-patterns

• "General brief" — "we'll work on phase 2" without file maps, without DoD, without quick-check. Useless.
• Copy-paste of old brief — not refreshed, misleading. Better none than outdated.
• Brief in the user's memory — "I'll tell you on start what's next". The next session can't see the previous conversation.

What to do if the brief is outdated

A new session will find a mismatch (e.g. commit sha in brief ≠ git log). Before doing anything:

1. git log -10 --oneline + git status
2. Update the brief first (commit "chore: update phase brief")
3. Only then start the work

The brief is a contract between sessions. Treat it like a production document.