LCN Wafer Inspection

Appearance

Session Continuity Runbook ​

How to start a new Claude Code session — on this machine or a different one — and pick up the roadmap work at the exact point the previous session left it.

This exists because the roadmap (Phase 0 → Phase 2) spans multiple weeks and almost certainly multiple sessions. Claude's local memory does not transfer between machines; the git repo does. Everything needed for continuity must therefore live in the repo.

Pair this runbook with:

  • CLAUDE.md (repo root) — auto-loaded at session start; holds the five-line "Current position" block
  • roadmap-progress.md — per-slice status and the running session log

1. Starting a new session ​

1.1 Preconditions on the machine ​

  • Repo cloned and checked out to the commit you want to resume from (usually master)
  • .NET 10 SDK installed
  • dotnet-counters installed globally (dotnet tool install -g dotnet-counters) — only needed if the next action involves a measurement capture
  • Claude Code installed and the working directory set to the repo root
  • (Optional) GitHub Copilot with Claude Sonnet available if the next action is a TASK-* implementation that already has a Copilot agent prompt

1.2 Kickoff prompt (copy-paste) ​

Paste this as the first message of a new session:

Read CLAUDE.md, then docs/reviews/roadmap-progress.md (the session log).
Tell me where we are in the roadmap and what the next action is, in under 10 lines.
Do not start work yet — wait for my confirmation.

Claude Code auto-loads CLAUDE.md, but the explicit read instruction forces the progress log to also be consumed before the summary, so the answer is grounded in both the summary and the detailed record.

1.3 After the summary ​

Three typical second messages, in order of increasing scope:

  • "continue with the next action" — when the next action is small and well-defined (for example, capturing the demo baseline row)
  • "open SLICE-N and write its spec and task files" — when starting a new slice per the roadmap
  • "I want to revisit decision X" — when earlier judgment needs to change; expect Claude to propose an edit to the relevant spec / ADR / roadmap section before implementing

Do not skip the summary step. Jumping straight to work without the orientation turn produces drift: Claude starts from priors instead of from the committed state.

2. Ending a session (the handoff protocol) ​

This is the mirror image of starting one. Whenever a session moves the plan forward:

  1. Update CLAUDE.md's "Current position" block — phase, last completed slice, next action, blockers, date. Keep to five lines.
  2. Append a session entry to docs/reviews/roadmap-progress.md under today's date, at the top of the session log. Keep to ~5 lines: what was done, commit hashes, measurement rows filled, decisions.
  3. Update the per-slice status table in the same file if any slice's status changed (Proposed → In Progress → Completed).
  4. Commit all doc edits alongside the code they describe. Progress notes that live only in an uncommitted working tree do not help the next session.

If a phase's exit gate is met, record it explicitly in the relevant phase section of the progress file rather than burying it in the session log.

3. Cross-machine specifics ​

Three things live outside the repo and do not travel:

ItemWhat to do on a new machine
Claude's local memoryNothing — it rebuilds itself as you work; project state lives in the repo
dotnet-counters installRun dotnet tool install -g dotnet-counters once
Copilot chat historyRe-paste the prompt block from the relevant TASK-*.md file into a fresh session

There is nothing else. If a future slice relies on a machine-local tool, the slice's task file must say so, and this table must grow.

4. Handling drift and stale state ​

4.1 CLAUDE.md says one thing, the code says another ​

Trust the code. Update CLAUDE.md before doing anything else, then write a session log entry noting the correction. Stale pointers in CLAUDE.md mislead every subsequent session until fixed.

4.2 Progress file says a slice is Completed but the work is missing ​

Check git log for the slice's acceptance-criteria artifacts (CI workflow file, meter class, etc.). If they are absent, the previous session closed the slice prematurely. Re-open the slice (status → In Progress) in the progress file, add a session log entry explaining the discovery, and fix the gap before continuing.

4.3 Two sessions in parallel on different machines ​

Don't. This is a single-threaded plan. The git repo is the lock; whoever commits first wins, and the second session has to rebase its progress-file edits onto the new state. The session-handoff protocol is designed for serial work only.

4.4 The last session's commit was force-pushed or rewritten ​

The session log can diverge from actual git history if someone rewrites commits. If commit hashes in the log do not resolve (git cat-file -e <sha> fails), write a session log entry noting the rewrite and move on. Do not rewrite the log — historical entries are evidence even when the commits they reference no longer exist.

5. Fresh-clone walkthrough ​

Concrete first-time steps on a machine that has never seen this repo:

git clone <repo-url>
cd lcn-wafer-inspection-desktop
dotnet tool install -g dotnet-counters   # only if next action is a measurement
dotnet restore
dotnet build --configuration Release
dotnet test --configuration Release      # confirm 216+ tests pass before editing

Then launch Claude Code in the repo root and paste the kickoff prompt from §1.2.

If dotnet test fails on a fresh clone, stop. Something is wrong with the machine setup (wrong SDK version, missing Windows feature, warnings-as-errors catching a new analyzer diagnostic). Fix that first — a session that starts against a red build cannot produce trustworthy work.

6. Related material ​

Docs-first project memory for AI-assisted implementation.

LCN Wafer Inspection Prototype