/resume — read-only context loader

/resume rehydrates a session that lands in an in-flight worktree with no memory of how the work got there (REQ-F2.1, D-30). It gathers the durable context a worker needs — the kickoff brief, tasks.md state, the branch's git log, the PR state, and an optional handover brief — surfaces the working tree's uncommitted state, and asks before any work continues.

It is strictly read-only. It surfaces information and defers every decision to the human: it never auto-stashes, auto-commits, or auto-cleans (D-30), and as a read-only loader it never pushes or merges (REQ-F2.1). The point is to make the situation legible, not to act on it.

This is a read-only, non-dispatching path. Outside a git repository there is nothing to resume, so it stops with a clear message (Step 1); every other missing prerequisite (no remote, gh absent, a brief that is not there yet) degrades with a clear note and a still-useful partial load rather than a hard halt. Both arms are graceful per REQ-K1.7: a clear message, never an opaque failure.

Doctrine

This skill is procedure, not doctrine. Two rule docs inform it; resolve each via the rule-doc resolution convention (scripts/resolve-rule-doc.sh <doc-name> under the resolved planwright root, or the documented PLANWRIGHT_ROOT / CLAUDE_PLUGIN_ROOT chain):

• spec-format — the two-brief model (kickoff = durable contract, handover = optional in-worktree cache), the kickoff-brief structure, and the planwright/<spec>/task-<id-or-ids> branch convention this skill parses to locate the spec.
• interaction-style — the three disciplines and the turn/artifact arbitration, which govern the one attended turn this skill has: Step 8's.

Because /resume is a read-only loader, a doc that does not resolve is a one-line degradation note, not a halt: fall back to reading the brief and tasks.md directly and proceed (REQ-K1.7).

Doctrine manifest (machine-parseable, per doctrine/instruction-hygiene.md; run-start loads before work begins, point-of-use at the named step):

Doctrine: run-start spec-format Doctrine: point-of-use interaction-style (Step 8's turn)

Procedure

1. Establish location and prerequisites

Confirm the current directory is inside a git repository and resolve its top level. If it is not a git repo, say so plainly and stop — there is no in-flight worktree to resume. Note (do not fail on) the absence of a remote or of the gh CLI; those only narrow the PR-state step below.

With the tower argument, Step 1 is followed by Tower mode below in place of Steps 2-8.

2. Identify the in-flight unit

Read the current branch name and parse it against the convention planwright/<spec>/task-<id-or-ids>. Before interpolating the parsed <spec> into any path, validate it against the REQ-A1.8 spec-identifier charset (^[a-z0-9][a-z0-9-]*$, max 64 chars) and refuse the reserved word flight; no skill interpolates a failing identifier into a path or command (REQ-A1.8), so a segment that fails is treated as no match. The <spec> segment names the spec bundle (<root>/<spec>/, <root> being the spec root's primary view that scripts/resolve-root.sh spec --primary prints); the <id-or-ids> segment names the task or bundle being executed. A flight branch planwright/flight/<flight-id> is specless: say so and resolve no spec. If the branch does not match the convention or <spec> fails validation (e.g. a spec branch planwright/<spec>/spec, a hostile branch name, or an unrelated branch), do not guess a task: say which branch you are on and try to resolve <spec> only when it is unambiguous — a single spec bundle under <root> (a direct child whose name passes the REQ-A1.8 charset; the reserved underscore-prefixed directories _pending/, _observations/ and _flights/ are not bundles and are skipped), or a single bundle whose requirements.md carries the literal **Status:** Active marker and that has a kickoff brief (a format-version 2 or 3 bundle never stores Active — its header rests at Ready while work is in flight — so a stored **Status:** Ready with a kickoff brief counts the same way there, but only when the render reports work in flight: a freshly signed-off, undispatched v2 bundle is not an in-flight unit). Both arms consider only directory names that pass REQ-A1.8 (an Active bundle has already passed validation, so its name conforms). If that inference is unambiguous, continue with the resolved <spec>. If it is not — zero candidates (no spec root, or no bundle directory passes REQ-A1.8) or several candidates — say so plainly and proceed with no resolved <spec> (Steps 3-4 below degrade to a spec-less partial load, a clear message rather than an opaque failure per REQ-K1.7) rather than inventing a unit.

3. Load the kickoff brief (the contract)

If Step 2 resolved a <spec>, read <root>/<spec>/kickoff-brief.md — the durable contract downstream work executes against. Surface the signed-off goal restatement, the task-graph slice for the in-flight unit, and the risk-register entries that touch it (when unsure whether an entry is relevant, include it rather than omit it). If the brief is absent or has no final sign-off section, note that the work predates a signed brief (or the brief is partial) and continue with the rest of the load; do not stop. If no <spec> was resolved, note that and move on — Steps 5-8 still produce a useful spec-less partial load.

4. Load tasks.md state

If a <spec> was resolved, read <root>/<spec>/tasks.md, keying the read off the bundle's declared Format-version: (invariant-tasks D-7). In same-repo, a halt on the task branch sits in the worktree's own copy (scripts/resolve-root.sh spec, without --primary), so read that copy's ## Awaiting input too, at either version:

• Format-version 1: surface the in-flight unit's block — and when the branch encodes a cohesion bundle (task-<id-or-ids>, e.g. task-3-4), every task block the bundle covers, not just one — including each block's section (In progress / Awaiting input / etc.), its Status: and Last activity: annotations, Done when:, and Dependencies:, and note whether each dependency sits in Completed.
• Format-version 2: the committed file holds definitions plus human-authored payload only — no placement sections and no state annotations exist. Surface the unit's block (Done when:, Dependencies:) from ## Tasks, note any reference bullet naming the task in ## Awaiting input, ## Deferred, or ## Out of scope (a parked task), and read execution status — the unit's phase, each dependency's completion, the bundle's derived Active/Done — through the render, the canonical human-facing read surface (scripts/spec-status.sh <root>/<spec>; invariant-tasks D-6). In a separate-repo store (scripts/resolve-root.sh spec --posture), also note when that tasks.md is uncommitted in the holder: a halt note awaiting the operator's commit (custom-spec-location REQ-E1.9). A render failure degrades to reporting the definition and bullet state with a clear note.
• Format-version 3: the version 2 read, plus each task's repository: the render names the alias of every task whose block names one (a block without Repository: belongs to the bundle's work repository) and any repository-unresolved task with its alias and reason. Report that state as this machine's registry or field gap, never as progress or a stall.
• Missing or unparseable Format-version:: neither arm applies — surface it and report definitions and bullets as found, assuming neither version's semantics (D-7's fail-closed direction; this loader writes nothing regardless).

This is the canonical orchestration state record; report it as found, without editing it. With no resolved <spec>, skip this step.

5. Load the git log

Show the recent commits on this branch (most recent first), and the branch's relationship to its base (commits ahead / behind where that is observable). This is what reconstructs what the prior session actually did.

6. Load the PR state

If a remote and the gh CLI are available, read the PR for this branch (gh pr view on the current branch): its number, draft/ready state, title, and review/CI status. If gh is absent or unauthenticated, there is no remote, or the branch simply has no PR yet, record that no PR state is available and proceed with a partial load: everything except the PR state is still available (REQ-K1.6, REQ-K1.7). A branch with no PR is a normal pre-PR state, not an error.

7. Load the optional handover brief and polish audit

If <worktree>/.claude/handover.md exists, read it and fold its in-flight notes into the context Step 8 offers. It is an optional best-effort cache (D-3), not a contract: its absence is normal and never an error.

<worktree>/.claude/polish-audit.md is the same kind of cache, left by a standalone /polish run, and this skill is its named reader. If it exists, carry it into Step 8 the way /polish would have: each pending sign-off and each queued fork as one line among the question's options, the counts in the detail, the file as the pointer. Never replay the tables into the turn. Its absence is normal and never an error, exactly as for the brief above.

8. Surface the working tree and ask before proceeding

Run git status and surface the working tree exactly as it is: staged, unstaged, and untracked changes. Do not stash, commit, clean, or otherwise touch the working tree — the decision about uncommitted state belongs to the human (D-30).

Then, before doing any further work, ask the human how they want to proceed. Steps 3–7 gather; nothing they gather reaches the operator before this turn, which is a projection of the load (interaction-style, the arbitration), not the load itself:

• The question leads, with the decisions the load surfaced as its options — uncommitted changes to settle, a pending sign-off or open fork from the polish audit, a halt recorded against the unit — each option stating its own action and consequence, per the balance rules, with an explicit leave-it-for-now option.
• One compact status line follows: the unit, its derived phase, the PR number and draft state (or none, or unknown when Step 6 could not ask), the working tree as clean or a count of changed paths, and "partial load" when any step degraded.
• The context elements — unit, brief slice, task state, git log, PR state, handover notes, the polish audit's counts, working-tree status — are offered on request, one layer at a time, never emitted by default. A decision the operator must weigh is never hidden in that layer: it belongs in the question.

A follow-up the operator names in the answer gets its tracked form proposed per interaction-style's Capture at birth, but /resume stays read-only: the session continues with that write as its first act, once the operator confirms, and this skill never makes it. A proposal the operator declines is not tracked. Mirror the turn into the structured decision/transcript log as one turn record, sanitized like the log's other records (D-19); where the harness provides no such log, say the mirror was skipped, never improvising one into the repository.

When a <spec> was resolved, also recommend — as an optional independent step, one line — that the human may run /spec-walkthrough <spec> themselves for an unaided, plain-language re-read of the bundle to re-orient (REQ-F1.1, REQ-F1.2, D-11). It is a suggestion only, never a step this skill performs, and as a read-only loader /resume neither runs it nor depends on it. /resume ends here; continuing the work is a separate, human-initiated step.

Tower mode

/resume tower reconstructs what is in flight for the whole checkout, not one unit, outside a tower session (REQ-F1.4, D-9). It renders from the same sweep the tower's start reads, so the two surfaces cannot disagree.

Run scripts/flight-sweep.sh sweep --no-write, by its resolved literal absolute path under the planwright root, one plain command (doctrine/plugin-script-invocation.md). --no-write leaves the derived index untouched, keeping this mode read-only. Its usage header defines the rows and states.

• Exit 0 is the render. Lead with the flights that need the operator (awaiting the operator, dead, stranded, or unknown), each by flight id with its landing or worktree and the private park record its partial row names, then one status line: the count per state, "partial load" when any forge, registry, or queue row other than ok names a read not made (a forge skipped for no-flights or no-origin aside), and plugin-root skew when the root-skew row says yes.
• Any other exit is reported with its stderr as a partial load. Never reconstruct flights another way: one derivation is the point.

A flight to continue is a separate, human-initiated step, typically /resume inside that flight's worktree. Mirror the turn as Step 8 does.

Invariants

These hold at every step. The skill's one and only write is the REQ-B3.2 self-healing drift-log note (Maintenance section): recording one observation fragment through scripts/obs-record.sh and committing it as its own chore commit. That chore never touches the resumed work; every invariant below describes the read-only guarantee over that work. Step 8's turn record goes to a log the harness provides, outside the repository, so it touches neither.

• Never write the flight index or touch a flight in tower mode: it reads through --no-write only.
• Never modify the working tree of the resumed work: no stash, clean, checkout, reset, or commit of in-flight changes. /resume only reads it (REQ-F2.1); D-30 specifically forbids auto-resolving uncommitted state.
• Contract (doctrine/human-gates.md): never push, open or update a PR, or merge.
• Never edit tasks.md, the brief, or any spec bundle file. The observations fragment store under the spec root's _observations/ is the carved-out drift-log exception above, not a spec file. State moves belong to /orchestrate and /execute-task, not to a context loader.
• Never hard-fail opaquely on a missing prerequisite: outside a git repo, stop with a clear message (Step 1); for every other missing prerequisite, degrade with a clear note and load what is available (REQ-K1.7).

Maintenance

After each run, compare these instructions against the doctrine and spec they implement: REQ-F2.1 (the read-only loader contract), D-30 (surface, do not auto-resolve), REQ-A1.8 (the spec-identifier charset gate on <spec> before path use), and the spec-format doc's two-brief model, brief structure, and branch convention. If the brief structure, the handover-brief location, the identifier charset, or the branch convention have drifted from what this skill describes, record a one-line drift observation through the shared helper (scripts/obs-record.sh --slug skill-drift --scope <repo> --text 'skill-drift(resume): <what>' — the entry text keeps the skill-drift(...) prefix) and commit the fragment as its own chore commit, per REQ-B3.2 / D-42; surface a non-zero helper exit rather than silently dropping the observation. In repositories without specs/, surface the drift to the user instead of recording it. Do not edit this skill or the doctrine docs to resolve the drift; the accumulator's canonical reader (/spec-draft) owns folding drift into spec amendments.