implement-issue

name	implement-issue
description	Validates a GitHub issue against the current codebase, reading the nearest AGENTS.md/CLAUDE.md, area context, and any applicable stack/conventions skills first. Runs a full-context investigation (real project commands, whole code path, no shortcuts), handles already-fixed issues by closing or adding regression tests, invokes the grill skill when registered, then presents implementation options and stops for the user's choice before coding. Updates the branch against origin's default branch, implements the chosen option, searches project context for DEFINITION_OF_READY.md before implementation, runs verification (UI/UX checks plus the project's full check gate), reviews against the issue's acceptance criteria and project-context DEFINITION_OF_DONE.md before handoff, runs a /review code review, and always hands off via /create-pr. Use when the user runs /implement-issue with an issue number.
license	Unlicense OR MIT
compatibility	Requires the GitHub CLI (gh) authenticated to the target repository and network access; verification examples assume a Bun toolchain.

Implement issue

Instructions

Validate and implement a GitHub issue in the current repository.

Non-negotiable gates (do not skip, do not rationalize)

These four gates are mandatory. Most failures of this skill come from skipping one of them under time pressure or because the task "looks simple." Being an implementation command is not a license to skip any gate.

1. GATE A — Grill before planning. When a grill skill is registered, you must invoke it (step 6) before forming a hypothesis or presenting options. Do not proceed to options without it.
2. GATE B — Full-context investigation before concluding. You must complete the investigation in step 5 (enumerate the project's real commands, trace the full code path, reproduce) before forming any conclusion. A conclusion drawn from a single file or a guessed command is invalid.
3. GATE C — Wait for the user's choice. After presenting options (step 8) you must stop and wait for the user to pick one. Do not continue to implementation on your own.
4. GATE D — Code review, then hand off (do not stop early). Whenever there is a code or test change to ship, you must run a code review via /review (step 16) and then invoke /create-pr (step 17). Finishing by only summarizing the change in chat, without running the review and opening the PR, is a failure of this skill.

Forbidden rationalizations — if you catch yourself writing any of these, you are violating the skill, stop and follow the gate instead:

• ❌ "Since /implement-issue is an implementation command, I'll proceed with option A." → No. The command requires you to wait for the choice. Implementation is what happens after the user picks.
• ❌ "The user said 'Agreed' / 'go ahead' / 'sounds good' before I ran grill and showed options." → No. That only counts as implementation approval if it comes after the required grill/options gate. To skip the gate entirely, the user must explicitly say something like: "skip the implement-issue gate and code directly."
• ❌ "The choice is obvious, so I'll skip the question." → No. Present options and wait. The user may know constraints you don't.
• ❌ "Grill isn't strictly necessary here." → No. If it's registered, run it.
• ❌ "I treated grill-with-docs as 'answer with doc-grounding' instead of actually running the grilling loop." → No. Invoking grill means executing the grill skill itself — its real, interactive question loop — not answering in a doc-grounded style, not paraphrasing what it would ask. Load the skill and run it.
• ❌ "I'll ask a couple of clarifying questions of my own; that's basically grilling." → No. That is not the grill skill. Run the actual grill-with-docs / grill-me skill.
• ❌ "I found the likely cause in this one file, no need to look further." → No. Complete the full-context investigation first.
• ❌ "The change looks complete, I'll summarize it here instead of opening a PR." → No. Run /review, then always invoke /create-pr (GATE D).
• ❌ "I already self-reviewed, so I'll skip the /review code review." → No. The /review pass is a separate, mandatory code review of the diff.

If you are a smaller / non-frontier model: treat steps 6, 5, and 8 as literal hard stops, and treat steps 16 and 17 as mandatory always-run endings. Run the tool, finish the checklist, ask the question, then wait — and at the end, run the review and open the PR.

Use the grill skill for thoroughness (always when available)

Before forming a hypothesis or presenting implementation options, the agent always invokes the grill skill when it is registered in this environment — not only when something is ambiguous. This is GATE A above. The grill output is folded into the implementation plan and validation step so the result is more thorough than the raw issue text would produce.

Invoking the grill skill means literally running that skill — not imitating its spirit. grill-with-docs and grill-me are separate skills with their own multi-question interrogation loop. To invoke one you read its SKILL.md and execute its procedure: actually ask the user the grilling questions it generates and wait for the answers, iterating until the loop completes. The following are NOT invoking it and are forbidden substitutes:

• Treating the mention of grill-with-docs as a style instruction — "answer with doc-grounding," "be thorough," "cite the docs" — and then proceeding. ❌
• Summarizing or paraphrasing the questions grilling would ask instead of asking them. ❌
• Asking one or two clarifying questions of your own and calling that grilling. ❌
• Skipping it because you believe you already understand the request. ❌

If you cannot run the grill skill, do not silently downgrade it to "doc-grounded answering" — say explicitly that no grill skill was found (see discovery hint) and proceed on the input as given.

• /grill-with-docs is preferred. Use /grill-me only when /grill-with-docs is not registered.
• Discovery hint: look for a skill or command named grill-with-docs or grill-me (e.g. ~/.cursor/skills/grill-with-docs/, ~/.cursor/skills/grill-me/, .cursor/skills/..., .agents/skills/...).
• If neither is registered, state explicitly that no grill skill was found, then proceed with the workflow on the input as given.

When this workflow invokes an external grill skill, treat it as a nested planning dependency: obey that skill's procedure exactly, do not implement product code during the grill sub-session unless that skill explicitly requires documentation/context updates, then return to this workflow and continue with validation and options.

Active context declaration

Do not declare the active context at invocation time. First fetch the issue, read project/area context, discover matching skills, investigate/reproduce the relevant behavior, and run the grill skill when available. Then, immediately before presenting implementation options, briefly state the context and skills that are now active, for example:

Active context before planning: AGENTS.md, project-area/AGENTS.md, project-area/CONTEXT.md, docs/adr/0003-..., react-stack, convex, grill-with-docs. No matching <domain> skill found.

This is a gate immediately before options: actively search for relevant project, stack, domain, and grill context before the declaration. If the declaration is missing any discovered context, load it before continuing. A context note before grill does not satisfy this gate; the active context must be restated with the implementation options.

Pre-edit approval checklist

Before any file edit or implementation command, run this checklist out loud in commentary:

Gate check: I have not edited files yet. I'm running the grill/options step first.

Then confirm all five items are true:

• Grill-with-docs / grill-me has run, or the user explicitly waived it.
• The project-context Definition of Ready search is complete, every discovered Definition of Ready has been read, and the selected path satisfies every applicable readiness item before any file edit.
• Exactly three implementation options were presented.
• One option was recommended.
• The user explicitly selected an option, or explicitly approved the recommendation, after seeing those options.

If any item is missing, stop. Ask for the missing grill step, Definition of Ready search/readiness resolution, options gate, recommendation, or post-options approval before editing. Generic approval language such as "Agreed", "go ahead", "sounds good", or equivalent does not satisfy this checklist unless it follows the three presented options. The only way to bypass this checklist before options is an explicit user instruction such as: "skip the implement-issue gate and code directly."

Steps

1. Parse the issue number. If missing or non-numeric, ask.

2. Fetch the issue with GraphQL first: title, body, state, labels, assignees, URL, comments, and whether the entity is actually a pull request.

3. Fall back to REST when GraphQL is unavailable:

   gh api "repos/$OWNER/$REPO/issues/$ISSUE_NUMBER"
   

4. Read the project's agent context before forming a hypothesis or editing. In this order:

   • The root AGENTS.md.
   • Agent-alias files (mandatory search). Search for CLAUDE.md and equivalent root agent aliases. Read each discovered alias and confirm whether it is a symlink/alias to AGENTS.md or contains additional instructions. Carry any additional instructions into the active context declaration.
   • The nearest <area>/AGENTS.md to the files the issue touches in a multi-area repo. Nested files override the root for that area.
   • Contribution rules (mandatory search). Search the root, nearest affected area, docs/, and any AGENTS.md-referenced context for CONTRIBUTING.md or equivalent contribution/review guidance. Read every match. Treat the nearest/most specific match as authoritative for what may be merged, and carry all matches into the active context declaration.
   • Project-context Definition files (mandatory search). Search the root, nearest affected area, docs/, and any AGENTS.md-referenced context for DEFINITION_OF_READY.md, DEFINITION_OF_DONE.md, and spelling/case variants such as Definition of Ready, Definition-of-Done, definition_of_ready, or defintion_of_done. Read every match. Treat the nearest/most specific match as authoritative for the affected area, and carry all matches into the active context declaration.
   • The repo's docs/ index (docs/README.md, docs/architecture.md, docs/code-style.md, or equivalent) for the area being changed. Do not skip this step even when the issue looks small — Hard Constraints sections (e.g. "Bun only, no npm/pnpm/yarn", "AI SDK via Vercel AI Gateway only") frequently change the implementation path.

   Discover and use implementation-specific skills and context (required). Before planning, check what specialized skills and context apply to the area being changed, and use them:

   • Registered skills. Look for skills that match the project's stack or domain (e.g. a stack skill like react-stack / native-nostalgia-stack, a conventions skill like convex-conventions, or any project-provided skill in .agents/skills/ ↔ .claude/skills/). When one matches the change, read it and follow it — its rules override generic defaults for that area.
   • In-repo context. Honor area-specific docs/ (e.g. docs/code-style.md, a feature MVP doc), .cursor/rules, and any AGENTS.md-referenced guides for the files you're touching.
   • If a clearly relevant skill or context exists, using it is not optional. Implementing without consulting an applicable stack/conventions skill is a shortcut (see step 15). If none applies, note that briefly and proceed.

5. Investigate the whole codebase before concluding (GATE B). Do not take shortcuts. A conclusion drawn from a single file or an assumed command is invalid. Before forming any hypothesis:

   • Enumerate the project's real commands instead of guessing. Read the manifest's script section (package.json scripts, Makefile / Justfile / Taskfile, pyproject.toml, Cargo.toml, etc.) and the docs/tooling.md / docs/quick-start.md equivalents. Use the commands the project actually defines (e.g. the project's check, test, lint, dev names) — never invent a command or assume a default that the repo hasn't declared.
   • Search broadly, not narrowly. Use codebase search and grep to find every site related to the issue: the symbol, its callers, its tests, sibling implementations, and config. Read the surrounding modules, not just the first match.
   • Trace the full code path from entrypoint to the reported symptom. Identify the actual layer where the behavior originates rather than patching the first place the symptom appears.
   • Reproduce the reported behavior against current code; do not trust the issue text alone. When the issue cites a reproduction command, test path, or external artifact (test262, Playwright run, etc.), fetch and run that exact artifact. The title is a pointer, not a spec.
   • If after a genuine investigation something is still unclear, that is a finding to raise in the options — not a reason to guess.

   If the reported behavior does NOT reproduce, the issue may already be fixed. Do not invent a change to justify the command. Determine which case applies and carry it into the options (step 8):

   • Case: already fixed AND already covered by a test. Find the commit/code that fixed it and the test that locks it in. The recommended outcome is to close the issue as already resolved (referencing the fixing commit and the covering test), not to write new code. Only add something if the user wants extra coverage.
   • Case: already fixed BUT not covered by a regression test. The behavior works but nothing prevents it from regressing. The work becomes adding a regression test (and any missing edge-case tests) that would fail against the pre-fix code and passes now — no production-code change. Name the test after the issue so the linkage is obvious.
   • Case: fixed for the reported path but adjacent paths are untested or still broken. Add tests for the sibling paths surfaced in the broad search above, and fix any that are genuinely broken. Treat each broken sibling as in-scope only if it shares the issue's root cause; otherwise note it for a separate issue.
   • In all three cases, confirm the "already fixed" conclusion with evidence (the passing reproduction, the responsible code, the existing or missing test) before presenting it — a behavior that merely looks fixed in one spot may still fail on another path.

6. Run the grill skill (GATE A). When grill-with-docs / grill-me is registered, read that skill and execute its actual question loop now on the issue plus your investigation findings — ask the questions, wait for answers, iterate to completion — then fold its output into the options and verification plan. Provide the grill skill with the project, stack, domain, docs, ADR, and investigation context discovered in steps 4–5. Do not substitute a "doc-grounded" answer or your own ad-hoc questions for the skill. Do not implement product code during the grill sub-session unless the grill skill explicitly requires documentation/context updates. If no grill skill is registered, say so explicitly and continue.

7. Validate before coding:

   • The issue exists, is open, and is not a pull request.
   • No blocked, duplicate, wontfix, or equivalent label/comment.
   • Expected behavior and acceptance criteria are clear enough to implement.
   • The project-context Definition of Ready search from step 4 is complete and documented in the active context. The issue, investigation findings, and selected implementation path satisfy every applicable Definition of Ready item before branching or editing. Any unmet readiness item is a hard stop: resolve it with the user before implementation.
   • Absence protocol: after the mandatory search finds no Definition of Ready, state that no project-context Definition of Ready was found and continue with the workflow's readiness checks.
   • If validation fails or requirements are ambiguous, stop and ask.

8. Declare active context, present implementation options, then STOP and wait (GATE C). Before listing options, state the active context/skills discovered and used in steps 4–6, including any applicable project, stack, domain, docs, ADR, and grill skills. If the declaration reveals a relevant missing skill or context file, load it before continuing. Then present exactly three distinct options with tradeoffs, a verification plan, and a recommendation grounded in the step 5 investigation and step 6 grill output. The three must be genuinely different approaches, not trivial variations of one. When step 5 found the issue already fixed, the options reflect that situation instead of inventing a code change — e.g. (a) close as already resolved citing the fixing commit and covering test, (b) add a regression test (plus missing edge-case tests) that would have caught the original bug, (c) extend coverage/fixes to the adjacent paths surfaced in the search. Do not write any implementation code until the user explicitly picks an option or explicitly tells you to proceed with the recommendation. Do not interpret "this is an implementation command" as permission to skip the choice. End your turn here and wait for the user's reply. If the chosen option is "close as already resolved" with no code or test change, skip steps 9–17: instead, comment on the issue with the evidence (fixing commit + covering test) and close it (or ask the user to). The remaining steps apply only when there is a code or test change to ship.

9. Branch / worktree:

   • Prefer reusing an existing focused branch or worktree for the issue.
   • If a branch exists without a worktree, use or create a worktree when that best isolates the work.
   • Otherwise create a focused branch named from the issue (e.g. issue-123-short-slug); use a worktree when practical.
   • Update the branch/worktree against the latest baseline before implementing. Run git fetch origin, then merge the remote default branch into the working branch (e.g. git merge origin/<default-branch> — never rebase, per the git-workflow skill). Resolve any conflicts and commit the merge before writing new code, so the work starts from the current origin main.

10. Implement the smallest complete change that satisfies the chosen approach.

11. Update tests and documentation per the contribution guidance discovered in step 4 (CONTRIBUTING.md, AGENTS.md, or equivalent). Absence protocol: after the mandatory search finds no contribution guidance, state that no project contribution guidance was found and follow the issue, Definition of Ready, Definition of Done, and local code patterns.

12. Run targeted verification first (focused tests, types, lint) on the changed area, then broader verification when the change has wider impact.

13. If the change is UI/UX, rendering and visual evidence are mandatory (do not skip). A UI/UX change handed off without screenshots of the actual rendered result is incomplete:

    • Run the app (or Storybook / component sandbox) and load every affected screen, component, and state — never assert the UI is correct without rendering it.
    • Capture before/after screenshots (or short recordings) of each affected screen and state, at the project's supported breakpoints and across light/dark/system themes when applicable.
    • Compare the captures against the design or the issue's expected state, and fix any discrepancy before handoff.
    • Verify accessibility: keyboard navigation and focus order, visible focus styles, ARIA roles/labels for new interactive elements, color contrast meeting WCAG AA (or the project's standard), and prefers-reduced-motion respected for animations.
    • Reuse existing design-system components and tokens; do not introduce one-off styles for primitives that already exist.
    • Attach the screenshots/recordings and accessibility notes to the PR — this is mandatory, not optional. The PR must be fully reviewable from these artifacts alone, without re-running the app, so the change can be judged asynchronously. A UI/UX PR missing this visual evidence is not ready for /create-pr.

14. Run the project's full verification gate before invoking /create-pr. Use the project's aggregator script discovered while enumerating real commands (e.g. bun run check) — that's the canonical "ready to commit" signal. Absence protocol: after command enumeration finds no aggregator script, run the per-step gate explicitly:

    bun install --frozen-lockfile
    bun run format:check   # or biome check
    bun run lint           # or biome lint .
    bun test
    bun run typecheck      # or tsc --noEmit / bunx tsc --noEmit
    bun run build
    

    Do not skip steps because they "should pass." If any step fails, fix the cause; do not invoke /create-pr with a red gate.

15. Review the implementation before handoff (do not skip). After the gate is green but before /create-pr, audit your own change critically — as a reviewer who did not write it would:

    • Check against the spec, criterion by criterion. Walk each acceptance criterion in the issue (and any scope confirmed across later turns/grill) and confirm the change actually satisfies it, citing the code or test that does so. Anything unmet is unfinished work, not a follow-up. When the scope was deliberately changed, match that updated intent instead — and note the divergence from the original issue text in the PR description so reviewers understand why.
    • Check the Definition of Done. Re-read every project-context Definition of Done discovered in step 4 before handoff. Verify the implementation, tests, documentation, review evidence, and handoff artifacts satisfy every applicable item. Any unmet completion item is a hard stop: fix it before /review or /create-pr, or stop and get explicit user agreement that the item is out of scope. Absence protocol: after the mandatory search found no Definition of Done, state that no project-context Definition of Done was found.
    • No shortcuts. No stubbed logic, hardcoded values standing in for real behavior, TODO/FIXME left behind, swallowed errors, skipped/.only/commented-out tests, or "happy path only" handling of cases the issue requires. Re-trace the full code path from step 5 and confirm the real layer was fixed, not just the symptom.
    • No tech debt introduced. No dead code, no duplication that should be extracted, no copy-paste of an existing pattern that has a shared helper, no weakened types (any, unsafe casts) or loosened lint/type rules to make the gate pass, no leftover debug output.
    • Consistency. The change follows the repo's conventions (from step 4 agent context and docs/code-style.md) and reuses existing components/utilities rather than reinventing them.
    • If this review surfaces a problem, fix it and re-run the relevant verification (step 12/14) before proceeding. Do not defer found issues to "a follow-up" unless the user explicitly agrees.

16. Run a code review before handoff (GATE D, do not skip). Invoke the /review skill/command on the change (the branch diff) and address its findings before opening the PR. This is a separate, fresh review of the diff — distinct from your own step-15 self-review.

    • Discovery hint: look for a skill or command named review / code-review (e.g. ~/.cursor/skills/review/, .cursor/skills/..., .agents/skills/...). Run the actual skill; do not substitute a self-summary for it.
    • Fix every issue it surfaces and re-run the relevant verification (step 12/14) before proceeding. Do not defer findings to "a follow-up" unless the user explicitly agrees.
    • If no /review skill is registered, say so explicitly, then perform a thorough manual diff review covering correctness, security, error handling, tests, and style.

17. Hand off via /create-pr (GATE D, mandatory). Always invoke /create-pr to commit, push, and open the draft pull request — this is the required end of the workflow whenever there is a code or test change to ship. The commit created during this handoff must use a Conventional Commit subject (type(scope): summary). Do not end the turn by only summarizing the change in chat; the opened PR is the deliverable. Include Closes #<issue> in the PR body.