---
name: staged-implementation
description: Implement coding changes in engineer-reviewed stages. Use only when the user explicitly invokes $staged-implementation or directly requests staged implementation, incremental implementation with approval between stages, or a pause after each implementation section. Plan the stages before editing, work test-first where practical, report each stage, and wait for explicit engineer confirmation before continuing.
---

# Staged Implementation

Implement a coherent section of a coding task at a time so the engineer can inspect, modify, and own the change as it develops.

## Preflight

Before changing files:

1. Inspect the request, relevant code, tests, and working tree.
2. Propose a cohesive stage map with a fixed total, such as `1/4` through `4/4`. Do not count preflight as a stage.
3. State each stage using this compact contract:

   ```markdown
   Stage N/M — <single deliverable>

   - Outcome: After this stage, …
   - Includes: …
   - Explicitly excludes: …
   - Test target: …
   - Why this is not split further: …
   ```

   Keep a behavioral test and its associated implementation in the same stage; never create a tests-only stage followed by an implementation-only stage.
4. Wait for the engineer to approve the stage map before starting Stage 1, unless the user has already explicitly approved the proposed breakdown.

## Stage Sizing

Plan each stage around the smallest end-to-end behavior or coherent internal outcome that an engineer can review without mentally completing unfinished work.

### One Primary Deliverable

A stage must have exactly one primary, reviewable deliverable. State it as a
single sentence beginning with “After this stage, …”. Split a stage when it
changes more than one independently reviewable concern:

- runtime configuration or feature enablement;
- public API shape or HTTP semantics;
- persistence or query behavior;
- client or UI behavior;
- operational readiness or deployment behavior.

Keep changes from multiple concerns together only when separating them would
leave an unsafe or misleading intermediate state. State that dependency in the
stage map's “Why this is not split further” field.

Before proposing the map, write a one-sentence release note for each stage. If
the sentence describes multiple distinct user outcomes, split the stage.
Default to three to five stages; use two only when both stages are genuinely
narrow end-to-end vertical slices.

- Give each stage one independently verifiable outcome and its closest relevant test.
- Include every change needed to make that outcome coherent; do not split work merely by file, layer, or technical role.
- Split a stage when it contains multiple independently testable behaviors, separate user journeys, or decisions that could be approved independently.
- Keep preparatory work with the first outcome that depends on it, unless the preparation itself establishes a useful, verifiable contract or invariant.
- Avoid splitting tightly coupled changes when doing so leaves a stage unusable, misleading, or dependent on unreviewed follow-up work.

Use this planning question to judge a proposed boundary: *What is the smallest end-to-end behavior an engineer could approve without needing to mentally simulate unfinished pieces?*

Do not start a later stage early.

## Execute a Stage

For every stage, use this order:

1. Announce `Stage N/M` and the one subsection being implemented.
2. Create or update the narrowest relevant test first when practical. Run it to establish the expected failure when practical.
3. Implement only the behavior in that stage.
4. Run the focused test and proportionate static checks or broader verification.
5. Report the stage in this format:

   ```markdown
   Stage N/M — <outcome>

   - Tests: <added/updated tests, or why tests were not applicable>
   - Implementation: <what changed>
   - Verification: <commands and results>
   - Review note: <remaining concern or none>

   Waiting for your confirmation or revised direction before Stage N+1/M.
   ```

Do not begin the next stage until the engineer gives clear approval or revised direction. Treat questions, silence, and a status request as a pause rather than approval.

## Tests and Exceptions

Prefer nearby test patterns and focused behavioral assertions. When test-first work is impractical, document the reason in the stage report and add coverage as close to the behavior as possible. Examples include mechanical non-behavioral changes, a CSS-only visual change, no runnable test target, or unavailable required services.

## Engineer Changes Between Stages

On every resumption, inspect the working tree and relevant diff before editing. Preserve engineer changes and summarize how they affect the completed work and remaining stages.

If the engineer's changes or revised direction make the remaining map inaccurate, publish a revised stage map before continuing. Keep the original total when possible; when it must change, clearly state the new total and resumed position, for example `Stage 2/5` after revising an original four-stage map. Ask for direction when the intent of manual changes is unclear.

## Completion

After the final approved stage, provide a concise aggregate summary of all stages, verification, and any remaining test gap. Do not claim completion while a required approval gate is outstanding.