SeamStressDev Session Continuity
What this is
Seam bugs are coherence failures between parts written at different times. AI assisted development manufactures exactly that condition: many short sessions, each fast, each locally correct, none holding the whole. The code accumulates; the understanding resets every session. This protocol is the small ritual that carries understanding across the gap.
Trigger
- Session start in a scaffolded repo, before the first change
- Session end, or any point where the work stops and context will be lost
- Resuming a task another session began
Required behavior
On start, orient before acting:
1. Read the seam map (.seamstress/seam-map.md). Know where the dangerous ground is
before walking on it.
2. Read the continuity note (.seamstress/session-notes.md) if it exists: what the
last session changed near seams, what was left open, what was overridden and why.
3. Verify the ground, do not assume it. git log --oneline since the note was
written; git status for uncommitted work. The note is a hypothesis about the repo; the
repo is the fact. If they disagree, say so before doing anything.
On end, leave the note you would want to find:
4. Write the continuity note: which seam files changed and why, in one line each; what is verified green versus expected but unverified (the labels from the verification protocol carry over); anything left half done, named honestly as half done; any protocol overrides and their stated reasons, recorded as expired history, never as standing permission. Two things are mandatory regardless of length: every override that occurred, and every unresolved risk. Brevity budgets apply to everything else.
5. Keep it short. The note is a torch handoff, not a diary. Ten lines beats a page, because a page does not get read at the start of a hurried session, and an unread note protects no one. Short never means silent: the mandatory items in step 4 appear even if they are the whole note.
6. Tend the map. If this session touched code that meets the seam criteria (moves
money, decides authorization, crosses tenant or user data boundaries, deletes) and that
code is not in .seamstress/seam-map.md, add it, with a one line reason, and say so in
the continuity note. A stale map is a map with a hole exactly where the newest code is,
and the newest code is where the seams are.
Override
The human can skip the closing note ("just stop here"). The opening orientation has no useful override: acting on a seam bearing repo without reading its map costs thirty seconds to skip and has no benefit. If the human insists, comply and note it.
Why this exists
The pattern this targets has a name in the engine's research: session churn. Files edited across many separate AI assisted sessions concentrate seam bugs, because each session writes code that is coherent with what it read, and no session reads everything. The double charge in catalog case 3 was two files, each fine, written apart. Continuity notes do not make sessions share a brain; they make each session start where the last one actually stopped, instead of where it plausibly stopped.
What this protocol cannot do
It cannot summarize what a session did not understand. A note written by a session that missed the seam bug will hand the next session the same miss, with added confidence. The note transfers attention, not correctness; the verification protocol is what keeps the contents honest, and the map is what keeps attention pointed at the right files.