/implement-issue

name: implement-issue
description: Implements an issue end-to-end: fetches the spec from the project issue tracker, creates branch, writes code with TDD, runs checks, commits, publishes a draft change (PR/MR), closes issue on merge. Tracker- and host-agnostic — GitHub via gh CLI is the factory default; docs/agents/issue-tracker.md and docs/agents/code-host.md override. Use when user says "implement issue", "work on issue #N", "/implement-issue", or wants to process an issue locally.

Implement Issue

Issue → branch → test-first code → checks → draft PR. One issue per invocation.

**Contract docs.** Issue mechanics come from `docs/agents/issue-tracker.md` (its `## Delivery operations`), change mechanics from `docs/agents/code-host.md`. Read those two first if present; where they define an operation, they win over the `gh` defaults below. "PR" means whatever the code host calls a reviewable change. Their annexes (`code-host-ci.md`, `issue-authoring.md`) are for later phases — implementing an issue needs neither.

What the work is judged on

1. **It does what the issue asks, the way the spec decided.** Every acceptance criterion, built to the interfaces and seams the spec's Implementation and Testing Decisions fix. Where the issue is part of a larger spec, your code has to fit the rest of it: reuse what already exists instead of adding a second version of it. 2. **Every behaviour has a test that fails without it.** Proven, not assumed: you saw it fail (see *Red before green*). 3. **The change is as small as the issue allows.** Refactor-level cleanups belong to the review, not here.

Everything else in this skill is how to get there without wasting the session.

Red before green

One behaviour at a time: write its test, **run it and watch it fail**, write only the code that makes it pass, run it green, next behaviour. Never write the tests in bulk and the code after; never write code before its test has been seen red.

The red run is the proof the test can fail. A test that passes before the code exists tests nothing: the behaviour comes by another path, or the test never reaches it — an assertion that runs before an async result lands, a key pressed with the focus already on the button so the browser's own handling passes it, a mock that answers whatever is asked. Rewrite it until it is red for the right reason (the message names the missing behaviour, not a typo or an import), then implement.

A good test:

• exercises behaviour through the public seam — what a user or caller sees —

never internals, so it survives a refactor;

• takes its expected values from the spec or a worked example, never

recomputed the way the code computes them;

• fails when the behaviour it names breaks, and only then.

When your change moves what an **existing** test exercises (a listener to another target, a handler to another component), make that test fail once against a deliberately broken version of your code, then restore it: a test a refactor left green may no longer be able to fail.

Where no test can come first — pure wiring, config, no harness for it — say so in the PR's Test plan rather than skipping silently.

Flow

1. Select the issue

**When a caller (e.g. /developer) named the issue, skip this step** — check it is open and go on.

Interactively: if the given issue has sub-issues (GitHub: `gh api graphql` on `issue.subIssues(first: 50) { pageInfo { hasNextPage } nodes { number title state } }`), pick the first open one whose blockers — native dependency links and any "Blocked by" list in its body — are all closed. Over 50 children: stop and report, the parent should be split. Nothing unblocked: report and stop. With no ref, list open issues labelled `ready-for-agent` (or the repo's mapping in `docs/agents/triage-labels.md`) and pick bugs > tracer bullets > polish > refactors, or ask.

2. Read the issue

Once, with its comments, into a file — GitHub: `gh issue view <N> --json title,body,comments > /tmp/issue-<N>.json`, then read the file. (`gh issue view --comments` comes back empty inside a /developer worktree.)

The issue's `## Spec extract` carries the spec decisions that apply to it; read the parent spec only when that section is missing — unless the caller tells you to read it anyway.

3. Branch and bootstrap

git fetch origin main
git checkout -b agent/issue-<N>-<slug> origin/main   # slug: title, lowercased, dashed, ≤50 chars

• **A branch name from the caller** replaces `agent/issue-<N>-<slug>`.
• **A base branch from the caller** (e.g. a spec's integration branch)

replaces `main` everywhere: fetch it, branch from `origin/<base>`, open the PR against it.

• Local code host (no `origin`): branch from local `main` / `<base>`.
• Never `git checkout main` — in a linked worktree it is held by the primary

checkout.

• As a /developer worker, first confirm you are in a linked worktree:

`git rev-parse --path-format=absolute --git-dir --git-common-dir` must print two different paths (keep `--path-format=absolute`). The same path twice means you are in the user's checkout: stop and report blocked.

Branch **before** reading any source — a fresh worktree starts from the local main, which can lag. Then install dependencies quietly (`pnpm install --reporter=silent` or the project's equivalent; no quiet flag → redirect to a file and read its tail only on failure) and run any prerequisite build `AGENTS.md` / `CLAUDE.md` names. All paths stay inside the worktree.

4. Implement

Explore first, through the repo's own map: `AGENTS.md` / `CLAUDE.md` and what they link under `docs/agents/`; where they prescribe a zone map or an index command (`just outline <path>`, ctags…), that is binding — use it rather than `cat` on large files, never truncate it or silence its errors, and batch several lookups in one call. Read each file whole **once**; afterwards use `grep -n` / `sed -n`. Never re-read a file to check your own edit.

Then the red →