---
name: iterate
description: >
  Execute one iteration cycle within the current milestone. Reads context,
  implements a single scoped change, runs quality gates, records results,
  and decides next action. Use this for every individual development step.
---

# Iterate — Single Iteration Cycle

Execute exactly one development iteration following `docs/implement.md`.

## When to use

- You need to implement the next deliverable in the current milestone
- You need to fix a bug or test failure
- You need to refactor a specific module

## Steps

### 1. Read context
1. Read `AGENTS.md` — confirm the execution contract and hard constraints
2. Read `docs/prompt.md` — current milestone scope
3. Read `docs/plan.md` — find the specific deliverable (look for unchecked `- [ ]`)
4. Read last 3 entries in `docs/documentation.md` — avoid repeating failed approaches
5. Read `docs/failures/taxonomy.md` — check for known failure patterns

### 2. State intent
Write one sentence:
> I am changing [X] to achieve [Y] because [Z].

The reason must trace to a milestone deliverable. The claim must be falsifiable.

### 3. Implement
- One primary change only
- Respect the max-files-per-change limit recorded in `AGENTS.md` and `docs/implement.md`
- Follow legibility principles (structured logging, remediation hints, module docstrings)
- If the change grows too large, stop and decompose
- Keep a running list of files touched in this iteration; you will need it for safe rollback and documentation

### 4. Verify
1. Run the primary quality gate command from `AGENTS.md` §5.
2. Run the focused verification commands listed in `docs/prompt.md` for the active deliverable.
3. If the project defines a separate regression check in `docs/implement.md`, run that before recording results.

### 5. Record
Update `docs/documentation.md`:
- Refresh `## Current State`
  - current milestone
  - active deliverable
  - last validation result
  - next action
- If this iteration introduced a lasting repo rule or tradeoff, add a short bullet to `## Decision Log`
- If code changes or doc validation exposed stale guidance, update the affected docs now instead of deferring to a separate maintenance sub-skill
```
## Iteration #<n> — <date>
- **Milestone**: <ID>
- **Change**: <one sentence>
- **Files modified**: <list>
- **Rollback scope**: <only files from this iteration that are safe to revert>
- **Verification result**: <pass/fail + evidence>
- **Quality gate status**: <pass/fail>
- **Decision**: continue | adjust | rollback
- **Next step**: <what to do next>
```

### 6. Decide
- **continue** → verification passed, pick next deliverable
- **adjust** → partial success, refine and re-iterate
- **rollback** → regression or unexplainable result, revert

## On failure: use escalating recovery

| Level | When | Action |
|---|---|---|
| L1: Retry | First failure | Minor adjustment, re-run |
| L2: Adjust | Same failure after L1 | Different approach entirely |
| L3: Rollback + Replan | Same failure after L2 | Revert only the files from this iteration after inspecting the diff, then decompose the deliverable |
| L4: Escalate | Same failure after L3 | Stop, notify human with full context |

### Harness signal capture (after every L2 or L3)

After resolving an L2 or L3 failure, ask: **"What was missing from the environment
that caused this struggle?"**

Classify the gap:
- `missing-doc` → add or update the relevant documentation
- `missing-tool` → create a script or recommend installing a tool
- `missing-constraint` → add a lint rule, CI check, or AGENTS.md guardrail
- `missing-context` → update AGENTS.md, compaction strategy, or Required Reading
- `uncertain` → ask the human what would have prevented this failure

Then:
1. Update `docs/failures/taxonomy.md` with the failure pattern AND a prevention action
2. If the fix is a harness change (not just a code fix), record it in
   `docs/documentation.md` Decision Log with tag `harness-improvement`
3. If the pattern is universal (not project-specific), also tag it
   `harness-improvement-candidate` for potential upstream skill improvement

## Replan trigger check (after every L2 or L3)

After resolving an L2 or L3 failure, also check whether the plan itself needs adjustment:

- **Consecutive 2× L2+**: review whether the current deliverable should be split
  into smaller pieces. If yes, update `docs/plan.md` with the decomposed deliverables.
- **Consecutive 3× L2+**: review whether the current milestone scope is too ambitious.
  If yes, consider splitting the milestone or deferring some deliverables.
- **New constraint or dependency discovered**: evaluate whether it affects the current
  milestone or subsequent milestones. If yes, update `docs/plan.md` and record the
  reason in `docs/documentation.md` Decision Log.
- **Uncertain whether to replan** → ask the human (per the Uncertainty Protocol).

Spec change protocol:
- Small changes (do not affect North Star or hard constraints) → agent may update
  `docs/plan.md` and `docs/prompt.md` autonomously, recording the change in Decision Log
- Large changes (affect North Star, hard constraints, or architecture) → escalate to
  the human before making any plan changes

## Periodic check

After every 3 iterations, run `$quality-audit` sub-skill (if installed) and update
`docs/plan.md` Operations Cadence with the latest evidence.

Before external review or handoff, capture a short review packet in
`docs/documentation.md` with:
- scope of the change
- files changed
- validation evidence
- primary risks or follow-ups

Never use repository-wide rollback commands such as `git checkout -- .` or `git reset --hard`.

During normal iteration work, do NOT ask the human for routine confirmation.
Only escalate when a hard constraint, blocking ambiguity, uncertainty protocol trigger,
or L4 recovery trigger requires it.
