Seamkeeper

Seamkeeper

Maintain continuity of design intent across coding sessions and across rotating AI models, so a codebase reads as a single authored work rather than an anthology of fragments by different hands. Operationally: while authoring, don't create seams; while auditing, patch existing seams honestly.

Why this exists

Reasoning is ephemeral; code persists. Each session — and each model that takes a turn — inherits only the artifact, never the prior author's reasoning, and reconstructs intent from the code alone. It reconstructs it subtly wrong, and the wrongness deposits as seams: a shift in idiom at a boundary, a cluster of "just in case" defensiveness where one author didn't trust or understand another's code, the same concept solved two ways because the second author never saw the first solve it, and the dangerous one — a latent fault-line where an implicit contract (an assumption that lived only in a now-gone reasoning trace) is silently relied upon. That last kind reads as clean code, compiles, passes the happy path, and fails on the edge case nobody had budget to think through. It is a fault line, not a smell; there is nothing to point at.

A human coder is valuable after the fact because they persist — you can call them back from another team and the "why" is still alive in their head, so the code gets consulted rather than ripped out. A rotating cast of amnesiac sessions has no one to call back; the "why" did not leave with anyone, it simply stopped existing. So the entire job of this skill is one move: make the repository itself the advisor. Put the irreducible "why" where the next reader — human or any model — can reach it, so they recover intent instead of guessing, and so a codebase that goes wrong can be consulted for the clue instead of only removed.

Governing principle: in-band first, the ledger is residue-only

This is what keeps the discipline cheap and elegant instead of bloated — and it is the part most easily gotten wrong.

Carry continuity in the bones wherever possible: types, names, structure. Bone-borne continuity is nearly free, because those lines were getting written anyway, and it is precisely what makes the code read as a unified work. The ledger — out-of-band prose — is the only part that costs extra tokens, so it is the last resort, and it holds only the non-recoverable residue: what the code structurally cannot say about itself.

Apply one test to every candidate ledger line — recoverability:

Could a future reader reconstruct this from the code in less effort than reading the note?

If yes, the note is waste — cut it. Narrating what the code already says is the "anthology of short stories" smell, and an over-grown ledger becomes the fragmentation it was built to prevent. Record only residue:

• a discarded approach and why it was discarded,
• an assumption the code relies on that lives in no type or signature,
• the reason a non-obvious choice was non-obvious,
• what is deliberately unfinished and what would finish it.

When the elegant move and the cheap move turn out to be the same move, you are on the right track. The discipline is not "write more down." It is: write down only the part of the mind the artifact can't hold, and trust the artifact with the rest.

Two modes

Pick the mode that matches the task. They share the principle above and differ only in which behaviors they emphasize.

• Authoring mode — you are producing or extending code. Goal: don't create seams.
• Audit mode — you are sweeping existing code. Goal: patch existing seams honestly, without fabricating what's gone.

---

Authoring mode — don't create seams

1. Surface contracts in-band. When code relies on an unstated precondition, push it into the type or signature, where it cannot evaporate when your reasoning does. This converts the dangerous invisible class of seam (a silent assumption) into the loud visible class (a compile error for the next author who gets it wrong). In Rust this is most of the battle — a newtype or a type-state turns "this input is already normalized" into something the compiler enforces. Only when the type system genuinely cannot hold the contract, fall back to a greppable // CONTRACT: comment. See references/ledger-format.md.

2. Append residue as you go — don't save it for the end. Journal incrementally rather than summarizing at session close, so a crash or a kernel reset costs you the last thought instead of the whole session's reasoning. Run the recoverability test on every entry before you write it. Entry format in references/ledger-format.md.

3. Leave honest fragments, not bare TODOs. A run that cannot finish a thing marks the loose end richly: what's done, what assumption it rests on, what finishing requires, and why it stopped — so the next author inherits a fragment that knows it is a fragment. Never encapsulate an unfinished core behind a wrapper that makes it look finished; the honest TODO advertises itself, the wrapped-over loose end lies and becomes load-bearing before anyone notices. Fragment-marker convention in references/ledger-format.md.

4. Re-read before building over inherited code. Before changing code you did not write this session, reconstruct its intent from the ledger and the surfaced contracts — not from the bare source. Where the ledger does not explain something, flag the gap rather than guess. A cold-read guess, stitched in confidently, is exactly how seams form: you are finishing someone else's thought in a mood you don't have.

5. Redefine "done." Not "it compiles and works now," but "the next reader can recover the why." The exit condition of a session is that the advisor has been left behind. This is the single thing a session cannot supply for itself by accident — it has to be done on purpose.

---

Audit mode — patch existing seams honestly

This mode is the most valuable and the most abusable. State the contract with yourself before you start.

You cannot recover what was never in the artifact. The dangerous seams are dangerous because the "why" died with the reasoning that produced them — it is not in the code, and no amount of model capability reads what isn't there. A more powerful auditor recovers more of the recoverable and exactly zero of the truly gone — and is more able to fabricate the missing "why" convincingly, which is more dangerous, not less, because a fluent wrong advisor-note gets believed. Restraint matters more here, in proportion to capability.

The contract: close what's recoverable, harden what's merely analyzable, mark what's gone, fabricate nothing. In ascending order of honesty and value:

1. Unify recoverable seams. Where intent is derivable from the code even though it's scattered — a duplicated helper, two idioms for one job, three names for one concept — collapse them into one. This is legitimate cleanup and the real source of the "reads as one work" effect.

2. Surface latent contracts even when the "why" is gone. You cannot recover why a function assumes normalized input, but you can detect by analysis that it does — that is a property of the artifact, fully recoverable — and lift it into a type or a checked assertion. This converts a silent fault-line into a loud, enforced one without claiming any lost intent. It is the highest-leverage honest move available in an audit: it heals the dangerous property of the seam (silent breakability) while honestly leaving the narrative property (why it's shaped this way) unrestored.

3. Mark the unrecoverable precisely — do not reconstruct it. Where the intent is genuinely gone, record the gap, not a guess: trail goes cold here, entered by an unattributed author, what the code does (analyzable) versus why unknown, and the latent risk. This localizes the unanswerable so the next reader investigates the right spot instead of discovering the hole mid-debugging. Never write an inferred "why" as if it were recovered fact. That single move — laundering a reconstruction as a recovery — is what makes an audit worse than no audit. Gap-mark format in references/ledger-format.md.

Closing all seams by smoothing them into plausible unity produces a codebase that reads unified but lies — surface coherence bought with fiction, which is worse than the visible anthology, because the anthology at least advertises where to be careful.

---

Formats

See references/ledger-format.md for the concrete ledger entry format, the gap-mark format, the fragment-marker convention, and contract-surfacing patterns (with Rust examples). Keep every one of them minimal — omit any field that the recoverability test would delete. The formats are a floor for honesty, not a quota to fill.

Adapting this outside Claude (the discipline is model-agnostic)

The whole point is that continuity lives in the repository — the shared substrate every author reads and writes — so this is not Claude-specific. It is built precisely because the author rotates across models, budgets, and crashes; a single-model continuity mechanism would shatter the first time a different model takes a turn. Only the SKILL.md auto-loading is Anthropic-harness-specific. The content re-homes unchanged to an always-loaded convention file (CLAUDE.md, AGENTS.md, a rules file) or a system-prompt block on any other agent. When delivered that way, the only thing lost is automatic triggering; the discipline is identical, and a non-participating author who never receives it is handled gracefully by the gap-marking step above.

A note on this file

This SKILL.md tries to practice what it preaches: every line is meant to be load-bearing residue, and nothing here narrates what the examples already show. If you extend it, run the recoverability test on your own additions first.