# Implement Issue

> Load this skill when the user says "implement issue", "implement-issue", or "/implement-issue". Implements a GitHub story issue end-to-end: prepares base branch, creates feature branch, implements the requirements, verifies via the verify-implementation skill, and opens a PR.

- Skill: `dawidvanzyl/implement-issue` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dawidvanzyl/implement-issue`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dawidvanzyl/implement-issue/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: dawidvanzyl (https://skillmd.com/u/dawidvanzyl)
- Updated: 2026-08-19
- Page: https://skillmd.com/skills/dawidvanzyl/implement-issue

---


## Announcement

At the start of execution, always post a visible message to the user:

> "Loaded skill: **implement-issue**. Starting workflow..."

## Inputs

Use this skill when the user provides:

- `issue_number` (story/sub-issue), e.g. `48`
- `parent_issue_number` (epic/parent), e.g. `45`

Optional but recommended:

- Repository owner/name if not inferable from git remote.

## Goal

Execute the full story workflow for a GitHub issue:
1) prepare the base branch via the prepare-base skill,
2) read and orient from the issue,
3) check dependencies are unblocked,
4) create a correctly named feature branch from the base branch,
5) implement the requirements,
6) verify implementation via the verify-implementation skill,
7) open a PR targeting the base branch.

## Procedure

### 0) Gather inputs

Before doing anything else:

- If `issue_number` was not provided, ask: "What is the issue number to implement?"
- If `parent_issue_number` was not provided, ask: "What is the parent epic issue number?"
- Do not proceed until both values are confirmed.

### 0.5) Prepare base branch

- Invoke the `prepare-base` skill.
- Allow `prepare-base` to ask for and checkout the base branch independently.
- Do not pass or assume a base branch — let the user confirm it within `prepare-base`.
- After `prepare-base` completes, `origin/{base_branch}` has been fetched and
  is current. The current local branch may or may not be `base_branch` itself
  (if another worktree already had it checked out, `prepare-base` will have
  stayed on the prior branch and relied on the fetched remote ref instead —
  this is expected and does not block the next step).

### 1) Read and orient

Read issue `#{issue_number}` fully. The issue follows the structure defined
in `.github/ISSUE_TEMPLATE/sub-issue.md`.

Ignore completely:

- `## Post-Implementation Summary`

Extract and internalize the following before writing any code:

- `issue_title`
- `milestone_title` — from the issue's assigned GitHub milestone, if any.
  Used only for the PR `--milestone` flag in step 6; omit that flag entirely
  if the issue has no milestone assigned (expected for `[Bug]` and
  `[Tech Debt]` issues).
- IT codes — from `## Epic Reference > Acceptance Criteria Covered` (e.g. `48IT1`)
- UC codes — from `## Acceptance Criteria (G/W/T)` (e.g. `48UC1`)
- **Constraints** — read `## Context & Constraints` in full. Note every
  pattern, convention, and restriction listed. These are non-negotiable during
  implementation; do not deviate without raising it with the user first.
- **Functional requirements** — read `## Functional Requirements`. These are
  the observable behaviours the implementation must deliver. Use them as the
  primary implementation checklist.
- **Domain & Data** — read `## Domain & Data`. Understand the entities, their
  relevant fields, and the business rules before touching any domain code.
- **API / Interface Contract** — read `## API / Interface Contract`. The
  endpoint signatures, payloads, and error cases described here are the agreed
  contract. Do not alter them during implementation.
- **Out of Scope** — read `## Out of Scope`. This is a hard implementation
  boundary alongside Functional Requirements; do not implement anything listed
  here.
- **Notes** — read `## Notes` last, if present. This section contains edge
  cases, security considerations, and deliberate deferrals that must not be
  missed or overridden.
- `docs/coding-standards.md` — git, commit, and PR conventions.
- `docs/coding-standards-backend.md` — if any backend scope is detected in
  the issue labels or content.
- `docs/coding-standards-frontend.md` — if any frontend scope is detected in
  the issue labels or content.
- `src/.editorconfig` — if backend scope.
- `frontend/.editorconfig` — if frontend scope.

If any requirement is ambiguous or two sections appear to conflict, ask a
clarifying question before coding. Do not resolve ambiguity by assumption.

### 1.5) Dependency gate (HARD STOP)

Check `## Context & Constraints` for any `Related issues: Depends on #X` (or similarly phrased blocking references).

For every such dependency, check the issue's status.

If ANY blocked issue is not closed:

- Stop immediately.
- Output: "Blocked dependency detected: #X is not closed. Implementation cannot proceed."
- Do not load standards, create a branch, write code, or run verification.

### 2) Orient in the codebase

Before writing any code, explore the existing codebase to understand how to
map the issue's requirements to actual files and structure:

- Locate the layer boundaries described in `## Context & Constraints` — find
  the existing directories and files that correspond to each layer.
- Identify the patterns to follow (service classes, middleware, naming
  conventions) by reading 2–3 representative existing files in the relevant
  areas.
- For stories with `layer: frontend`: read `## Page Architecture` and identify
  existing component patterns the new screens should follow.
- If the codebase structure is unclear or no analogous code exists, state your
  understanding to the user and ask for confirmation before proceeding.

The goal of this step is to arrive at a clear mental map of where each
requirement will land, without having written a single line yet.

### 3) Create feature branch

- Determine the branch prefix from the issue's labels: `type: feature` →
  `feature/`, `type: bug` → `bug/`, `type: tech-debt` → `tech-debt/`.
- Create branch `{prefix}/{issue_number}-{slug}` from `origin/{base_branch}`
  (`git checkout -b {prefix}/{issue_number}-{slug} origin/{base_branch}`),
  never from current HEAD — this keeps the branch point correct even when
  another worktree's local copy of `base_branch` is stale or the branch
  wasn't checked out locally in step 0.5. Slug per the rule in
  `docs/coding-standards.md` (kebab-case, derived from the issue title, max 5
  words). No milestone number in the branch name.

### 4) Implement

- Implement all functional requirements from `## Functional Requirements`,
  honouring the constraints from `## Context & Constraints`, the boundaries
  from `## Out of Scope`, and the contracts from `## API / Interface Contract`.
- For each UC code: write the corresponding test — one test per UC, named to
  reflect the G/W/T behaviour it verifies.
  - Backend UC codes: xUnit tests tagged `[Trait("AC", "{code}")]` using the
    exact code as it appears in the issue body (e.g. `[Trait("AC", "48UC1")]`).
  - Frontend UC codes: vitest service tests (mock fetch, no DOM) in
    `frontend/src/services/__tests__/`. Install vitest if not present
    (`npm install -D vitest`). Register any new tag in `frontend/vitest.config.ts`'s
    `tags` array (name + description), same as every existing tag.
- For each IT code: write an xUnit integration test tagged
  `[Trait("AC", "{code}")]` using the exact code as it appears in the issue
  body (e.g. `[Trait("AC", "45IT1")]`) — IT codes carry the **epic's** issue
  number, already resolved in the text; do not recompute it.
- If `## Acceptance Criteria (G/W/T)` has no entries, no unit/frontend tests are required for this story. IT code coverage from `## Epic Reference > Acceptance Criteria Covered` is independent of this and still applies if present.
- Update `README.md` if behaviour, setup, usage, or documentation are affected.
- Build: `dotnet build src/PanoramaMusic.slnx`
- Format check: `dotnet format src/PanoramaMusic.slnx --verify-no-changes`
- Test: `dotnet test src/PanoramaMusic.Tests`
- Run frontend checks (lint, typecheck, vitest) if story has frontend scope.
- Fix all failures before proceeding.

### 5) Verify implementation (gauntlet loop)

Commit your work before verifying. Then run up to **3** verify cycles.

For each cycle, invoke `verify-implementation` in a sub-agent, passing:

- `issue_number`
- `base_branch`
- `mode: subagent`
- `cycle` — 1, 2, or 3
- `prev_verify_sha` — the `VERIFIED_SHA` from the previous cycle (omit on
  cycle 1)
- `prev_report` — the previous cycle's report (omit on cycle 1)

Act on the verdict:

- **`PASS`** — proceed to step 6. Warnings are advisory; address any you agree
  with, or leave them.
- **`BLOCKED (n)`** — for each blocker, either fix it and commit, or mark it
  invalid with a reason. Carry both into the next cycle's `prev_report` — fixed
  items so verify can confirm them, invalid items annotated
  `INVALID: {reason}` so verify can adjudicate. Do not mark an item invalid to
  avoid work; the reason must cite the issue, the codebase, or a standards doc.
- **`NEEDS_HUMAN (n)`** — stop. Present the open questions and disputed
  findings to the developer. Once the developer rules, record the decision as
  `RESOLVED_BY: developer` in `prev_report`, apply any required fix, and resume
  the loop. Settled items are never re-raised.

If cycle 3 does not return `PASS`, stop and hand the outstanding report to the
developer. Do not proceed to step 6.

### 6) Open PR

- Ask: "Are you ready to post a pull request?"
- If yes: proceed with commit, push, and PR creation.
- If no: stop and wait.
- Commit and format the PR following conventions in `docs/coding-standards.md`.
- Push feature branch.
- Use `milestone_title` extracted in step 1, if any.
- Create PR using `gh pr create` with:
  - `--base base_branch`
  - `--title "{issue_title} (#{issue_number})"`
  - `--milestone "{milestone_title}"` — **omit this flag entirely** if the
    issue has no milestone assigned (expected for `[Bug]`/`[Tech Debt]`
    issues). Never invent a milestone.
  - `--body` including:
    - brief overview of what changed
    - `Closes #{issue_number}`
    - milestone name as a readable line, if one is assigned
- Do not rely on post-creation edits — set milestone and issue reference at
  creation time.

## Guardrails

- Never proceed if dependencies are blocked.
- Do not use force push or destructive git history commands unless explicitly
  requested.
- Do not amend commits unless explicitly requested.
- Preserve unrelated local changes in working tree.
- Do not deviate from patterns or constraints listed in `## Context &
  Constraints` without raising it with the user first.
- Never implement outside `## Functional Requirements` / `## Out of Scope`.
- Never assume missing information.
- The verify loop is capped at 3 cycles. `implement-issue` owns the count;
  `verify-implementation` is stateless.
- Never dismiss a verify blocker silently. Fix it, or mark it invalid with a
  cited reason and let verify adjudicate.
- Keep communication concise and actionable.