implement-issue git:20260915.96b4731A

Immutable. This exact content is served forever at /api/v1/blob/8f9a1b8f479cd56c.

---
name: implement-issue
description: >-
  Turn an existing GitHub issue into a finished pull request — the actual coding. Use when an issue
  carries a `🛠️ Implementation plan` checklist and the user wants it BUILT: worktree, draft PR,
  task-by-task commits ticked on the live issue, review, ready-flip. Triggers: "implement issue 47",
  "knock out the tasks on issue 71", "execute the plan", "resume issue #X", « implémente l'issue 47
  », « exécute le plan de l'issue », a bare issue link with "go build it" — including keeping the
  IN-FLIGHT PR mergeable (sync/conflicts with `main`) while it is still being built. Does NOT apply
  to planning a NEW issue (create-issue), landing a finished PR (merge-pr), or ad-hoc coding with no
  plan.
license: MIT
compatibility: >-
  Requires an authenticated gh CLI, git, and a code-review skill. Reads the committed repo profile
  (.claude/skills/repo-profile.md) generated by profile-repo. Self-contained otherwise: the
  worktree recipe is its own scripts/, the plan shape and TDD loop ship under skills/_shared/.
metadata:
  author: Philippe Matray
  suite: tagout
---

# Implement an issue from its plan

## What this does

`create-issue` builds every issue around a `**🛠️ Implementation plan**` section: a checklist of
`### Task N` blocks whose every step is a `- [ ]` checkbox, with the **last step of each task being its
commit message**. (Older issues carry the same plan as a comment — this skill handles both.) That plan
is a contract an executor can run cold; this skill is that executor.

It turns the plan into a real PR the way a careful engineer would: isolated worktree, draft PR opened
up front so progress is visible, one commit per task, and — the part that makes the issue a live
progress board — **each task's checkboxes get ticked on the issue as the work lands.** When the last
box is checked, it runs a code review, fixes what surfaces, and marks the PR ready.

Plans name this skill as their executor (the header note in
[`../_shared/plan-shape.md`](../_shared/plan-shape.md)), and the doctrine it executes by — the plan
shape, the TDD loop in [`../_shared/tdd-loop.md`](../_shared/tdd-loop.md) — ships under
`skills/_shared/`, so it runs the same on every machine with no third-party plugin installed (#324).
This skill owns the GitHub/worktree/PR bookkeeping around that doctrine.

## Autonomy contract

Run **hands-off** once started — the user watches, doesn't babysit. See
[ADR 0005](../../docs/adr/0005-the-lifecycle-skills-run-hands-off-triage-backlog-does-not.md) for the
decision scope. Whenever a step (a dispatched sub-agent, the code-review pass, a merge) would pause
for a question or sign-off, **pick the reasonable default, state the assumption, keep going.** Stop
only for a genuine blocker:

- `gh` not authenticated, or no push access.
- No `🛠️ Implementation plan` on the issue — not in body, not in a comment (nothing to execute).
- A task's tests can't be made green after an honest effort — don't fake green, don't commit over a red bar, don't tick a box for work that doesn't pass. Stop and report the wall with the failing output. **"Honest effort" means you ran the `debug-issue` loop**: a local command that reproduces the red, built and run before any fix — not a fix retried three times.
- A merge conflict you can't resolve with confidence — both `main` and your branch rewrote the *same logic*, and picking a side would silently drop a sibling PR's work. The mechanical conflicts (version, changelog, snapshots, lockfiles) have known-correct resolutions (Step 8) — handle those; stop only for genuinely ambiguous ones, showing both sides.

Never tick a box, commit, or flip the PR to ready on an assumption — those three acts claim work is
*done*; back them with evidence (tests run, output seen). A resolved merge is the same claim:
re-build and re-test on the merged tree — a clean *textual* merge is not a clean *semantic* one.

## Checklist

Create a task per item and work them in order. Step 6 is the loop — one pass per task.

1. **Preconditions** — `gh` works, you're in the target repo, resolve the issue number.
2. **Read the plan** — fetch the `🛠️ Implementation plan` from the issue body (or a comment, on older issues); save it and note where it lives.
3. **Pick the execution mode** — assess complexity → *Inline (Extra)* or *Subagent-per-task (Ultracode)*.
4. **Create this issue's own worktree** — via `scripts/make-worktree.sh`, off `main`. Never implement from the checkout you were launched in, even if it is already a worktree. If no branch-name match is found, fall back to an issue-scoped GitHub search before scaffolding a new one — a second open PR closing the same issue is the failure this step exists to prevent.
5. **Open the draft PR** — empty scaffold commit, push, `gh pr create --draft` linking the issue; PR title carries a Conventional Commits prefix (`fix:`/`feat:`/…, CI-enforced) and ends with `(#<issue>)`.
6. **Loop until every task is checked** — implement the next unchecked task → verify green → commit → tick that task on the issue plan *and* the PR description → push.
7. **Code review** — run the `code-review` skill, apply + commit the fixes, push.
8. **Sync with `main`** — merge the latest `origin/main` into the branch and resolve conflicts per the profile's *Conflict hot-spots* (version, changelog, snapshots, lockfiles — see reference).
9. **Verify, format, then mark ready** — build/tests green on the merged tree AND the profile's format/lint verify gate clean (commit fixes), then `gh pr ready`.
10. **Recap** — the shared closing shape ([`../_shared/recap.md`](../_shared/recap.md), with its [Boundary findings block](../_shared/recap.md#the-boundary-findings-block)): PR URL, what shipped, what was assumed or deferred.

Resume-safe: re-running mid-flight is fine. A task is "done" when **all** its step checkboxes read
`- [x]`; start at the first that isn't. Reuse **this issue's** worktree/branch/PR rather than making a
second — matched first on the issue's own branch name, then, if that finds nothing, on whether GitHub
already has an open PR closing this issue; never on "whatever checkout I woke up in" (see
`references/github-mechanics.md`).

---

## How to read this skill

**One step file at a time, when you reach it — never all up front.** Every token loaded here is
re-read on every later turn (`skills/auto-dev/references/token-economics.md`: ~83% of a run's
spend is context re-read), so the step bodies live under `references/steps/` and the checklist
above is the whole of what loads with the skill. Open a step when its checklist item starts; the
shared references it names load the same way, from inside that step.

- Step 1 — [`references/steps/01-preconditions.md`](references/steps/01-preconditions.md) · reads [`_shared/preconditions.md`](../_shared/preconditions.md)
- Step 2 — [`references/steps/02-read-the-plan.md`](references/steps/02-read-the-plan.md) · reads [`_shared/plan-shape.md`](../_shared/plan-shape.md), [`_shared/untrusted-input-boundary.md`](../_shared/untrusted-input-boundary.md)
- Step 3 — [`references/steps/03-execution-mode.md`](references/steps/03-execution-mode.md) · reads [`_shared/tdd-loop.md`](../_shared/tdd-loop.md)
- Step 4 — [`references/steps/04-worktree.md`](references/steps/04-worktree.md) · reads [`_shared/guard-invocation.md`](../_shared/guard-invocation.md), [`_shared/worktree-ignore-check.md`](../_shared/worktree-ignore-check.md)
- Step 5 — [`references/steps/05-open-the-draft-pr.md`](references/steps/05-open-the-draft-pr.md) · reads [`_shared/sync-with-main.md`](../_shared/sync-with-main.md)
- Step 6 — [`references/steps/06-implementation-loop.md`](references/steps/06-implementation-loop.md) · reads [`_shared/tdd-loop.md`](../_shared/tdd-loop.md), [`_shared/test-seams.md`](../_shared/test-seams.md)
- Step 7 — [`references/steps/07-review.md`](references/steps/07-review.md)
- Step 8 — [`references/steps/08-sync-with-main.md`](references/steps/08-sync-with-main.md) · reads [`_shared/sync-with-main.md`](../_shared/sync-with-main.md)
- Step 9 — [`references/steps/09-verify-and-mark-ready.md`](references/steps/09-verify-and-mark-ready.md)
- Step 10 — [`references/steps/10-recap.md`](references/steps/10-recap.md) · reads [`_shared/recap.md`](../_shared/recap.md)

## Notes on quality

- **The checkbox is a promise.** Ticking `- [x]` on the live issue says that task is done and tested. Only ever tick after a real green test run + commit — a checked box over a red bar lies.
- **A zero exit is not a receipt.** `git commit` does not check you are still on the branch you created, and `git push -u` prints "branch … set up to track …" whether or not your commit reached your branch. Both are claims about *what git attempted*, not about *where the work is*. That is why Steps 5–9 go through the guards and why the guards re-read state instead of trusting the return code — the same reason `tick-plan.sh` reads the issue back after PATCHing it. Step 8's merge — the largest write in the flow, and the one with the widest window, since conflict resolution sits inside it — goes through `guarded-merge.sh` on the same terms (#41).
- **One commit per task, message from the plan** (its final step) — verbatim, so git history mirrors the plan and the issue. The one exception is an inline fix under the carve-out below: its own commit, `fix: <what it corrects>`, never folded into the task's.
- **Stay resumable.** Everything keys off the issue's checkbox state and the existing branch/PR, so a re-run picks up where it left off.
- **Don't widen the blast radius.** Implement the plan, not your own ideas. A finding you discover on the way takes one of two exits, and the test has two halves that must **both** hold: it is **fixed inline** when it is **local** (every file the fix touches is already modified by this PR) *and* **small** (the fix adds no file to the diff and no behaviour the Spec does not already cover). Whether it is a regression of a shipped guarantee is **not** part of the test. An inline fix is its **own commit** and gets a line in the PR description under `### Fixed along the way`, so the trail survives without an issue. Put that heading **above** `### Follow-ups`: `merge-pr` harvests the lines after a Follow-ups heading, and a sibling placed below it would be read as deferred work and filed. Why the two halves are conjunctive, and why the regression axis is out, sits beside the disposition table in `references/spec-review.md`. Anything failing either half is deferred as before: a bullet under `### Follow-ups` in the **PR description** (and called out in the report) — that heading is where `/merge-pr` harvests deferred work and files it as tracked issues; noting it only in the ephemeral report would lose it. Don't smuggle that work into this PR.