summarize-delivery

name	summarize-delivery
description	Close the loop after an assign-to-workforce run by turning what actually happened into an accountability artifact — planned versus actual delivery, mid-work decisions, plan drift, evidence-backed delivery claims, and remaining work. The plan the user confirmed is the contract; this skill records where execution obeyed it, where it changed, and what is genuinely safe to claim as delivered. Runs on complete, partial, AND failed runs — failure is reported faithfully, never smoothed over. Use when the user says "summarize delivery", "delivery summary", "wrap up", "close the loop", "what did we actually ship", or "plan versus actual", or after assign-to-workforce merges (or fails to merge) a plan's waves. Authored and maintained in agentculture/devague (origin = devague); guildmaster pulls this skill from here and broadcasts it to the AgentCulture mesh — it is NOT vendored from guildmaster like the inbound skills here.
type	command

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

The skill is named summarize-delivery; it is the delivery-side closure leg of the devague method — the fifth leg, run after the sibling /assign-to-workforce skill has executed (or attempted to execute) a converged plan. 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, 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. Read the plan the run executed. When the run was devague-driven, the baseline is the plan's tasks, acceptance criteria, and waves, available 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. Quote task ids and summaries verbatim into the Planned Work section — 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. Each claim carries a confidence level (high / medium / low / unverified) and at least one resolvable evidence pointer, or an explicit unverified marker. 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 plan | 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 `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. One per bullet.>

- <decision> — <why it was made>

## Drift From Plan

<Every plan task whose delivery differs from its contract. Exhaustive relative
to the plan. Each entry: the plan item, the reason, and exactly one of
acceptable / risky / needs-follow-up. If nothing drifted, state "no drift"
and back it with the task-by-task accounting above.>

| Plan item | Reason for divergence | Classification |
|-----------|-----------------------|----------------|
| `t2` | <what changed vs. the confirmed task> | needs-follow-up |
| `t3` | <what changed vs. the confirmed task> | 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.

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).

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. When the run was devague-driven, the plan (tasks, acceptance criteria, waves) and the exported plan-md are the planned-work baseline.

When no devague plan state exists, degrade to git history and PR history as the planned-work baseline — and SAY SO in the artifact (in the baseline: line and the Planned Work section). The delivery summary is still a valid accountability artifact; it just names its baseline honestly instead of pretending a plan existed.

The only devague moves this skill uses — all read-only

This skill never mutates devague state. The complete set of devague moves it documents is read-only:

Move	What it reads
devague plan show [--json]	The plan's tasks, acceptance criteria, dependencies.
devague plan waves --json	The wave batches + per-task summary / instruction / acceptance_criteria / covers, keyed by id — the verbatim planned-work baseline.
devague scope --list [--json]	Recorded scope-exploration findings, if the frame carried any.
devague show [--json]	A frame / plan rendered for reading.
devague status [--json]	Where a frame stands (read-only next-move helper).

No other devague command appears in this method. Producing a delivery summary leaves .devague/ byte-identical (issue #20).

Hard rules (do not violate)

These are the point of the method — a delivery summary must be trustworthy.

• No overclaiming. A delivery claim without evidence is marked unverified, never asserted as done. The unverified marker survives into the committed artifact; no downstream step upgrades a claim's confidence without new evidence.
• Partial and failed runs are valid inputs. There is no completion precondition — a run that merged zero waves is still a valid input. Failure is reported faithfully: it appears under Drift and Remaining Work with its cause, and no delivery claim says "done". No section ever becomes unwritable.
• Verification is read-only. You may run the test suite, the linters, and git log to substantiate a claim before writing it. Verification never mutates code or state. A claim you cannot verify stays unverified.
• No devague state mutation. The only devague moves this skill uses are the read-only plan show, plan waves, scope --list, show, and status (see the table above). Never run a mutating devague command, and never run devague plan inside a task worktree to "mark a task done" — that is /assign-to-workforce's boundary too (#20).
• Account for 100 % of plan tasks. Every plan task appears in Actual Delivery as delivered / partial / dropped / blocked — no silent omissions. Both the task count and the claim-evidence coverage are checkable by inspecting the artifact alone, with no hidden context.
• Quote the plan verbatim. Planned Work quotes task ids and summaries verbatim from devague plan waves --json. Drift is measured against the confirmed contract, not a reworded version of it.

Worked example

A partial run: three tasks were planned, two merged cleanly, and the third failed its post-merge TDD gate and was reverted. Every section is still writable — nothing about the failure makes the artifact unproducible.

# 1. Establish the planned-work baseline — read-only, quoted verbatim.
devague plan waves --json      # -> {"plan": "widget-export", "waves": [...],
                               #     "tasks": {"t1": {...}, "t2": {...}, "t3": {...}}}
devague plan show              # human-readable plan for the Intent paragraph

# 2. Establish actual delivery — read-only reconciliation.
git log --oneline main~4..main   # what merged
gh pr view 71                    # the run's PR (evidence pointers)
uv run pytest tests/test_export.py::test_widget_round_trips -q  # verify a claim

The resulting docs/deliveries/2026-07-09-widget-export.md:

# Delivery Summary — widget export

plan: `widget-export` · run: `partial` · date: `2026-07-09`
baseline: `devague plan (widget-export)`

## Intent

Ship the `widget export` command as three independent tasks fanned out by
/assign-to-workforce.

## Planned Work

Quoted verbatim from `devague plan waves --json`:

- `t1` — add the `export` verb to the CLI chassis
- `t2` — implement the widget-md renderer
- `t3` — wire the convergence gate into `export`

## Actual Delivery

| Plan task | Status | What actually landed |
|-----------|--------|----------------------|
| `t1` | delivered | `export` verb registered; merged in PR `#71` |
| `t2` | delivered | renderer added at `devague/render/widget_md.py` |
| `t3` | blocked | post-merge tests failed; merge reverted |

## Mid-work Decisions

- t2 renders an absent field as an empty line rather than filler — matches the
  no-fabrication rule the plan assumed but did not spell out.

## Drift From Plan

| Plan item | Reason for divergence | Classification |
|-----------|-----------------------|----------------|
| `t3` | gate raised on an unconverged plan; reverted, not delivered | needs-follow-up |

## Evidence

- tests: `tests/test_export.py::test_widget_round_trips` — pass
- tests: `tests/test_export.py::test_gate_blocks_unconverged` — fail
- commits: `main~4..main`
- PRs: `#71`

## Delivery Claims

| Claim | Confidence | Evidence |
|-------|------------|----------|
| the `export` verb ships and round-trips | high | test `tests/test_export.py::test_widget_round_trips` · PR `#71` |
| the widget-md renderer exists | high | file `devague/render/widget_md.py` |
| the convergence gate blocks unconverged exports | unverified | t3 reverted — not claimed done |

## Remaining Work / Follow-up

- `t3` — fix the gate wiring so `test_gate_blocks_unconverged` passes, then
  re-run the TDD merge gate. Blocking for the feature's completeness.

Note what the failure did: it flowed into Actual Delivery (blocked), Drift (needs-follow-up), Delivery Claims (unverified), and Remaining Work — and no claim overstated it. That is the whole point.

After the summary — the final PR gate

The delivery summary is the review map for /assign-to-workforce's third human gate (the final PR). Commit docs/deliveries/<created-date>-<slug>.md alongside the run's work so the reviewer can audit planned-versus-actual without replaying the transcript. This skill does not open the PR or mutate any state — it produces the artifact the human reviews.

Provenance

This is a first-party skill — its origin is agentculture/devague, the fifth in the outbound family after /scope, /think, /spec-to-plan, and /assign-to-workforce, covering the delivery-side closure leg after a plan is executed. guildmaster pulls it from here and broadcasts it to the AgentCulture mesh; because devague is upstream, it is never re-vendored back from guildmaster's re-broadcast copy. The cite, don't import policy still holds: downstream repos copy it, they don't symlink or depend on it. See docs/skill-sources.md.