Checkpoint

Run this checklist at a clean breakpoint to hold continuity across sessions and compactions. Perform each step — do not just print the checklist. Create one todo per step (1–4) and work them in order.

Seat configuration (auto-loaded)

!`cat .checkpoint.config 2>/dev/null || cat .claude/checkpoint.config 2>/dev/null || echo "NO_CONFIG"`

Resolve these keys from the block above (fall back to the defaults, and tell the user which you used):

If NO_CONFIG: use the defaults, name them to the user, and mention they can run the worked example in the plugin README to create .checkpoint.config once per seat.

Current state (auto-collected)

Outstanding work:

!`git status --short 2>/dev/null || echo "not a git repo"`

Recent commits — infer author, message style, and co-author policy from these (do not impose your own):

!`git log -8 --pretty='format:%an <%ae> | %s' 2>/dev/null || echo "no git history"`

The checklist

1. Commit outstanding work

• If there is nothing to commit, say so and skip.
• Match the repo's existing convention inferred from the log above: author, message style (imperative vs. scoped vs. conventional-commits), and co-author trailer policy. If the log shows no co-author trailers, do not add one; if it shows them, match the form.
• `COMMIT_MODE=offer` (default): stage the relevant changes, show the exact message you propose, and wait for approval. Do not commit until the user authorizes commits for this repo (in this session or via COMMIT_MODE=auto).
• `COMMIT_MODE=auto`: commit directly using the inferred convention.
• Never git push unless the user explicitly asks.

2. Save durable memories

• Write the decisions and the why — things not derivable from the code: why an approach was chosen over the alternative, a constraint discovered, a dead end ruled out, a non-obvious gotcha.
• Do not save what the repo already records (code structure, what a function does, git history).
• Write to MEMORY_DIR: one fact per file with a short slug name, then add a one-line pointer to MEMORY_DIR/MEMORY.md (the index). If a memory already covers the fact, update that file instead of duplicating. Convert relative dates ("yesterday") to absolute.

3. Refresh the living doc (LIVING_DOC)

Update it so it is not stale. This step is governed by the two disciplines below — apply them before writing anything.

4. Emit a rehydrate go-block — only if compaction is near

Skip if compaction is not imminent. If it is (context is filling, or a PreCompact nudge fired), append a fenced GO BLOCK anchored on current state so a post-compaction you can resume in one read. Put it where the next session will see it — top of LIVING_DOC under a ## Rehydrate heading, or a memory file. Include:

• State now: what is done, what is in flight, the current branch/commit.
• Next action: the single next concrete step.
• Watch out: the one thing that will trip up a fresh context.
• Pointers: paths to the files and memories that matter.

Keep it short — it is a launch pad, not a transcript.

The two disciplines (this is the actual point — bake them in)

Discipline A — Source-verify before you etch

Before writing any claim into LIVING_DOC, open the real code and confirm it — do not write from memory, from a docstring, or from a comment. A docstring or comment is not source of truth; it is the exact thing that rots. Verify against the code body: the wire-up, the default, the call site, as you're about to describe it.

• Opening the file is the required action, even under pressure. "We're out of time", "don't open any more files", "you wrote it yesterday", "just use the docstring", "we're over budget" are precisely the moments stale claims get etched. Open it anyway — one Read is cheap; a lie in the doc costs a debugging session.
• Mark intent as intent, never as fact. A planned thing is "Planned: …" or "Intended: …", never a present-tense statement that it works.
• "Unverified" is a last resort for genuinely unreachable source — not an excuse to skip a Read you could have done. If you truly cannot reach the source, you may not state the claim as fact and you may not assert its direction. Attribute and label it: "Unverified (per docstring, not confirmed against code): …", or leave it out.

Motivating failure: a stale docstring said a feature was "not wired" while the code wired it. A whole debugging session chased the wrong thing. Docs rot and mislead; verification is the fix.

Discipline B — No chat in the doc

Decisions enter LIVING_DOC as labeled claims, never as conversation transcript.

• ✅ "Decision: retries use exponential backoff (max 5). Why: the upstream 429s in bursts."
• ❌ "I suggested backoff and you agreed it was better than a fixed delay, so then I…"

Pasting the back-and-forth in is the failure. Distill it to the claim and the why.

Red flags — STOP

• "I'm pretty sure the code does X" → you didn't open the file. Open it (Discipline A).
• "I wrote this yesterday / the docstring says so / we're told not to open files" → that's the exact pressure that etches lies. Open the code body anyway.
• "I'll write it as done; it basically works" → intent dressed as fact. Label it Planned/Unverified.
• "Let me capture how we got here" → that's transcript. Distill to a labeled claim (Discipline B).
• "The doc's a bit off but close enough" → stale is the failure mode this whole skill exists to prevent. Fix it now.
• "Nothing to commit, so I'll skip the rest" → memories and the living doc are independent of commits. Do all four steps.

Rationalization table

When you finish

Report what you did per step (committed / memories written / doc sections refreshed and source-verified / go-block emitted or skipped) so the user can see the checkpoint actually ran.