sgomez/developer-skills / skills/implement-issue
implement-issue
VerifiedImplement 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
- 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.
- Every behaviour has a test that fails without it. Proven, not assumed: you saw it fail (see Red before green).
- 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
maineverywhere: fetch it, branch fromorigin/<base>, open the PR against it. - Local code host (no
origin): branch from localmain/<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-dirmust 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 → green loop above, running only the test file you are working
on with the project's quietest reporter (pnpm test <file> --reporter=dot
or the project's form). A red run: re-run just that file or test for its
output, never the suite.
5. Checks
After the last loop is green, once each:
- Typecheck and the full suite — unless the repo's pre-push hook runs
them (
lefthook.yml,.husky/pre-push,.pre-commit-config.yaml); then the push in step 7 is that run. - The formatter's writing form (
biome check --write .,cargo fmt --all, …), always — a hook only checks. - The lint gate (the repo's own recipe —
just lint, apackage.jsonscript…), unless the pre-push hook runs it.
Commands without a quiet reporter: <cmd> > /tmp/check.log 2>&1; echo "exit=$?",
and grep the log only when the exit is non-zero. Never pipe a gate into tail:
it throws the exit code away. A green gate is never re-run to confirm it.
Fix every failure. If you cannot, see Blocked.
6. Commit
One commit, Conventional Commits, body lines ≤ 100 characters:
<type>(<scope>): <short description>
Implements #<N>: <issue title>
- <key decision>
7. Publish
A draft PR linked to the issue for closing — GitHub:
git push origin <branch>
gh pr create --draft --base <base> \
--title "<type>(<scope>): <short description>" \
--body "Closes #<N>
## What changed
<brief summary; any judgement call on an ambiguous point>
## Test plan
- [ ] <acceptance criterion> — <test name>, seen red first"
For a bug, add a ## Root cause section after ## What changed: where the
wrong value or state originates, and that the fix acts there — not on the
one consumer the issue reported. The reviewer checks it against the code.
Run the push alone, bare, with the Bash tool's maximum timeout
(timeout: 600000) — a gate-running pre-push hook outlasts the default, and the
worktree sandbox refuses compound shapes. If the hook rejects the push, fix,
amend (nothing was published), push again. Never --no-verify.
Keep the body's shape whatever the host — Closes <ref>, ## What changed,
## Root cause (bugs), ## Test plan.
8. Done
Do not close the issue. Closes #<N> closes it on merge where the host
supports that; otherwise whoever merges closes it.
Blocked
When you cannot finish (missing context, unfixable failures, an external
dependency), comment on the issue — GitHub:
gh issue comment <N> --body "Blocked: <reason>. <what would unblock it>." —
and stop. Do not close it. Unattended, do not wait for an answer.
Rules
- One issue per invocation.
- No code before its test has been seen failing; a test green on its first run is rewritten, not kept.
- Never bypass git hooks. A pre-push failure in a package you did not touch: suspect missing installs first; genuinely broken on the base branch → Blocked.
- No commented-out code, no TODOs.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |