Multi Phase Session

Multi-Phase Session Management

Large software projects, long-term initiatives, or phased work—where each phase is a distinct milestone with clear acceptance criteria—benefit from a session-per-phase model instead of trying to compact context within a single conversation.

Why separate sessions per phase

AI context quality degrades measurably around 60% of capacity (before auto-compact), and subsequent compacts introduce truncation and lossy summarization. A project split across multiple compact cycles accumulates error.

Better pattern:

• One AI session per phase
• Each phase terminates with a commit, updated handoff, and session closure
• Next phase opens fresh with the handoff file and project docs as context source
• The codebase, specification documents, and handoff file are the canonical context—not the previous chat history

This preserves quality because:

• The next agent (or next session with the same agent) reads living docs, not truncated chat summaries
• Decisions, blocked items, and state are recorded in files meant for future readers, not buried in chat
• Each phase is independently validated before moving forward
• Context isn't split across a "what I remember from chat" and "what the files say"

Session lifecycle per phase

Phase completion checklist

Before closing a session:

1. Code is committed — all work merged to the appropriate branch or merged to main (per project CI rules)
2. Acceptance criteria are met — the phase has a defined "done" state; validate it
3. Handoff is written/updated — if the project uses session-handoff.md or equivalent, it reflects current state
4. Next phase is clear — the handoff names the next objective, expected duration, and any blockers
5. CHANGELOG or progress log is updated — significant milestones are recorded for future reference

Opening a new session for the next phase

1. Read the handoff first — open session-handoff.md or equivalent in full before proceeding
2. Check git state — git status, git branch, git log --oneline -5 to understand current state
3. Verify acceptance criteria from prior phase — confirm the last phase actually completed and is clean
4. Read critical docs — specification, architecture decisions (ADRs), any phase-specific README
5. Begin with verification — first steps validate the prior phase is stable before building the next one

Compact within a phase vs. across phases

• Compact within a phase (/compact) — acceptable if the work is continuous and there's no natural break. Preserve: current objective, open blockers, active trade-offs, current validation state, and concrete next steps. Drop: resolved discussions, abandoned approaches, large tool outputs.
• Compact across phases — anti-pattern. Don't force compact when a phase ends. Open a new session instead; the overhead of reading files is smaller than the risk of losing phase context to lossy summarization.

Handoff file format and live-doc discipline

A durable handoff file is the primary context for the next agent/session. It must be understandable in isolation.

Minimum required sections

• Phase just completed — name, what was built, what was validated, any trade-offs made
• Current git state — branch name, upstream (main/prod/staging), if dirty or clean, current commit hash of relevance
• Blockers or open decisions — anything that stopped progress or is waiting for a human choice
• Architecture / known constraints — what the next phase must know to avoid breakage
• Next phase — expected work, entry point (file/command to start with), and acceptance criteria
• Gotchas or pitfalls discovered — anti-patterns found, tools that didn't work, environmental surprises

Stale-doc defense in depth

When multiple versions of a document exist (e.g., v1, v2, v3 of a design spec, or multiple branches of a financial calculation), protect against a future agent opening the wrong one:

• Mark every superseded document with a banner at the top: [SUPERSEDED — use <current-filename>]

  • Apply this to all file types: .md, .csv, .json, data files, not just human-readable docs
  • The banner is a local defense; it doesn't depend on the handoff's index being read first

• Resolve contradictions in your source-of-truth — if the same matrix says a claim is "proven" in section 1 and "partial" in section 5, a future agent will follow the first occurrence and be misled. Fix the contradiction before closing.

• Validate the handoff with deterministic checks — use grep to confirm superseded banners are present, or ask a second agent to simulate opening just these docs: "Would a blind agent be misled?"

Branch naming in handoff

If work lives on a feature branch (not main), explicitly name it in the handoff:

Current branch: feature/phase-2-auth-overhaul (not merged to main yet)
Next step: open new session in this branch, or merge to main first

Never open Claude in a subdirectory

Always launch the AI agent from the root of the project repository, not from a feature directory, subdirectory, or subfolder.

Why: Global configuration files (.claude/, .codex/, .gemini/, or language-equivalent), shared rules, and context files live at the repository root. Opening in a subdirectory means:

• The agent doesn't load the root-level instructions or rules
• Multi-session coordination breaks (handoff files won't be found or will be in the wrong place)
• Environment context (project-specific setup, shared libraries, CI configuration) is inaccessible

When the next session starts: explicitly tell the next operator or agent the full repository path, e.g.:

cd /path/to/my-project-repo

Not:

cd /path/to/my-project-repo/apps/frontend  ← WRONG

Exception: Git worktrees (which share the parent repository's .git directory) maintain access to root-level configuration and can function correctly.

Example: 3-phase refactor

Phase 1 — Audit & Design

• Read the current codebase, write spec of changes needed
• Commit: docs/refactor-spec-v1.md, CHANGELOG entry
• Handoff mentions: "Spec ready, no blockers, Phase 2 begins here: implement core module transformation"

Phase 2 — Implementation

• Open new session, read handoff and spec
• Build refactored modules, tests, integration points
• Commit: feature branch refactor/core-modules
• Handoff: "Core modules done, integration tests green, Phase 3 is edge-case handling and migration of dependent code"

Phase 3 — Edge Cases & Cleanup

• Open new session, check Phase 2 is merged/stable
• Handle remaining dependent code, performance edge cases, documentation
• Commit: merge to main
• Handoff: "Refactor complete, all tests passing, code review done. Next work is feature X or maintenance"

Each session is fresh, each phase is independently validated, and context doesn't degrade because the agent reads files, not chat summaries.

When NOT to use multi-phase

• Trivial changes — a typo fix, a single-file edit, or a command-line one-liner does not need a handoff.
• Exploratory work — if the outcome is uncertain and there's no phase boundary, a single session is fine. Use compact if needed.
• Pair-programming — if the agent and operator are both present and active in the same session, compact is acceptable.

Use multi-phase when work is clearly phased, spans multiple days or sessions, or when you notice quality dropping as context fills.