escapeboy/ai-prompts/continuity

Continuity — resume → work → finalize

The bottleneck between coding sessions is not memory volume, it is the lost operational thread: what is mid-flight, what already failed, what to do next. Big context, vector recall, and chat history all "remember more" yet still miss the one fact that matters (this command already failed). This skill keeps that thread in a small repo-local artifact and runs a lifecycle over it.

Core loop: resume (bounded start surface) → work → finalize (leave evidence). Without the lifecycle, memory is passive archaeology. With it, memory becomes execution.

When to Use This Skill (and When NOT to)

Start simple. Reach for this skill only when the work spans more than one session on the same repo. Do NOT create a .continuity/ for throwaway or single-shot tasks — that is the sixth-memory-store trap this skill is explicitly built to avoid.

The artifact

Repo-local .continuity/ (scaffold with the script below):

• .continuity/STATE.md — the bounded resume surface AND the finalize target

(one living, compacted doc — not an append-only journal). Portable → committable/shareable.

• .continuity/local/ — gitignored, machine-specific operational scratch. Local-only.

Every fact carries an evidence tag (weight, not decoration): [observed] [validated] [user] — trust · [claimed] [contradicted] [unknown] — low trust. Full section spec, tag semantics, and a worked example: `references/format.md`.

Actions

resume (session start)

1. If .continuity/STATE.md is absent → offer init (don't force it; see "When NOT to").
2. Read STATE.md. Emit a compact surface (≤ ~12 lines): Now · Next action ·

top Known-failures · Validation expectations · Entry points.

1. Surface uncertainty: flag [claimed]/[unknown]/[contradicted] items as low-trust,

and warn if _Last finalized: is stale (> ~14 days) — verify before trusting.

1. Then start work from the Next action.

finalize (session end)

Synthesize the session INTO STATE.md (compact, don't append endlessly):

• Now ← current mid-flight state · Next action ← the single next step
• Decisions / Known failures / Validation expectations / Entry points / Unresolved risks

— update in place, each bullet evidence-tagged. Demote anything later work contradicted to [contradicted]; delete what's resolved and no longer load-bearing.

• Update the _Last finalized: line (date + short session tag).
• Then lint (below). Keep STATE.md bounded — if it grows past ~1 screen, compact it.

init / lint (via the script)

python3 ~/.claude/skills/continuity/scripts/continuity.py init <repo>   # scaffold .continuity/
python3 ~/.claude/skills/continuity/scripts/continuity.py lint <repo>   # validate structure + tags

lint checks required sections, valid evidence tags, and the provenance line. Run it after finalize; treat a non-zero exit as "the surface is malformed — fix before ending the session".

Relationship to existing memory (complement, not replace)

• Serena — stable architecture/conventions of a project. Continuity ≠ this; it's the live thread.
• Svod — durable, versioned, cross-session policies/facts with provenance. Promote a continuity

fact that outlives the task INTO Svod; leave transient operational state in .continuity/.

• codebase-memory-mcp — structural repo map (use it to fill Entry points). Usage: `codebase-memory`.
• auto-memory / MEMORY.md — ephemeral session facts. Continuity is the bounded, evidence-weighted

operational subset, co-located with the code and diffable.

Boundaries

Always

• Keep STATE.md bounded and evidence-tagged; make uncertainty visible.
• Prefer updating the existing surface over spawning a parallel one.
• lint after finalize.

Ask first

• Committing .continuity/STATE.md to a shared/team repo (it becomes visible in diffs & to teammates).
• Writing anything sensitive (tokens, internal URLs, credentials) — those never go in the portable STATE.md;

local-only scratch goes under .continuity/local/.

Never

• Turn this into a general knowledge dump — it is the operational thread only.
• Create .continuity/ for single-session/throwaway work.
• Trust a [claimed]/[unknown] item or a stale surface without re-verifying.