Summarize Delivery

summarize-delivery — turn a workforce run into an accountability artifact

The skill is named summarize-delivery; it is the delivery-side closure leg that closes the devague method's eight-leg flow:

scope -> think -> challenge -> spec-to-plan -> assign-to-workforce ->
deviate -> validate-delivery -> summarize-delivery

It runs after the sibling /assign-to-workforce skill has executed (or attempted to execute) a converged plan — and after any /deviate records that run produced, since /deviate slots in between /assign-to-workforce and this skill, recording approved mid-run departures the moment they happen during the fan-out. Where /assign-to-workforce takes the plan to delivery, this skill summarizes that delivery: it separates what was planned from what was actually delivered, records the mid-work decisions and plan drift the execution produced — quoting /deviate's approved dN records as the recorded ground truth wherever they cover an item — states delivery claims with evidence and confidence, and names the remaining work.

The plan the user confirmed is a contract, not a fiction. Agents make mid-work decisions, hit constraints, cut scope, and produce delivery claims that were never in the plan. Until now the flow had no wrap-up leg to record any of it. This skill is that leg: the summary records where execution obeyed the contract, where it changed, and what is actually safe to claim as delivered.

It is not a polite progress report and not a restatement of the plan. It is an accountability artifact — auditable by a human who never watched the run.

The three readers

Write for exactly these three, and no one who was present for the execution:

1. The operator (main agent) closing a workforce run — assembling the ground truth of what merged, what failed, and what still needs doing.
2. The human owner at the final PR gate — who uses the artifact as the review map: every delivery claim traces to a plan task or an explicit drift entry, so the plan-versus-actual comparison is mechanical, not rhetorical.
3. Any later reader who needs to know what actually shipped without replaying the execution transcript. The artifact is committed and self-contained; nothing in it depends on unrecorded memory of the run.

Method-only — no script, no CLI verb

This is a method-only skill (v1), modelled on /scope at its birth: a SKILL.md with an output template and no entry-point script, no new CLI verb. The deterministic devague CLI surface is unchanged — Devague never spawns agents, marks tasks done, gates merges (/assign-to-workforce owns the TDD gate), or mutates delivery state. The CLI stays deterministic and non-orchestrating (issue #20); the summary is agent-side work. A future devague delivery engine — a third structural peer with a delivery store and a deterministic no-overclaim gate — is parked as follow-up, deferred until dogfooding the method shows machine state is needed.

Because there is no script, this skill invokes the read-only devague moves directly (if devague isn't on your PATH: uv tool install devague).

The method

1. Establish the planned-work baseline — verbatim, starting from the skeleton. Run devague summary [--plan <slug>] [--json] first. It renders the eight-section template pre-filled, verbatim, from the plan's tasks, the plan's live source frame, and the delivery (deviation) store — with <fill: ...> placeholders standing in for everything execution-dependent (run status, per-task delivery status, evidence, delivery claims). Continue filling in that skeleton rather than retyping it from scratch — fewer transcription errors, same verbatim-baseline rule. Fall back to hand-assembly when devague summary isn't available at all — the verb is missing (an older devague predates the command) or the underlying state it needs can't be read (no current plan, or a delivery record written by a newer devague) — by reconstructing the baseline read-only via `devague plan show [--json]` and `devague plan waves --json`, the same enriched payload /assign-to-workforce fans out, keyed by task id with each task's summary, instruction, acceptance_criteria, and covers. If no plan state exists at all, degrade further still (see "Degrading when there is no plan state"). Whichever path was taken, say so in the artifact's baseline: line — one of `devague summary skeleton`, `devague plan (hand-assembled)`, or `git+PR history (no plan state)`. Quote task ids and summaries verbatim into the Planned Work section either way — mirroring the verbatim-brief rule in /assign-to-workforce. Drift is then measured against the contract the user confirmed, never against a paraphrase.
2. Establish actual delivery. Reconcile the baseline against what merged: the merged branches, commits, and PRs of the run. Every plan task must be accounted for as delivered / partial / dropped / blocked, keyed by task id — 100 %, no silent omissions.
3. Record mid-work decisions. Every constraint discovered, scope cut, or choice made during execution that was not in the plan.
4. Classify drift against the plan. Any plan task whose delivery differs from its contract becomes a drift entry — exhaustive relative to the plan, never silently normalized. Each entry names the plan item it diverges from, the reason, and exactly one classification: acceptable / risky / needs-follow-up.
5. Gather evidence, read-only. You may run read-only verification — the test suite, the linters, git log — to substantiate a claim before you write it. Verification never mutates code or state. A claim you cannot verify stays unverified.
6. State delivery claims with confidence + evidence — grounded in the lapse ledger. Each claim carries a confidence level (high / medium / low / unverified) and at least one resolvable evidence pointer, or an explicit unverified marker. Read devague lapse --list first (or the Lapse ledger evidence: block devague summary's skeleton already renders under this section — see Method step 1): an approved lapse touching a claim — an unverified grader, a below-target sample size, an assumption standing in for a real measurement, or another of LAPSE_CODES (devague/frame.py) — caps that claim's confidence honestly instead of letting it default to high; a still-proposed lapse is pending, not yet evidence, and must not be cited as if it already were. A claim without evidence is unverified — never asserted as done.
7. Name the remaining work. What is incomplete, deferred, or newly discovered — including any failure and its cause.
8. Write the artifact and commit it. Fill the eight-section template into a committed, durable file at docs/deliveries/<created-date>-<slug>.md — the structural peer of docs/specs/ and docs/plans/. Reads of plan and frame state stay read-only; producing the artifact leaves .devague/ byte- identical.

The eight-section template

Fill this in verbatim — all eight sections, in this order. Every section stays writable for a partial or failed run; nothing here requires all waves merged, and there is no completion precondition (a run that merged zero waves is still a valid input).

# Delivery Summary — <plan title>

plan: `<slug>` · run: `<complete | partial | failed>` · date: `<created-date>`
baseline: `<devague summary skeleton | devague plan (hand-assembled) | git+PR history (no plan state)>`

## Intent

<One paragraph: what this run set out to deliver, and the plan it executed.>

## Planned Work

<The plan's tasks, quoted VERBATIM from the `devague summary` skeleton (or,
when hand-assembling, `devague plan waves --json`) — task id and summary,
never paraphrased. When no plan state exists, quote the git/PR baseline
instead and SAY SO here.>

- `t1` — <task summary, verbatim>
- `t2` — <task summary, verbatim>
- ...

## Actual Delivery

<Every plan task accounted for — 100 %, keyed by task id — as one of
delivered / partial / dropped / blocked.>

| Plan task | Status | What actually landed |
|-----------|--------|----------------------|
| `t1` | delivered | <what merged> |
| `t2` | partial | <what merged, what is missing> |
| `t3` | blocked | <why it could not proceed> |

## Mid-work Decisions

<Constraints discovered, scope cuts, and choices made during execution that
were not in the plan. When a delivery store exists for this plan, quote each
approved deviation by its `dN` id — the record is the decision, consumed here,
not re-litigated. A decision no record covers is still captured directly. One
per bullet.>

- `d2` — <what deviated, from the record> — <the record's reason>
- <decision not covered by any deviation record> — <why it was made>

## Drift From Plan

<Every plan task whose delivery differs from its contract. Exhaustive relative
to the plan. When a delivery store exists, an entry covered by an approved
deviation names the plan item as `` `tN` (`dN`) `` and inherits that record's
reason and classification verbatim. Drift NOT covered by any record is still
recorded here exhaustively, exactly as before — never silently normalized. If
nothing drifted, state "no drift" and back it with the task-by-task accounting
above.>

| Plan item | Reason for divergence | Classification |
|-----------|-----------------------|----------------|
| `t2` (`d2`) | <quoted from the `d2` record's reason> | needs-follow-up |
| `t3` | <what changed vs. the confirmed task — no record covers this> | risky |

## Evidence

<The read-only checks run to substantiate the claims below: test node ids that
ran, lint results, `git log` ranges, PR/issue numbers. This section is what
makes every claim resolvable.>

- tests: `<pytest node id>` — <pass | fail>
- lint: `<command>` — <result>
- commits: `<sha>..<sha>`
- PRs / issues: <#NN, ...>

## Delivery Claims

<Each claim: the assertion, a confidence level, and a resolvable evidence
pointer — or an explicit `unverified` marker. No claim is asserted as done
without evidence.>

| Claim | Confidence | Evidence |
|-------|------------|----------|
| <what was delivered> | high | commit `<sha>` / file `<path>` |
| <what was delivered> | medium | PR `#<n>` · test `<node id>` |
| <what is asserted but not checked> | unverified | (no evidence — not claimed done) |

## Remaining Work / Follow-up

<What is incomplete, deferred, blocked, or newly discovered — including any
failure and its cause. Every partial/dropped/blocked task from Actual Delivery
reappears here with its next step.>

- <remaining item> — <next step / owner>

Delivery Claims — the row contract

Every Delivery Claims row carries three fields:

• Claim — the specific thing asserted as delivered.
• Confidence — exactly one of high / medium / low / unverified.
• Evidence — at least one resolvable pointer, or the explicit unverified marker. A resolvable pointer is one a reader can follow: a commit SHA that exists, a file path that is present, a PR or issue number that is real, or a test node id that ran. "It works" is not evidence.

devague summary's skeleton already appends a Lapse ledger evidence: block beneath the placeholder row whenever the frame has any filed lapses — approved entries rendered as a small Lapse | Code | What table, still-proposed ones listed as pending approval (not yet evidence), and rejected ones omitted entirely (devague/render/summary_md.py's _lapse_evidence_lines). Treat that block as the ledger's contribution to this section — read it (or run devague lapse --list directly) rather than re-deriving by memory which lapses bear on which claim.

Drift From Plan — the entry contract

Every Drift From Plan entry names three things:

• The plan item it diverges from (by task id, quoted from the plan).
• The reason for the divergence.
• Exactly one classification: acceptable (a defensible deviation), risky (may cause a problem; flag it), or needs-follow-up (leaves work the plan assumed done).

When a delivery store exists and an approved devague deviate record covers the item, cite it by its dN id and inherit its reason and classification verbatim — the record is the recorded ground truth, not something this skill re-derives. An item no record covers still gets an entry here, worked out the same way as before.

Degrading when there is no plan state

The summary is producible from durable inputs — plan state, git history, PR links, test output — and never depends on unrecorded memory of the run. There are three tiers, most to least mechanical, and the artifact's baseline: line names which one applied:

1. devague summary skeleton — the plan (and, if any, its delivery record) can both be read; the render is fully mechanical. baseline: devague summary skeleton.
2. Hand-assembly — devague summary isn't available (the verb is missing, or the state it needs can't be read) but the plan itself can still be read: reconstruct the baseline read-only via devague plan show [--json] and devague plan waves --json. baseline: devague plan (hand-assembled).
3. Git + PR history — no devague plan state exists at all: degrade to git history and PR history as the planned-work baseline. baseline: git+PR history (no plan state).

Whichever tier applied, SAY SO in the artifact (in the baseline: line and the Planned Work section). The delivery summary is still a valid accountability artifact either way; it just names its baseline honestly instead of pretending a more mechanical path was used.