iterative:implementing

What this skill does

# Executing Work

Read the plan critically, create tasks, and implement with TDD, code review, and continuous testing. The plan is your guide — it contains the decisions, patterns, and test scenarios that drive implementation.

## When to Use

- After `iterative:tech-planning` skill completes a plan
- When a plan document exists and is ready to implement
- When tasks already exist from a prior session
- Can be invoked standalone with a plan document path

## Key Principles

1. **The plan is your guide** — Read referenced files and patterns, use the plan's decisions to drive implementation
2. **Clarify before building** — Ask questions now, not after building the wrong thing
3. **Test as you go** — Run tests after each change, not at the end
4. **Commit as you go** — One commit per completed subtask, never batch commits at the end
5. **Review at the right scope** — Section review after each plan section, final review of all branch changes, user chooses which severities to fix
6. **Stop when blocked** — Ask for help rather than guessing

## Workflow

### Phase 0: Detect Resume

1. Check for in-progress tasks related to this plan.
2. If tasks exist and work is in progress: load the plan document, summarize current state, show completed vs remaining subtasks, continue from next incomplete subtask (skip to Phase 2).
3. If no tasks exist: proceed to Phase 1 — **even if you have prior conversation context.** Having discussed the plan in a previous session is not the same as having set up tasks and workspace. Phase 1 setup (task creation, workspace isolation) must run before any implementation begins.

### Phase 1: Understand and Setup

1. **Find and read the plan document completely.** Check conversation context for referenced plans, scan `docs/plans/` for recent plan files. If no plan found, ask user for path. If no plan exists, ask the user: A) Create a tech plan first (recommended), B) I'll provide the plan path. If tech plan: invoke `iterative:tech-planning` skill.
2. **Review critically.** If anything is unclear or ambiguous, ask now. Do not skip this — better to clarify now than build the wrong thing.
3. **Workspace isolation.** See Workspace Setup section.
4. **Create tasks from the plan.** See Task Creation section.
5. **Execution preference.** Present an interactive choice to the user — `AskUserQuestion` (Claude Code) or `request_user_input` (Codex): A) Execute all tasks, report when done (default), B) Pause after each plan section for feedback, C) Pause after each subtask for feedback.

### Phase 2: Execute (repeat per plan section)

1. **Record section baseline.** Before starting each plan section, capture the current commit: `git rev-parse HEAD`. This SHA is the section's baseline — used to scope reviews to only this section's changes.
2. **Analyze dependency graph.** Using the plan's `**Depends on:**` and `**Files:**` fields, group the section's subtasks into execution batches — subtasks with no unmet dependencies form the next batch.
3. **Execute batch.** For each batch, spawn subagents for all subtasks (concurrently when multiple). Always use subagents, even for single-subtask batches — this keeps implementation detail out of the orchestrator's context, preserving capacity for reviews, phase transitions, and user interaction. Each subagent receives:
   - Path to the tech plan document
   - Subtask number and title
   - Parent task context
   - Task ID
4. Worker reads subtask from plan, loads referenced patterns, implements with TDD (tests first), commits, and updates task status (see task-worker agent for details).
5. **Wait for batch completion.** All subagents in the batch must finish before the next batch starts.
6. **Test verification gate.** After each batch completes, verify that feature subtasks produced test files. For each completed feature subtask, check: does the test file listed in the plan's `**Files:**` field exist, and does it contain tests matching the plan's `**Test scenarios:**`? If a feature subtask committed without tests, flag it immediately — do not continue to the next batch until resolved.
7. **Repeat** steps 3-6 for remaining batches.
8. Update plan document progress (mark completed items).
9. Mark section complete in task system.
10. **Section code review.** Run after all subtasks in the plan section are complete (see When to Review table for trivial exceptions). **Skip if this is the only section in the plan** — Phase 3's final review will cover the same code plus simplification changes, so a section-level review would be redundant. For multi-section plans: scope to `git diff <section-baseline-sha>..HEAD`. Pass the baseline SHA and plan context to the `code-review` skill. **Wait for the review to complete and fixes to land before moving on.** Do not run anything else in parallel with code review — it needs to see the final code. **Placeholder exclusion:** When the review returns findings targeting code that is an acknowledged placeholder for a later plan section, exclude those findings from severity acceptance — they will be addressed in a later section and caught by the final review. Note excluded count and reasons in the review summary (e.g., "Excluded 1 finding — placeholder for section 3").

### Phase 3: Finish

**Phase 3 steps are strictly sequential. Do not parallelize them** — each step depends on the output of the previous one.

1. Verify: all tasks complete, all section-level code reviews passed.
2. **Detect base branch.** `git rev-parse --verify origin/main >/dev/null 2>&1 && echo main || echo master`. Use this for all branch-level scoping in Phase 3.
3. **Simplification pass.** If `/simplify` is available, invoke it to review and clean up changed code. Otherwise, do a manual review of changed files (`git diff --name-only $(git merge-base HEAD <base>)..HEAD`) and apply behavior-preserving simplifications: flatten nesting, remove dead code, simplify expressions, collapse single-use variables. This is a single bounded pass — not a refactor. **Wait for simplification to complete before proceeding** — the final review must see simplified code.
4. **Final review offer.** Present an interactive choice to the user: A) Full code review of complete work (recommended), B) Skip to finish.
5. If review: invoke `code-review` skill with scope `git diff $(git merge-base HEAD <base>)..HEAD` (all branch changes including simplification).
6. **Severity acceptance (separate prompt).** If the review found issues at any severity, present severity acceptance (see Severity Acceptance section). This is its own prompt — do not combine it with next-step options, and do not skip it even when all issues are Medium/Low. "Clean" means zero findings at any severity. If no findings, skip to step 7.
7. **Next steps (separate prompt, after fixes land or user skipped fixes).** Present an interactive choice to the user: A) Another review round, B) Wrap up and create PR, C) I'll handle PR/merge myself (exit). Do not recommend wrap-up if fixes were just applied — recommend **another round** to verify. Recommend **wrap up** only when zero findings or user chose to skip all fixes.
8. Repeat steps 5-7 if user chooses another round.

## Workspace Setup

Ensure the agent has an isolated workspace before creating tasks or writing code.

**First: sync with remote**
Pull the latest from the default branch before creating any branch or worktree.

**Then: check current state**

| Situation | Action |
|-----------|--------|
| Already in a worktree | Confirm it's for this feature, then proceed |
| On default branch | Ask the user: A) Create worktree (recommended), B) Create branch, C) Continue on main (requires explicit consent) |
| On a feature branch | Ask the user: A) Continue on this branch, B) Create new worktree |

Invoke the `git-worktree` skill if a worktree is needed.

## Task Creation

Task creation happens inside Phase 1, after the plan is read and clarified. This ensures the implementer understands the plan before tasks are locked in.

###