---
name: deliver
description: |
  Take one ticket or idea from raw intent to merge-ready (or shipped, when
  asked): context-first, docs→tests→code, live QA, refactor at three
  altitudes, semantic commits, diverse-provider review, adversarial pre-ship
  thinking. Use for "deliver this", "build this ticket", "make it
  merge-ready", "take this end to end". Trigger: /deliver.
argument-hint: "[backlog-item | description]"
---

# /deliver

One piece of work, end to end, done the way we'd be proud of. This skill is
judgment checkpoints, not phase machinery — you own the decomposition, and
even the best model skips some of these steps unprompted. Don't.

## Context first

Before writing anything: read the ticket and the live code it touches; build
real product understanding (who uses this, what breaks if it's wrong);
`/research` best practices when the design has open questions; and
**pre-factor** — if the change lands in messy ground, clean the ground first
as its own commit. If the ticket has no goal or acceptance oracle, run
`/shape` (or write the oracle yourself for small work) before building.
Building without an oracle yields plausible garbage.

**Verification system first** (shared AGENTS.md, Layer 1): locate the
repo's live-verification harness — the one command that exercises a change
against the running thing and emits reviewable evidence. If none exists,
building it is the ticket's first milestone, not a detour; every milestone
after ships through it. The harness-before-feature session catches the
bugs unit tests structurally cannot.

## Docs → tests → code

Write the documentation first: what will be true when this works (README
section, doc comment, API doc — whatever the repo's convention is). Then
failing tests that encode it. Then code to green. After green, loop back and
sync all three — docs, tests, and code must agree at the end, not just the
start. Work on a feature branch; never commit to the default branch.

Lenses, when judgment is contested: Ousterhout (deep modules, small
interfaces), Carmack (shippability — what can be cut), Kent C. Dodds (test
what users do, not implementation), Uncle Bob (leave it cleaner than found).

## QA the live thing

"Tests pass" is not verification. Run the application and drive the surface
that changed — `/qa` routes by app shape (browser, API, CLI, library, MCP).
Run it through the verification harness you located or built in Context
first. Leave an evidence packet — screenshots, transcripts,
request/response pairs, a verdict — where the repo keeps its receipts, so
the claim is checkable after you're gone.

## Refactor at three altitudes

With working code in hand, ask at each level — and act on what you find:

1. **The diff.** Would we write it this way from scratch? Duplicate code to
   DRY out? Conditionals to collapse? Slop to delete (unnecessary comments,
   defensive try/catch, casts, dead branches)?
2. **The codebase.** Is there a cleaner seam? Does this change reveal an
   abstraction that should exist — or one that should die?
3. **The backlog.** Does what you learned change what the product should do
   next? File tickets for the bigger moves; don't smuggle them into this
   branch.

## Land it

- **Semantic conventional commits**, push (the `/yeet` discipline: classify,
  split by concern, why-shaped bodies).
- **Review by diverse providers — never only yourself.** `/code-review` fans
  out fresh-context reviewers across model families; fix blockers, re-review
  until clean. Iterate until CI is green *and rigorous* — if the gate
  wouldn't have caught the likely failure, strengthening it is part of this
  ticket (`/ci`). Respond to every review finding: fix, ticket, or rejected
  with a stated reason.
- **Think adversarially before shipping.** If this breaks in production,
  what breaks first? How would we know — which log line, metric, or alert?
  If the answer is "we wouldn't," add the logging/alerting now, not after
  the incident. Dependency upgrades ride as one curated, risk-assessed
  commit — never a pile of unexamined bumps.
- **Default stop: merge-ready.** Squash-merge to master (the `/ship`
  trailer canon, `meta/CONTRACTS.md`) only when the operator asked for
  shipped, not just delivered. Then monitor if the repo has a post-ship
  signal, and ta-da.

## Done means

State plainly: what behavior changed and how you verified it live (exact
command/route/surface), what review found and how it was resolved, what
residual risk remains, and final `git status --short` + branch/remote state.
A clean tree is part of done — every leftover path gets committed, ignored,
moved out, or named as a blocker. No green-gate hand-waving: name the
evidence, not the aggregate.

## Gotchas

- **Skipping shape.** No oracle → no delivery. Write one or route to
  `/shape`.
- **Re-shaping mid-build.** If implementation reveals the shape is wrong,
  stop and say so — don't spin on a broken spec.
- **Self-review leniency.** The author's context rationalizes the author's
  choices. Reviewers get the diff and the oracle, never your reasoning
  trail.
- **Stale tickets.** If the item already shipped (closure trailer in
  history, `_done/` copy), refuse and fix the backlog instead.
- **Heavy/parallel lanes** route to `/sprites`; quick exploration stays
  local. Don't pre-shred work into atomic tasks — an outcome-shaped lane
  owns its own decomposition.
