Mp Implement Issue

Matt Pocock — Single Issue Implementation

Pick up ONE AFK-labeled issue and drive it to a merged PR. Lighter than /mp-implement (no decomposition phase) — assumes the slice already exists.

Input

The user invokes with:

• An issue reference (#42, GitHub URL, GitLab URL, or .scratch//.md for local-markdown trackers)
• Or no argument → query the configured tracker for the oldest unblocked ready-for-agent issue and ask the user to confirm before starting.

Persistence

Drive until the issue is merged (or hits a HITL checkpoint below). Do not stop after each step.

Process

1. Read the slice fully

Fetch the issue body, all comments, prior triage notes, and the agent brief (per docs/agents/issue-tracker.md). Read the parent PRD referenced in the "Parent" section.

If docs/agents/triage-labels.md indicates the issue is NOT ready-for-agent, stop and tell the user — refuse to pick it up without explicit override.

2. Verify context

Read CONTEXT.md (or CONTEXT-MAP.md → relevant per-context file) and any ADRs in the area. Note any constraint that affects your approach. Use this vocabulary throughout. If you're unfamiliar with this code area, map the relevant modules and callers using the domain glossary first — context matters more than speed.

3. Worktree + branch + clean baseline

Apply /using-git-worktrees: detect existing isolation, then set up an isolated worktree (or work in place if the user declines or the harness already isolates). Inside it, create a feature branch named after the slice title (kebab-case).

/using-git-worktrees also auto-runs project setup and verifies a clean test baseline — never start from a broken baseline. If tests fail on the clean checkout, stop and report before writing any code.

4. Prototype if a key question is open

If a state-model, data-model, or UI question is genuinely unresolved after reading the slice + PRD + CONTEXT, apply /prototype discipline: build the throwaway, answer the question, fold the decision back. Capture the answer in the slice (as a comment) or in an ADR if it meets the three criteria.

5. TDD loop (red-green)

For each acceptance criterion:

RED:   write one test for one behavior, watch it fail
GREEN: minimal impl, watch it pass
       (commit if behavior is non-trivial)

Repeat. NEVER write multiple tests up front. Each test responds to what the previous cycle taught you.

Tests verify behavior through public interfaces and behaviors, never internals — and only at seams pre-agreed in the slice/PRD acceptance criteria. If the slice declares no testable seam, that is a HITL checkpoint (see the list below) — don't invent one silently. If a test breaks during a refactor that didn't change behavior, the test was wrong — fix the test, not just the code.

Expected values must come from an independent source of truth — a known-good literal, a worked example, or the acceptance criteria themselves — never recomputed the way the code under test computes them (tautological tests pass by construction).

Mock only at system boundaries (external APIs, time, randomness); never mock your own modules or internal collaborators.

Pacing: in the loop, run the current test file + typecheck; the full suite runs once at the verification gate (step 7).

Don't refactor while red — refactoring is not part of the loop; it belongs to the review stage (step 8).

Identify deep-module opportunities while implementing (vocabulary per /codebase-design, the single source):

• Is this interface earning its keep? (deletion test: if you removed it, would complexity disappear or reappear in N callers?)
• Is there a hidden invariant the interface should encode?
• One adapter means a hypothetical seam; two adapters mean a real one — don't introduce a seam unless something actually varies across it.

6. Bug-during-implementation: apply /diagnosing-bugs

If a test fails for non-obvious reasons or behavior is wrong:

1. Build a feedback loop (THE skill — failing test, curl script, headless browser, replay harness — whichever reaches the bug fastest). Spend disproportionate effort here. Done when you can name ONE command — red-capable (goes red on this bug), deterministic, fast, agent-runnable — that you have actually run.
2. Reproduce reliably, then minimise: cut inputs, callers, config, and steps one at a time down to the smallest scenario that still goes red — the minimisation byproduct becomes the regression test. For non-deterministic bugs, raise the reproduction rate (loop 100×, parallelise, add stress, narrow timing) instead of theorizing.
3. Generate 3-5 ranked falsifiable hypotheses. State each as "if X is the cause, then changing Y will make the bug disappear."
4. Instrument with [DEBUG-] tagged probes. Change one variable at a time.
5. Fix at a correct seam. Regression test BEFORE the fix. If no correct seam exists for the fix, that itself is the finding — take the architectural branch below.
6. Cleanup: remove DEBUG logs (single grep on the tag). Ask "what would have prevented this?" — if architectural (tangled callers, a missing seam, hidden coupling), note it (do not refactor here; queue for parent /mp-implement Phase 4 or for an /improve-codebase-architecture pass).

7. Self-review + verification gate

Apply /verification-before-completion: each box below must be confirmed against fresh command output produced in this step — not "should pass", not a stale run. If you have not run the command in this step, you cannot check its box.

• All acceptance criteria checked off — line-by-line against the slice
• All tests pass — run the project's existing suite, your new tests, lint, and typecheck now, and read the output (0 failures)
• No [DEBUG-*] traces remain — single grep on the tag
• Branch name + commit messages + PR title all use CONTEXT.md vocabulary
• The PR description references the parent PRD and lists which acceptance criteria are met

8. Code review (two axes, parallel subagents)

Before opening the PR, get an independent review — do not rely on self-review alone. Mirrors upstream /code-review: two parallel reviewer subagents on separate axes, aggregated side by side.

1. Fail-fast fixed point (per /requesting-code-review): capture BASE_SHA (the slice's branch point) and HEAD_SHA; git rev-parse the fixed point to confirm it resolves, and confirm the three-dot diff git diff BASE_SHA...HEAD is non-empty — fail here, not inside a subagent.
2. Dispatch TWO reviewer subagents in parallel (one message, two Agent calls):

• Standards axis — give it: the diff command + commit list (git log BASE_SHA..HEAD --oneline); the repo's documented standards (e.g. CODING_STANDARDS.md, CONTRIBUTING.md); and the smell baseline below, inlined (the subagent has no other access to it). Brief: per file/hunk, (a) every violation of a documented standard — cite the standard (file + rule); (b) any baseline smell — name it and quote the hunk. Duplication and shallow modules noticed while green belong to this axis. Under 400 words.
• Spec axis — give it: the diff command + commit list; the slice issue body with acceptance criteria verbatim. Brief: report (a) missing or partial implementations, (b) scope creep, (c) implemented-but-wrong — quoting the spec line for each finding. Under 400 words.

1. Aggregate in two columns — ## Standards and ## Spec. Never merge or rerank findings across axes: a change can pass one axis and fail the other.
2. Apply /receiving-code-review to the result: evaluate each finding technically, not performatively. Fix every Critical and Important issue before proceeding; Minor → PR description or follow-up slice. Push back with technical reasoning and evidence when the reviewer is wrong.
3. After applying fixes, re-run the step 7 verification gate.

Smell baseline (compressed Fowler, Refactoring ch.3) — inlined for the Standards subagent. Two binding rules: a documented repo standard always overrides the baseline; every smell is a judgement call, never a hard violation — skip anything tooling already enforces.

• Mysterious Name — name doesn't reveal what it does or holds → rename
• Duplicated Code — same logic shape in more than one hunk or file → extract the shared shape
• Feature Envy — reaches into another object's data more than its own → move the method onto the data
• Data Clumps — same few fields/params keep travelling together → bundle into one type
• Primitive Obsession — primitive standing in for a domain concept → give it a small type
• Repeated Switches — same switch/if-cascade on the same type recurs → polymorphism, or one shared map
• Shotgun Surgery — one logical change forces scattered edits → gather into one module
• Divergent Change — one module edited for several unrelated reasons → split so each changes for one reason
• Speculative Generality — abstraction for needs the spec doesn't have → delete; inline back
• Message Chains — long a.b().c().d() navigation → hide the walk behind one method
• Middle Man — mostly delegates onward → cut it; call the real target direct
• Refused Bequest — ignores or overrides most of what it inherits → drop inheritance, use composition

9. Open PR + comment

Open the PR. Comment on the issue with a link. Move the issue to whatever status docs/agents/issue-tracker.md defines as "done by agent, awaiting human review" — do NOT close it (that's the maintainer's call).

10. Report

Tell the user:

• PR link
• Slice → PR mapping
• Any deferred items (architectural smells noted but not fixed, ADRs proposed, follow-up slices needed)
• Suggested next issue (next unblocked AFK in the same PRD's dependency chain)

HITL checkpoints inside this skill

Pause and ask only when:

• The issue isn't ready-for-agent (refuse without override).
• A new public interface is needed that downstream slices will depend on.
• The slice/PRD declares no testable seam to write tests against.
• A test that should pass fails for non-obvious reasons after 2+ honest fix attempts.
• The slice contradicts an existing ADR.
• The slice's acceptance criteria are ambiguous and you cannot resolve from PRD + CONTEXT + ADRs.

Otherwise: drive forward.

Composition

This skill is a tighter loop than /mp-implement (no Phase 0/1/2). It composes:

• using-git-worktrees — isolated workspace (step 3)
• prototype (when a question is open)
• tdd — the red-green engine, at pre-agreed seams (step 5)
• diagnosing-bugs (when stuck on a bug, step 6)
• verification-before-completion — honesty gate (step 7)
• requesting-code-review + receiving-code-review — independent review (step 8)

The review step mirrors upstream's two-axis code-review (parallel Standards + Spec subagents, Fowler smell baseline inlined); receiving-code-review stays the action layer on its findings. Deep-module vocabulary (module, interface, seam, adapter, depth) now lives in /codebase-design — the single source; this file only applies it.

Use them as deep modules — follow each skill's full discipline.

Terminology: local PRD/slices ≈ upstream spec/tickets. This skill is the AFK-enhanced counterpart of upstream's 15-line implement — it adds worktree isolation, a fresh-output verification gate, and independent two-axis review, which upstream deliberately leaves out.

Note: the two-stage subagent review engine (subagent-driven-development) belongs to the multi-slice /mp-implement Phase 3, not here — this single-issue loop runs one consolidated two-axis review stage. /mp-implement-issue can itself be dispatched as an implementer subagent by that engine.

When to use which

• /mp-implement — starting from a fresh PRD/design. Runs decomposition first.
• /mp-implement-issue — picking up a single pre-decomposed slice.
• Want to drive multiple issues in parallel? Use /mp-implement-issue for each in a separate worktree — /using-git-worktrees (step 3) sets up each one.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: skywalkercyt
• Source: skywalkercyt/mp-implement
• License: MIT

Install and usage instructions live in the source repository linked above.