koroqe/claude-code-sdlc/implement-slice

Command: Implement Slice

Implement only the next smallest slice from the plan using TDD.

Arguments

$slice (also available as $ARGUMENTS) optionally names the slice to implement. When empty, take the next pending slice from .claude/scratchpad.md.

Literal-token flag rule: a documented flag is active ONLY if its literal token appears in $ARGUMENTS. In particular, the no-changelog suppression flag is in effect ONLY when the literal token no-changelog was passed. Never infer it from context, and never assume it because the documentation describes it.

Pre-flight Checks

1. Confirm you are NOT on main — must be on a feature branch (feat/* or fix/*)
2. Confirm git status is clean (or explain why not)
3. Parallel subagent mode: when running as a subagent within a parallel wave (wave context provided in spawn prompt), the following rules apply for the entire execution:

• Do NOT write to .claude/scratchpad.md — the orchestrator handles scratchpad updates
• Do NOT write to .claude/instincts.md — it is PROTECTED identically to the scratchpad (Section 8 FR-7.2). Track deviation-rule tallies and the build-runner attempts counter in-context instead, and report them to the orchestrator for it to persist (see Step 6, Capture Instincts)
• Do NOT auto-continue to the next slice — return to the orchestrator after committing
• Chain git commands: git add <files> && git commit -m '...' as a single Bash command to prevent staging conflicts with sibling subagents

1. Tier-aware documentation check: confirm these documentation files exist — **skipped entirely

when .claude/scratchpad.md reads ## Tier: quick**, since neither file is ever required for a quick-tier change, by design (FR-4.4). This check runs unmodified — exactly as written below — when ## Tier: reads full or the field is absent: absence means full is the backward-compatibility default for every scratchpad written before this tier field existed, so an absent field is never read as license to skip this check.

• docs/qa/<feature>_test_cases.md — if not, delegate to qa-planner first
• docs/use-cases/<feature>_use_cases.md — if not, delegate to ba-analyst first

1. Tracer gate: read the plan file and check whether any slice is marked **Tracer:** yes.

• If a `Tracer: yes` slice exists and this invocation targets a different (non-tracer) slice, AND the tracer slice's Verify: condition has not yet been run and passed: REFUSE. Do not proceed to Step 1 (Identify the Slice) or any TDD work. State plainly that the tracer slice must be implemented and its Verify: condition passed first, name the tracer slice, and instruct the caller to run /implement-slice against the tracer slice before retrying this one. This check exists because standalone invocation of this skill bypasses /develop-feature's wave sequencing entirely — wave ordering alone cannot gate a direct, out-of-band /implement-slice call.

Source of truth for "the tracer passed": the tracer slice's DONE record with a commit hash in .claude/scratchpad.md, or a fresh run of the tracer's own Verify: command. If neither is available, or the record is ambiguous, REFUSE — an unverifiable tracer is an unpassed tracer.

• If this invocation targets the tracer slice itself: proceed normally — the tracer is exempt from its own gate.
• Exemption (backward compatibility), tier-aware wording (FR-4.5, AC-27): if the plan carries no **Tracer:** yes marker anywhere, this check does not apply. Print the tier-appropriate line verbatim, then continue with the remaining pre-flight checks and TDD flow as normal — the exemption is never silent:
• When `.claude/scratchpad.md` reads `## Tier: quick`: a marker-free plan here is quick tier's own single-slice plan, exempt from the tracer requirement by design — never a legacy plan. Print exactly:

tracer gate inactive — tier: quick, single-slice plan is exempt from the tracer requirement by design.

• When `## Tier:` reads `full`, or the field is absent (the pre-F4 legacy case): print the existing legacy wording, unchanged:

tracer gate inactive — no **Tracer:** yes marker found; treating as pre-F3 plan.

TDD Implementation Flow

1. Identify the Slice

Read the current slice from the implementation plan. Two formats are supported:

Executable format (preferred — when the slice has Files:, Changes:, Verify:, Done when: fields):

• Use the Files: list directly — these are the exact files to create/modify
• Use the Changes: descriptions as implementation guidance
• Use the Verify: commands in step 4
• Use the Done when: condition to confirm completion
• List the use-case scenarios this slice covers (from Use cases: field)
• Re-read each file from the Files: list before modifying

Legacy format (fallback — when the slice is prose without structured fields):

• Restate the next slice in 1 sentence
• List the use-case scenarios this slice covers (UC-X.Y, UC-X-A, etc.)
• Read existing files that will be modified

2. Write Tests First

Quick-tier carve-out (FR-4.4, AC-26): when .claude/scratchpad.md reads ## Tier: quick, state the following verbatim in the delegation prompt, before the request itself: "no docs/qa/<feature>_test_cases.md file exists for this change by design and MUST NOT be treated as a missing input." test-writer derives its tests from the slice's own Verify:/Done when: fields instead. This carve-out lives in the delegation prompt only — agents/test-writer.md itself is never modified by this instruction.

Delegate to test-writer agent:

• Reference documented test cases from docs/qa/ (for a quick-tier run, this reference is replaced

by the carve-out above, since no such file exists by design)

• Reference use-case scenarios from docs/use-cases/ for this slice (for a quick-tier run, use the

slice's own Use cases: field if present, since no use-cases file exists by design)

• Write tests for this slice's behavior using the project's test framework
• Run them and capture the RED result before writing any implementation. test-writer reports

the command, the exit status and which assertions failed, per its Output Format. This run is the point of TDD here: a test never observed to fail is not evidence that the change did anything (measured: docs/findings/harness-optimization-research.md §3).

• **If the tests pass on that first run, that is a legitimate outcome — but it must be declared,

never silent.** Two honest cases: the behaviour already exists and the slice characterizes it, or the test does not reach the new path and is therefore wrong. Say which. The forbidden state is a green suite whose greenness nobody can account for.

3. Implement Code

• Do not start until Step 2's red-phase result is in hand (a failing run, or a declared reason

the tests passed). Implementing first and testing after produces a green suite that cannot distinguish "fixed it" from "never tested it".

• Before editing each file: re-read it from disk (do NOT rely on earlier in-context reads — context compaction may have made them stale)
• Make minimal changes to pass the tests
• Follow the project structure as defined in CLAUDE.md
• Keep route handlers thin, business logic in services/data layer
• If this slice edits 4+ files: run the project's typecheck command after every 3 file edits before continuing (per error-recovery rules)
• When a slice touches UI files: read .claude/rules/design.md and extend its declared tokens — introduce no color, font, or duration value not declared there

4. Verify

If the slice has a `Verify:` field: run the exact command(s) from that field first. Then delegate to build-runner for full verification (typecheck, tests, build).

If the slice has a `Done when:` field: after verification passes, confirm the done-condition is satisfied (e.g., run the grep, check the endpoint, verify the file exists). If the done-condition is not met, the slice is not complete — investigate and fix.

If the slice has a `Verify:` field with "Manual verification:": report the check instructions in the output so the developer can verify manually.

Fallback (no structured fields): delegate to build-runner agent to run the project's typecheck, test, and build commands (from CLAUDE.md).

Persisted red-phase record. Alongside the attempts counter below, write one line per slice into .claude/scratchpad.md via `Edit`, never a whole-file `Write`:

Slice <N> red-phase: <command> → FAILED (<n> assertions) | NONE — <declared reason>

Same discipline as the attempts counter: it is the durable half of a fact that otherwise lives only in a subagent's reply and dies with its context. On the wave-subagent path .claude/scratchpad.md is PROTECTED, so the subagent reports the red-phase line and the orchestrator writes it when folding the wave, exactly as it already does for (category, count) deviation pairs.

Persisted build-runner attempts counter and `debugger` auto-invocation (FR-8.5, C8/FR-8.10). The 3-retry budget src/rules/error-recovery.md already governs is not tracked in conversation memory alone here either — mirroring /merge-ready's Gate 6 attempts: N/3 precedent exactly:

• Standalone path (no wave context): after every build-runner invocation for this slice (the initial run and each retry), write Slice <N> build-runner attempts: N/3 under the feature's current status in .claude/scratchpad.md via `Edit`, never a whole-file `Write`. Before deciding whether to retry, read this line back from the file — never rely on what you recall having written earlier in the conversation. When the counter reaches `2/3` with build-runner still FAILing, self-invoke the debugger agent — feeding it the prior failure output(s) and the feature slug — BEFORE the 3rd (final) retry attempt. Apply debugger's recommended fix under whichever deviation rule it names; if debugger returns UNDIAGNOSED, the final attempt proceeds exactly as it would have without this feature.
• Wave-subagent path (wave context provided): .claude/scratchpad.md is PROTECTED — do NOT write it. Track Slice <N> build-runner attempts: N/3 in-context for the duration of this slice instead, self-invoke debugger at 2/3 identically to the standalone path, and report the final attempts count to the orchestrator (Step 6, Capture Instincts) for it to persist.
• C8/FR-8.10 inline fallback: both paths above assume debugger can be reached via the Agent tool. If nested agent spawn is unavailable in the running context, do NOT skip the diagnostic pass — run debugger's bounded scientific-method protocol (agents/debugger.md Process: up to 5 falsifiable hypothesis cycles) inline, in this same context, instead of spawning it. The UNDIAGNOSED verdict and the final-attempt escalation path are unchanged either way. A diagnosis that cannot run degrades to a slower, inline diagnosis — never to silence.

5. Commit

• git add specific changed files (not git add -A)
• git commit -m "<type>(<scope>): <slice summary>"
• Types: feat, fix, test, chore
• Scopes: api | ui | db | auth | core | infra

6. Capture Instincts

This step runs after the commit step (5), occupying the same post-commit position pattern the changelog step (7, below) occupies. Unlike the changelog step, it is never suppressed by the no-changelog flag — that flag governs only CHANGELOG.md; the instinct store has its own, separate gating (the wave-subagent carve-out below).