snapshot

name	snapshot
description	Checkpoint a body of work: a reviewer subagent actively VERIFIES the work read-only (runs gates to confirm 'done' claims), checks it's ON-DIRECTION with the ticket's intent, and finds LEFTOVERS. Then, on your confirm, the orchestrator COMMITS the work scoped (only the reviewed files, gated on green) and posts a substantive status update to the ticket: a thorough comment, a status transition, and (only on material drift) an evergreen description rewrite with append-only Change history — and, on a closing snapshot (Done transition or session wrap-up), attaches the session debrief as the ticket's permanent record. Commit + comment + status + description all land under one batch confirm; nothing auto-posts. A building block: it verifies + commits the checkpoint + reports, never fixes code or files followups. Triggers: "snapshot this", "checkpoint the work", "commit and update the ticket", "snapshot progress", "post a ticket update", "update the ticket", "status update", "report progress to the ticket", "update ticket status/description".
version	1
tier	lightweight
args	[<work to snapshot / scope>] [-- <target ticket key, e.g. <PREFIX>-NNNN>]

Checkpoint a body of work. A reviewer subagent actively verifies the work read-only (running relevant gates to prove that what is claimed "done" is actually done), checks that it follows the ticket's direction, and catalogs leftovers. Once you confirm, the orchestrator commits the reviewed work (scoped, gated on green) and posts a status update to the ticket. This update includes a thorough comment, a proposed status transition, and—only when the premise has materially drifted—an evergreen description edit; on a closing snapshot it also attaches the session debrief as the ticket's permanent record. It is a menu, not a monolith: the batch confirm lets you decline any action — a commit-only checkpoint, a comment-only update, or the full commit + comment + status + description are all valid; you pick what lands at the confirm. Sessionless and lightweight: it runs within the active session—review → propose → one confirm → commit + post, then stop.

This is not /scrutinize: it does not hunt for code bugs or fix anything. Its job is to follow the direction, verify the claims, find the leftovers, and then stamp a checkpoint. It commits the reviewed slice and reports it outward to the ticket so a later human or reviewer-agent can trust the status without re-deriving it. It consumes the artifacts of /build and /scrutinize (_BUILD.md, _CRITIQUE.md, _FIX.md) to understand what happened. Multiple /snapshot checkpoints eventually roll up into a single /pr (which operates at the branch level, not the chunk level). As a building block, it verifies, commits, reports, and updates; it never repairs code or files followups (leftovers are merely guidance in the comment).

Related — /summarize: The §2 reviewer drafts its own comment body, but that "distill this work into a status" logic is exactly what /summarize does read-only. When a rich inward digest already exists (or you want one), /snapshot MAY generate its comment via /summarize and post that. /summarize is the report engine; /snapshot adds the verify + commit + outward post. This is optional wiring; the default self-contained draft path still stands.

Tracker note: This project uses Linear via the linear-server MCP — the tracker + its tools are constant; only the issue-key prefix and team vary per project and come from CLAUDE.md § Tracker (resolve them in §1, inject into the subagent prompt; keys are <PREFIX>-NNNN — FIN for finch). Tools: get_issue (read the ticket's intent/description/state/team/canonical branch), list_issue_statuses (resolve a target state), save_comment (post the comment), save_issue (move state and/or replace the description). Load schemas on demand (ToolSearch linear). No Linear MCP → The commit still happens (it needs no MCP), but the ticket half degrades. The direction reference falls back to args/conversation (state explicitly that On-direction is lower-confidence), the description proposal is SUPPRESSED (Part 3 → "skipped — cannot read current body to preserve history"), and only the comment + a suggested status are handed to the user to paste manually. Note that posting was skipped.

/snapshot Protocol

1. Scope & target ticket

Establish two things: the work under review and the ticket it reports to.

• Resolve the tracker config (do this first): Read CLAUDE.md's ## Tracker block (the orchestrator sees CLAUDE.md; the reviewer subagent does NOT — resolve here, inject in §2). Resolve the issue-key prefix (<PREFIX> uppercase for keys <PREFIX>-NNNN / its lowercase for branches <prefix>-NNNN-…) and the team. Finch: prefix FIN, team Finchclaims. Fallback — no ## Tracker block (unconfigured): keep today's behavior — detect a FIN-style key (uppercase-alpha prefix + -NNNN) from the slug/branch/conversation at lower confidence. The config is never a hard requirement; absent it, degrade to detection, don't error.
• Work under review: Resolve from args, else the active session (log / plan / build reports / critiques / IMPLEMENTATION_LOG), else the working-tree diff, else the conversation. This is what the checkpoint is about—and it defines the exact file set that gets committed (§3).
• Target ticket: The <PREFIX>-NNNN key (prefix from § Tracker) from the session slug (finch example, prefix=FIN: 2026_07_02_FIN_2737_… → FIN-2737), the git branch (lowercase prefix: <prefix>-2712-… → <PREFIX>-2712), or the conversation (text after -- overrides). get_issue it now to read its title, description (the intent/premise + any acceptance criteria), current state, team, and canonical branch name. This is the direction reference the review checks against, and its snapshot is the base for the description read-before-write (§3). If detection is low-confidence (e.g., branch-key ≠ slug-key) or ambiguous, confirm the ticket via one AskUserQuestion before reviewing.
• Wrong-ticket cross-check: Compare get_issue's returned canonical branch name against the actual current git branch (git branch --show-current). On mismatch, surface the wrong-ticket mismatch prominently in the §3 confirm header even if no slug/branch-key conflict was flagged. A reused-branch key can silently point at the wrong issue. (The canonical branch name is also what §3 step [1] uses to branch off dev/main.)

Resolve the trail: <trailDir> = <sessionDir>/builds/. Pick a <slug> once (kebab-case of the work). Before minting a fresh slug, ls <trailDir>—if an existing <slug>_*.md clearly matches this work (same chunk / ticket / topic), REUSE that slug so the trail clusters under one name. Only mint a new one for genuinely new work. Ledger/log appends (§3) use engine log.

Echo back one line: Snapshotting <PREFIX>-NNNN "<title>" (state: <current>, branch: <branch>) from <work>; trail: <trailDir>/<slug>_SNAPSHOT.md.

2. Review — spawn the reviewer subagent (active verify, read-only)

When to skip the subagent: If there is no target ticket (commit-only checkpoint) and no runnable gate for the work (e.g., docs / markdown / config with nothing to tsc/test/build), the reviewer is a near no-op. There's nothing to verify and no comment to draft. In that case, skip the spawn and do the commit scoping inline (identify the exact file set, classify CLEAN/MIXED via git diff -- <path>, propose the message), then go straight to §3. Otherwise, spawn the reviewer.

Backgroundable & parallelizable. This sub-agent dispatch is a composable building block: it can run in the background (run_in_background: true) so the orchestrator keeps working while it runs, and when the work splits into independent chunks, several such sub-agents can be fanned out in parallel and reconciled.

Before dispatching — §CMD_LOG_SKILL_INVOCATION: log this dispatch to the session log (why + context-pack pointer + one-line re-tread) so a restarted session can re-tread it. Fire it as the last step before the Task/Agent handoff.

Spawn one subagent (a general-purpose/analyzer) to review the work, verify it, identify the exact commit file set, and draft the update. It does the verification + framing; it never touches the tree. You (the orchestrator) keep the thread and perform the commit + posts in §3. Build its prompt self-contained:

You are drafting a historical CHECKPOINT for a ticket. Write it for a future engineer debugging a production outage caused by THIS exact code six months from now. Be dense, precise, and brutally honest about fragility. A tautological "aligned with intent, realizes the ticket as written" line is worthless padding. You VERIFY, FOLLOW THE DIRECTION, and FIND LEFTOVERS. You do NOT hunt for code bugs (that's a different skill) and you do NOT fix anything.

• Tracker config (resolved from CLAUDE.md § Tracker — the orchestrator fills these; you cannot read CLAUDE.md): Linear (linear-server MCP) · issue-key prefix <PREFIX> (keys <PREFIX>-NNNN, branches <prefix>-NNNN) · team <team>. Use this prefix for the ticket key and in the commit message; do NOT assume FIN.
• Target ticket (the direction reference): <PREFIX>-NNNN — intent/premise: <from get_issue description>; acceptance: <if stated>; current state: <state>.
• Work under review: <scope + concrete pointers: session artifacts / git diff cmd / build+critique reports / conversation digest>.
• READ THE FULL ARTIFACT TRAIL FIRST — not just the diff, but SCOPED to this work's <slug>. Before judging, read the COMPLETE trail for THIS work. It carries the decisions, critiques, verdicts, and rationale a diff can't show, and grounds the On-direction / Verified / Leftovers / Decisions&rationale / Risks review in everything that happened:
  • In <trailDir> (<sessionDir>/builds/) read THIS work's <slug>_*.md — its _BUILD.md, _CONTEXT_PACK.md, _CRITIQUE.md, _FIX.md, _EXPERIMENT.md, _TICKETS.md — PLUS the session artifacts (*_LOG.md, the plan, DIALOGUE.md) and LESSONS.md. A <slug>_TICKETS.md (written by /ticket) means a leftover was already captured as a filed followup — don't re-list it under Leftovers. In a long session, builds/ holds many unrelated slugs; only SKIM other-slug artifacts if directly relevant — never read the whole dir indiscriminately.
  • Full context IN → a tight distilled status OUT (the comment stays tight, TL;DR on top — the trail makes the status far richer than the diff alone; it does not bloat the comment).

Background is available (run_in_background: true) and relaying the summary when it lands still applies — but this step commonly runs foreground, since §3's confirm needs the reviewer's draft in hand right after. Run foreground when you need the result inline for the next step.

3. Calibrate, commit & post (single batch confirm)

HARD RULE — NO GIT GYMNASTICS (top-line safety constraint). The orchestrator NEVER stashes, git checkout/git restores, reverts, or temporarily removes ANY change (its own or a parallel agent's) to "clean up" a commit with intent to restore it later. That unroll-then-restore dance is HIGH-RISK and can silently lose a parallel agent's uncommitted work. It NEVER git add -p / patch-stages / surgically splits hunks. The only working-tree/index operation it may perform is git add -- <clean path>. If the reviewed work cannot be committed by whole-file staging of CLEAN files alone, the orchestrator SURFACES the situation and lets the USER decide — it does not manipulate the tree or index to force a clean commit.

1. Relay the draft: the proposed commit (message + file list with each file's CLEAN/MIXED classification + branch), the TL;DR, the proposed state change, and whether a description edit is proposed. Render the comment body in chat (or a tight digest + the trail link if very long).
2. Batch confirm (AskUserQuestion, MANDATORY — this both mutates the tree and posts outward). The header renders the ticket title + current state — and, on a §1 wrong-ticket cross-check mismatch, a prominent wrong-ticket warning (not just the number): "Post to <PREFIX>-NNNN '' (In Progress)?". Present ALL proposed actions together, up to four. Each is BEST-EFFORT and independent (step 3):
   • [1] Commit — the proposed message + the staged file set (each file shown CLEAN = will stage, or MIXED = also carries churn outside the work) + the target branch. The commit action offers, regardless of gate color: commit as proposed / edit message / edit the staged file set / skip the commit (post update only).
     • MIXED files are never auto-split, stashed, or unrolled. Per mixed file, the user chooses: commit the whole file as-is (churn included — explicitly flagged here) / skip that file (checkpoint only the clean files) / defer the whole commit. Default suggestion: skip the mixed file, commit the clean ones — the user can override.
     • Green gate: If the §2 verify gates were red or unrun, the confirm SAYS SO. "Skip the commit (post update only)" is a first-class choice at any gate color; committing red work is an explicit opt-in.
   • [2] Comment — the rendered body, plus any ready evidence to attach (screenshots/artifacts the agent already has in hand — see step 3 [2b]; "none" if there are none), and — on a closing snapshot (Done transition or session wrap-up) — + session debrief attached (see step 3 [2c]; shown as "no debrief yet — skipped" when none exists).
   • [3] Status move — <current> → <suggested>, or "none".
   • [4] Description edit — the single full body incl. ## Change history, or "no drift". → Post all / Edit one first / Cancel. On "Edit one first", ask which (commit / comment / status / description), loop to it, and re-present the confirm.

Constraints

• HARD RULE — no git gymnastics. The orchestrator NEVER stashes, git checkout/restores, reverts, patch-stages (git add -p), or temporarily removes any change to force a clean commit. That unroll-then-restore dance can silently lose a parallel agent's uncommitted work. The ONLY working-tree/index op is git add -- <clean path>. If the clean files alone can't form the commit, SURFACE it and let the USER decide; never manipulate the tree/index to force it.
• Not /scrutinize. It verifies the direction, the claims, and the leftovers — it does not hunt for code bugs or fix anything. A bug it happens to notice is a leftover/risk line in the comment, not a repair.
• Verify, don't assert. "Done" claims are confirmed by RUNNING the gates and cross-checking the diff — never taken on faith. A gate that couldn't run (or is destructive) is stated as such, not reported green.
• Read-only verify subagent. The reviewer runs only non-mutating gates and NEVER touches the working tree (no git add/commit/stash; no db:reset/migrate/seed; no e2e/live-service suites). The commit is strictly an orchestrator action after the confirm.
• Scoped commit, clean vs mixed, gated on green. Stage ONLY the CLEAN reviewed files with git add -- <path> — never git add -u/-A/.. MIXED files (carrying churn outside the work) are SURFACED to the user per file (commit whole as-is / skip / defer), never auto-split. Before committing, review git diff --cached so the user approves actual staged content, and re-check the narrowest gate (TOCTOU). Branch-first on dev/main using the canonical branch name (abort the commit if that fails). Message type(scope): <PREFIX>-NNNN … + the Co-Authored-By trailer. Only checkpoint green work by default; "skip the commit (post update only)" is always a first-class choice. No push unless asked.
• Notify siblings after a ticket update. Once the ticket-facing actions land, fire engine ticket notify <PREFIX>-NNNN "<decision-grade note>" so other local sessions subscribed to the ticket wake — a local dirty-flag, not an outward post, so it needs no confirm and is best-effort. This operationalizes §"Notify when you post a ticket comment" at the exact operative step: the general directive states the rule; a linear skill run reads its numbered steps and would otherwise skip a free-standing directive, so the notify is embedded here where the miss happened. Skip when running solo (no siblings) or when nothing landed.