---
name: Running An Iteration
slug: running-an-iteration
category: AI Engineering
description: Running An Iteration executes the next pending roadmap iteration by reviewing scope, baselining sentinel scenarios, dispatching implementation and evidence tasks, and updating iteration artifacts. Use it in an iterative-development loop when advancing one iteration at a time.
github: "https://github.com/prime-radiant-inc/iterative-development/tree/main/skills/running-an-iteration"
language: Python
stars: 179
forks: 17
install: "npx degit https://github.com/prime-radiant-inc/iterative-development/tree/main/skills/running-an-iteration ~/.claude/skills/running-an-iteration"
installs_to: ~/.claude/skills/running-an-iteration
source_path: skills/running-an-iteration/SKILL.md
collection_size: 6
category_size: 3475
collection_url: "https://dirskills.com/collections/prime-radiant-inc/iterative-development"
added: 2026-09-07T05:20:44.797Z
last_synced: 2026-09-07T05:20:44.797Z
canonical_url: "https://dirskills.com/skills/running-an-iteration"
---

# Running An Iteration

Running An Iteration executes the next pending roadmap iteration by reviewing scope, baselining sentinel scenarios, dispatching implementation and evidence tasks, and updating iteration artifacts. Use it in an iterative-development loop when advancing one iteration at a time.

**Install:**

```bash
npx degit https://github.com/prime-radiant-inc/iterative-development/tree/main/skills/running-an-iteration ~/.claude/skills/running-an-iteration
```

## README

# Running an Iteration

## Overview

Drives one iteration: picks the next pending, runs sentinel corpus baseline, runs pre-iteration scope review via PAR, decomposes into code and evidence tasks, dispatches `implementing-tasks`, runs impacted + sentinel scenarios at wrap-up, and updates the roadmap and iteration log.

## When to Use

Invoked by `iterative-development` inside the main loop. Each invocation runs exactly one iteration. After return, the orchestrator invokes `auditing-progress`.

## Script Location

All scripts referenced below live in this skill's `scripts/` directory, next to this SKILL.md file.

## Iteration Process

### 1. Pick next iteration

Read `docs/superpowers/iterations/roadmap.md`, find the first iteration with status `pending`.

### 2. Load scope context

Read the per-epic files in `docs/superpowers/iterations/requirements/` to load the full story cards for each committed story ID. Only read the epic files that contain stories for this iteration — not all of them. Also:
- Load the next 3 pending iterations from the roadmap for look-ahead
- Read `docs/superpowers/iterations/behavior-scenarios.md` to identify impacted scenarios
- Read `docs/superpowers/iterations/behavior-corpus.md` to identify sentinel scenarios

### 3. Run sentinel corpus baseline

Before any code changes, run every scenario in the behavior corpus with run cadence `sentinel`:

- If all sentinels pass: record baseline as clean, proceed
- If any sentinel fails: the failure predates this iteration. Record it, create a gap story for it, but proceed with the iteration (the gap will be addressed in a follow-up)

This establishes whether regressions exist before the current iteration starts.

### 4. Pre-iteration consistency audit

Before planning any work, verify that artifact state is consistent:

1. **Citation check:** `python3 "scripts/check_citations.py" docs/superpowers/iterations/roadmap.md docs/superpowers/iterations/requirements/` — if citations fail, stop and fix the roadmap.
2. **Status reconciliation:** For each story in this iteration's scope, verify:
   - Stories listed in the roadmap iteration are not already marked `done:ITER-XXXX` in the requirements index (unless code/tests actually exist for them)
   - Stories marked `done` in the requirements index actually have corresponding code and tests
   - No story appears in multiple pending iterations
3. **Epic counter validation:** Spot-check that epic progress counters match the actual count of `done` stories.

If any inconsistencies are found, reconcile before proceeding. Do not trust any single artifact blindly — cross-check.

### 5. Pre-iteration scope review (PAR)

Following `skills/shared/parallel-adversarial-review.md`:

1. Build the scope reviewer prompt using `scope-reviewer-prompt.md`
2. Wrap in PAR competitive framing from `skills/shared/par-reviewer-wrapper.md`
3. Dispatch TWO scope reviewers in parallel
4. Aggregate findings: same issue from both = high confidence, unique = still actionable, severity disagreement = take worst
5. If REVISE recommended: adjust iteration scope and re-review. Loop until APPROVE.

### 6. Decompose into code tasks AND evidence tasks

Break the iteration scope into TDD-sized tasks. Each task = failing test → implementation → passing test → commit.

**Evidence tasks:** In addition to code tasks, identify:
- Which existing scenarios are impacted by this iteration's changes
- Which new scenarios must be added (from the story proof obligations)
- Which scenario harnesses need to be extended
- Which behavior corpus entries need updated execution commands

Evidence tasks are first-class — they produce scenario updates, test harness extensions, and corpus index entries. They are NOT afterthoughts. Interleave evidence tasks with code tasks: after implementing a feature, the next task should be extending or adding the scenario that proves it.

**Cross-iteration dependencies:** Some stories reference subsystems that don't exist yet. For these, implement the thinnest abstraction boundary that satisfies the story's ACs without coupling to the future implementation. Prefer a single clean interface over a decomposed hierarchy — the real implementation will define its own internal structure when it arrives. Document the dependency with a TODO comment citing the future iteration. Do NOT defer the story silently or force premature integration.

### 7. Dispatch implementing-tasks

Pass the task list (code + evidence tasks) and iteration context to `implementing-tasks`. Wait for completion.

### 8. Post-iteration scenario runs

After all tasks complete, run:

1. **Impacted scenarios:** every scenario in the behavior corpus whose owning stories were touched by this iteration
2. **Sentinel scenarios:** every scenario with run cadence `sentinel`

If any impacted or sentinel scenario fails that passed at baseline (step 3), this iteration introduced a regression. Create a fix task and re-dispatch to `implementing-tasks`.

### 9. Resolve cross-iteration TODOs

Grep the codebase for `TODO(ITER-<current>)` markers — these are interface stubs that earlier iterations created expecting THIS iteration to provide the real implementation.

For each marker found:
1. Verify the real implementation now exists (not still a stub/NoOp)
2. If resolved: remove the TODO comment
3. If NOT resolved: the iteration is incomplete — add a fix task and re-dispatch

This step is a hard gate. An iteration that leaves its own TODO markers in the code is not done.

### 10. Wrap up

- Verify all iteration stories' ACs pass (sanity check before audit)
- Verify all proof obligations for observable ACs have corresponding scenario evidence
- Verify no `TODO(ITER-<current>)` markers remain in the codebase (step 9)
- Mark stories `done:ITER-NNNN` in the relevant epic files under `requirements/`
- Update scenario automation status and execution commands in `behavior-scenarios.md`
- Update the behavior corpus index in `behavior-corpus.md`
- Update iteration status in `roadmap.md` to `done`
- Append entry to `docs/superpowers/iterations/iteration-log.md` — include:
  - Stories delivered
  - Scenarios added or updated
  - Sentinel corpus results
- Validate: `python3 "scripts/validate_iteration_log.py" docs/superpowers/iterations/iteration-log.md`
- Return control to orchestrator (do NOT invoke `auditing-progress` — that's the orchestrator's job)

## Quick Reference

| Step | Tool/Skill | Purpose |
|---|---|---|
| Sentinel baseline | Run sentinel scenarios | Establish pre-iteration regression state |
| Citation check | `scripts/check_citations.py` | Mechanical: cited stories exist |
| Scope review | PAR + `scope-reviewer-prompt.md` | Semantic: scope, scenarios, splitting, boxing-in |
| Task execution | `implementing-tasks` | TDD code + evidence implementation |
| Post-iteration runs | Run impacted + sentinel scenarios | Catch regressions |
| TODO resolution | `grep -rn 'TODO(ITER-<current>)'` | Cross-iteration stubs resolved |
| Wrap up | `scripts/validate_iteration_log.py` | Artifact validation |

## References

- `skills/shared/parallel-adversarial-review.md` — PAR methodology
- `skills/shared/behavior-evidence-formats.md` — scenario and proof obligation formats
- `scope-reviewer-prompt.md` — scope reviewer prompt template
- `scripts/check_citations.py` — mechanical citation check