Ship a PR

Design the diff before writing it. The design binds nothing by itself, so Stage 1 stops and waits for the orchestrator to check it against the brief before Stage 2 touches source. Self-review is a checklist, not reflection: an unanswered question fails the stage, same as an unrun command.

Checklist

Copy this into your own response and check off each stage as you complete it:

Ship progress:
- [ ] 0. Understand: spec gate, engineering docs, seed the worktree
- [ ] 1. Design: PR body sections, then stop and wait for the design gate
- [ ] 2. Implement: match the analog, stay in budget (references/implement.md)
- [ ] 3. Self-review: the standard, ten shape questions, the coverage question (references/self-review.md)
- [ ] 4. Gate: make check green, gh pr ready

Freedom per stage

Thinking is high freedom. Verification and output are low: a checklist or a template you improvise is not one.

Register

Every instruction below, and in references/, carries exactly one of these:

A CONSTRAINT without a stated consequence is a preference, not a CONSTRAINT: rewrite it or demote it.

Stages

Stage 0: Understand

CONSTRAINT: read the issue (gh issue view <n>), docs/engineering/ in full, the docs/patterns/ file for your concern, and docs-site/content/resources/roadmap.mdx for the arc this issue sits in, before any edit. Consequence: skip it and Stage 1's design has nothing real to bind against, and the design gate has nothing to compare it to.

CONSTRAINT, spec gate: if the issue lacks Done when outcomes or scope bounds (what must NOT be added), comment on the issue naming exactly what is missing and stop. Consequence of skipping this: an unbounded spec produces unbounded code, and the reviewer's Scope phase will file it.

Seed the worktree: copy .env if present, then uv venv --python 3.12 && make install.

Stage 1: Design, then wait

Run uv run scripts/repomap.py. Open a draft PR (branch feat/<n>-<slug> or fix/<n>-<slug>, gh pr create --draft targeting dev, Closes #<n>) and write the complete design into its body before touching source. Section shape, caps, and the design gate: references/design.md.

CONSTRAINT: after posting the design, stop. Do not edit source until the orchestrator (or the user, outside ship-issue) tells you to proceed. Consequence of skipping this: bloat argued against code that already works never gets fixed; catching it at design costs nothing.

Stage 2: Implement

JUDGMENT, high freedom. Depth and test rules: references/implement.md.

Stage 3: Self-review

CONSTRAINT: answer every question in references/self-review.md in writing before Stage 4, including the coverage question. An unanswered question fails the stage.

Stage 4: Gate

• Compact the PR body: it describes the change as it now stands, not the rounds that produced it. Delete abandoned design and justifications the code no longer needs.
• CONSTRAINT: run export PR_BODY="$(gh pr view <n> --json body -q .body)" && make check, 100% green, before gh pr ready. Two consequences: a red make check shipped by gh pr ready puts a red required check on the PR and it cannot merge; and without the export, scripts/check_docs_impact.py reads an empty body, reports affected pages as unreviewed (or the author never sees the list), so CI's required "Check affected documentation" goes red on a gate believed clean (#602, #607, #617).
• No attribution trailers anywhere.

Answering a review

Reply in the review thread and resolve it. Never grow the PR body to answer a finding: a thread collapses once addressed, a body is what the next reader wades through to learn what the change does. The body only changes when the change does.

CONSTRAINT: resolve every thread, or the PR cannot merge. dev enforces this twice, as required_conversation_resolution in branch protection and required_review_thread_resolution in its ruleset, so one open thread holds the PR at BLOCKED with every check green, zero required approvals, and nothing in gh pr checks to explain it. Fixing the code is not answering the finding; the thread is.

gh api graphql -f query='mutation($t:ID!){resolveReviewThread(input:{threadId:$t}){thread{isResolved}}}' -f t="<thread-id>"

Thread ids come from reviewThreads on the pull request. Reply first, then resolve: a resolved thread with no reply tells the next reader nothing about what changed.

Measured by

Neither agent scores itself. What the dev side of this skill is measured on, from #431:

Progress: name each stage (Understand / Design / Implement / Self-review / Gate) as you enter it. A silent multi-stage run reads as a stall.