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 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
4. Confirm these documentation files exist:
   • 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
5. 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): if the plan carries no **Tracer:** yes marker anywhere, this check does not apply. Print this line verbatim, then continue with the remaining pre-flight checks and TDD flow as normal — the exemption is never silent:

     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

Delegate to test-writer agent:

• Reference documented test cases from docs/qa/
• Reference use-case scenarios from docs/use-cases/ for this slice
• Write tests for this slice's behavior using the project's test framework
• Tests should FAIL initially (no implementation yet)

3. Implement Code

• 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)

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).

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. Write Changelog Entry

This step runs only after a successful commit (step 5). It is the standalone-fix path: when a slice is committed outside the full pipeline, the changelog still needs an entry.

Skip this step entirely when EITHER skip condition is true:

• (a) Parallel-wave subagent — wave context was provided in the spawn prompt. The orchestrator / merge-ready owns the changelog entry for the wave.
• (b) no-changelog suppression flag — a no-changelog flag was passed (i.e. this run is driven by /develop-feature). merge-ready owns the entry for the whole feature.

If either condition holds, do NOTHING here — merge-ready writes the single consolidated entry.

When BOTH skip conditions are false (true standalone fix), write ONE entry to the project-root CHANGELOG.md following the changelog rule (changelog.md):

• Retrieve the real timestamp by running date -u +'%Y-%m-%d %H:%M' — NEVER invent or guess the timestamp.
• Fields: name, UTC time, a non-technical Summary, and Details (≤500 characters).
• Entries are day-grouped, newest-first.
• Idempotency guard: if an existing entry with the same name already exists under today's date, UPDATE that entry in place — do NOT duplicate it.

7. Update Scratchpad

Skip this step when running as a parallel subagent (wave context provided in spawn prompt). The orchestrator handles scratchpad updates after collecting all wave results.

When running standalone (no wave context), update .claude/scratchpad.md with:

• What changed
• Commit hash + message
• Use cases covered by this slice
• What's next (next slice)

Rules

• Minimal diff — change only what's necessary for this slice
• 1 slice = 1 commit (atomic)
• No refactors unless required for this slice
• NEVER add "Co-Authored-By" or AI attribution to commits

Output Format

## Slice: [description]
### Wave: [N — slice X of Y in this wave] (or "standalone — no wave context")

### Use Cases Covered
- UC-X.Y: [scenario name]
- UC-X-A: [alternative flow name]

### Tests Written
- [test file]: [number] test cases

### Implementation
- [files changed with brief description]

### Verification
- Typecheck: PASS/FAIL
- Tests: PASS/FAIL (X passed)
- Build: PASS/FAIL

### Git
- Branch: [branch name]
- Commit: [hash] — [message]

### Changelog
- Entry written: Yes / Skipped (parallel-wave subagent) / Skipped (no-changelog flag — develop-feature owns it)

### Next Slice
- [description of next slice]

Auto-Continue

When running as a parallel subagent (wave context provided): do NOT auto-continue. Return your result (PASS with commit hash, or FAIL with error details) to the orchestrator. Wave progression is managed by develop-feature.

When running standalone (no wave context), after committing this slice, if there are remaining slices in the plan:

• Immediately proceed to the next slice
• Do NOT wait for user input
• Read .claude/scratchpad.md to identify the next slice
• Continue the TDD flow for the next slice