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.