---
name: iterate-prototype
description: "Use to drive the polish loop on an in-progress prototype — read user feedback list, revise the relevant partitions, re-verify, repeat until the user emits 'satisfied' or 'LOCKED'. The polish loop after build-prototype's initial scaffold; runs sequentially (not parallel partitions). Captures gotchas + conventions discovered during iteration."
---

# Iterate Prototype

## Overview

After build-prototype scaffolds the initial prototype (per the manifest's `artifacts.prototype.stack:` — Vite+React app for `vite-react`, screens in the host Next.js app for `nextjs`, FastAPI service for `python-fastapi`, CLI binary for `cli`, Go service for `go-service`, or the existing app for `existing-repo`), the user runs it locally and gives feedback. For UI stacks: "this header is too tall", "the case detail needs a wrap-up modal", "the inbox filter is in the wrong place." For backend / CLI / service stacks: "the response shape is missing X", "this command should accept Y flag", "the grpcurl trace doesn't show Z." This skill turns that feedback into focused revisions and verifies each one before the next.

**Core principle:** the prototype iterates against the running app, not against imagined screens. Every revision cycle ends with `npm run dev` + click-through verification before the user gives the next round of feedback.

**Announce at start:** "I'm using the iterate-prototype skill to apply the pending feedback to the prototype."

## When to Use

- After `build-prototype` finishes the initial scaffold and the user starts giving feedback
- When the user says "polish", "iterate", "fix this", "tweak X", or names a specific feedback item
- When the user adds entries to `pocs/{name}-prototype/.forge/feedback.md` and asks to apply them

**Do NOT use this skill for:**
- Initial scaffolding (use `build-prototype` instead)
- Adding entirely new screens not in the wireframe (revise the wireframe first via `build-wireframe`)
- Fixing actual bugs in production code (this is prototype-only; production bugs go through `/bugfix`)
- Implementing real auth / real DB / production hardening (still Phase 6)

## Loop modes

Two modes, both opt-in:

| Mode | When |
|---|---|
| **Manual** (default) | User adds feedback, invokes `/iterate-prototype`, reviews after revision, repeats. One cycle per invocation. |
| **Autopilot** *(planned, not yet implemented)* | User invokes `/autopilot prototype` once. A stop-loop hook re-feeds the prompt until the user emits `LOCKED`. The skill reads feedback, applies, verifies, then yields back to the loop hook for the next cycle. See docs/V6-PLAN.md §11; until shipped, every cycle is manual. |

Default to manual unless the user explicitly opts into autopilot. Autopilot's risk is iteration without human review at each step — useful for hands-off polish but easy to misuse on consequential design changes.

## Inputs

| Source | Required | Purpose |
|---|---|---|
| Running prototype at `pocs/{name}-prototype/` | yes | The codebase being iterated |
| Locked wireframe HTML | yes | Still the spec — drift is checked against it |
| `pocs/{name}-prototype/.forge/feedback.md` | yes | Running list of user feedback items, oldest first |
| `pocs/{name}-prototype/.forge/partition-plan.md` | yes (from build-prototype) | Which partition each feedback item routes to |
| Existing `aiwiki/gotchas/` and `aiwiki/conventions/` | optional | Phase 4 captures so far |
| Manifest at `.forge/work/{type}/{name}/manifest.yaml` | yes | Phase state target |

## Feedback file format

`pocs/{name}-prototype/.forge/feedback.md` is a checklist:

```markdown
# Prototype Feedback

## Pending

- [ ] Case header is too tall on supervisor view — reduce vertical padding by 1 step
- [ ] Inbox filter sticky-positioned at wrong y-offset on `/inbox`
- [ ] Add an explicit "wrap up" CTA on case detail (currently only via menu)

## Resolved

- [x] (2026-05-09) Wireframe `s2` had a left rail; prototype was missing it — added
- [x] (2026-05-09) Tutorial overlay click-target too small — bumped hit area
```

The skill reads the `## Pending` section, applies each item in order, then moves resolved items to `## Resolved` with the date.

The user appends to `## Pending` between iterations. Manual mode runs one batch of pending items per invocation; autopilot mode keeps draining until pending is empty AND the user emits LOCKED.

## Process

### Step 0: locate inputs

| Input | How to find |
|---|---|
| Repo root | `git rev-parse --show-toplevel` or `${CLAUDE_PROJECT_DIR}` |
| Manifest | The single in-progress manifest under `.forge/work/*/*/manifest.yaml`. Multiple = ask user. |
| Prototype path | Manifest's `artifacts.prototype.path`, or default `pocs/{name}-prototype/` |
| Wireframe path | Manifest's `wireframe_path`, or default `pocs/{name}-wireframe/index.html` |
| Feedback file | `<prototype-path>/.forge/feedback.md` |
| Partition plan | `<prototype-path>/.forge/partition-plan.md` |

If `artifacts.prototype.locked_at` is already present in the manifest, surface the gap and stop — iterate runs while the prototype phase is open, not after lock. Otherwise the prototype phase is open: proceed.

### Step 1: read pending feedback

Parse `## Pending` from the feedback file. Each line that begins with `- [ ]` is an unresolved item.

If no pending items: report "No pending feedback to apply" and stop. The skill is a no-op when there's nothing to do.

### Step 2: route feedback items to partitions

For each pending item, identify which partition the change touches by reading the partition plan and the feedback content.

Three routing patterns:

| Feedback shape | Routing |
|---|---|
| Names a specific screen ("case detail header...") | Route to that screen's partition |
| Names a system area ("tutorial overlay..., notifications...") | Route to that system's partition |
| Cross-cutting (design tokens, shared component, global state) | Dispatch a single instance of `prototype-builder` covering the shared scaffold (NOT a partition) |

If a feedback item is genuinely ambiguous (could touch multiple partitions), dispatch one builder per affected partition with the item scoped to "your-partition's expression of <feedback>".

### Step 3: dispatch sequentially per partition

Unlike build-prototype's parallel dispatch, iterate-prototype runs sequentially. Reasons:

- Feedback items are usually small, individually scoped
- Sequential application keeps the diff reviewable per item
- Parallel revisions of the same partition would conflict

For each pending item:

1. Dispatch `prototype-builder` with the item scoped to the relevant partition (or shared scaffold)
2. Subagent returns the diff (changed files, content)
3. Apply the diff
4. Mark the item resolved

For cross-cutting items that touch multiple partitions, route to each in turn (still sequential).

### Step 4: verify after each cycle (or after the batch in autopilot)

In manual mode, after applying the batch:

```bash
cd pocs/{name}-prototype
npm run dev          # smoke test
# user clicks through; provides next round of feedback
```

In autopilot mode, after each individual item is applied:

```bash
cd pocs/{name}-prototype
npm run dev &
sleep 2  # give Vite time to compile
npx playwright codegen http://localhost:5173 --output /tmp/codegen.spec.ts &
# script kills after sanity check; the codegen output is for human review later
```

Verification doesn't replace user judgment — it just catches obvious breakage (compile errors, missing routes). The user is still the final reviewer.

### Step 5: dispatch prototype-reviewer for drift check (optional, every 5 cycles or on demand)

After ~5 iteration cycles, drift between prototype and wireframe accumulates silently. Dispatch `prototype-reviewer` to flag:

- Wireframe states that no longer have a matching prototype screen
- Prototype screens that aren't in the wireframe (undocumented features)
- Interaction model deviations (e.g. wireframe shows modal, prototype now uses sheet)
- Convention drift (file naming, import order, design token usage)

The reviewer returns findings; the user decides whether to update the wireframe (codify the change) or revert the prototype (restore alignment). Either way, the next iteration starts from a known-aligned state.

In autopilot, the reviewer runs every 5 cycles automatically. In manual, it runs on demand or when the user invokes `/check-prototype-drift`.

### Step 6: capture side effects during iteration

Each iteration may surface gotchas or conventions. The dispatched prototype-builder subagent will write these to `aiwiki/` per the gotcha and convention schemas. The wiki-lint hook validates on save.

If the prototype-builder reports a gotcha that already exists (matched by root cause), bump the existing gotcha's `occurrences` field instead of creating a duplicate. If `occurrences` reaches 3+, the gotcha is auto-drafted as a `proposed_rule:` block — the next session-start will hard-interrupt to require user approval before promoting it.

**When aiwiki is disabled** (`project.aiwiki_enabled: false` or `aiwiki/` missing): instruct the prototype-builder subagent to surface its findings as a one-line note to the user instead of writing — e.g. `aiwiki disabled — would have captured gotcha "{title}" / convention "{title}"; re-run /setup and pick Y to enable.` The subagent continues with the revision work; only the capture leg is suppressed. The Step 9 phase-close dream is skipped in this state (nothing to consolidate).

### Step 7: update the feedback file

After each batch (manual) or each item (autopilot):

- Move resolved items from `## Pending` to `## Resolved` with date
- Keep pending items that weren't applied (e.g. user reordered priorities)

### Step 8: detect convergence

Two convergence signals:

| Signal | Meaning |
|---|---|
| User emits "satisfied", "LOCKED", "done", or equivalent | Phase 4 is closing — write `artifacts.prototype.locked_at: <ISO-8601 timestamp>` and stop the loop. This is the **single-writer lock**: `build-prototype` set the `path` and `scaffold_status` earlier; `iterate-prototype` is the sole owner of `locked_at`. |
| Iteration count reaches 10 cycles since last alignment check | Run prototype-reviewer drift check before continuing; surface "are we converging?" if drift is high |

In autopilot mode, the loop hook reads the LOCKED signal from the manifest and exits cleanly.

### Step 9: phase-close dream (auto-fire on lock)

**Trigger:** Step 8 just wrote `artifacts.prototype.locked_at`. The prototype phase is closing, and Phase 4's accumulated `aiwiki/` writes (gotchas, conventions, raw notes from `/note`) should be consolidated before the next phase (codify) reads from it.

**Action:** invoke the `support-dream` skill with:

- **scope:** `aiwiki/raw/`, `aiwiki/gotchas/`, `aiwiki/conventions/` (the subfolders Phase 4 wrote to)
- **trigger:** `phase-close`
- **trigger_detail:** `"Phase 4 (iterate) lock — {feature/name}"`

`support-dream` dispatches the `dreamer` subagent and writes a consolidation proposal to `aiwiki/proposed/{dream_id}/`. Surface the dream id and review path to the user:

```
Phase 4 closed. Dream queued: 2026-05-18-HHMM-iterate-{name}
Review: `forge wiki review {dream_id}` or open `forge wiki ui`
The codify (Phase 5) gate blocks until this dream is reviewed.
```

**Gate coupling:** the codify gate (`harden` Step 0 readiness check) must verify any phase-4 dream is reviewed before proceeding. The next phase reads consolidated wiki state, so it cannot proceed against pending unreviewed proposals.

**Skip when:** no aiwiki writes occurred during Phase 4 (gotchas/conventions/raw all unchanged since prototype scaffold), or `project.aiwiki_enabled: false` (no aiwiki to consolidate). No-op dreams add noise.

## Anti-fatigue

If pending feedback grows past 10 items without any being resolved, the loop is not iterating — it's accumulating. Surface this to the user explicitly: "Pending list has grown to N items without resolution; consider whether the wireframe needs an update before continuing prototype iteration." This is the prototype-equivalent of the wiki accept-fatigue safeguard.

## Common mistakes

| Mistake | Fix |
|---|---|
| Running parallel revisions of the same partition | Sequential only in iterate; parallel is build-prototype's territory |
| Skipping drift check across many iteration cycles | Drift accumulates silently; run `prototype-reviewer` every 5 cycles or surface the gap |
| Applying feedback that asks for new screens | New screens require wireframe revision first; surface the gap, do not extrapolate |
| Hardening the prototype during iteration | Phase 4 is still the prototype; real auth / real DB / production-grade error handling stays out |
| Letting feedback file grow unbounded without convergence signal | Anti-fatigue: surface explicit "pending growing without resolution" warning at >10 unresolved |
| Forgetting to capture gotchas surfaced during iteration | Gotchas are Phase 5 inputs; they must land in `aiwiki/gotchas/` to feed harden |
| Bypassing wiki-lint on captured gotchas/conventions | Hook fires automatically; if it's bypassed, lint manually after |

## Red Flags

**Never:**
- Add screens not in the wireframe (revise the wireframe first)
- Lock the prototype with known broken interactions (the lock signal means "production should match this")
- Run autopilot mode on consequential design changes (e.g. layout overhaul) — autopilot is for polish, not redesign
- Skip drift checks indefinitely (5-cycle cadence is the floor)

**Always:**
- Sequential dispatch (one prototype-builder at a time during iterate)
- Update the feedback file as items resolve
- Run `npm run dev` between cycles in manual mode
- Capture gotchas + conventions to `aiwiki/` as they surface

## I/O Contract

| Field | Value |
|---|---|
| **Requires** | Running prototype, locked wireframe, feedback file, partition plan, manifest |
| **Produces** | Code changes in `pocs/{name}-prototype/`, updated `pocs/{name}-prototype/.forge/feedback.md`, gotchas + conventions in `aiwiki/` |
| **Updates manifest** | `artifacts.prototype.{path, locked_at}` on convergence |
| **Triggers** | wiki-lint on every `aiwiki/**` write; phase-close dream when prototype locks |

## Integration

| Caller | When |
|---|---|
| Manual `/iterate-prototype` | User-driven polish cycle |
| `/autopilot prototype` *(planned, not yet implemented)* | Stop-loop hook re-feeds the prompt; this skill runs once per cycle |
| `build-prototype` final step | After initial scaffold + first verification, hands off to iterate-prototype for refinement |

| Dispatches | For |
|---|---|
| `prototype-builder` (sequential, per partition) | Code revisions for each feedback item |
| `prototype-reviewer` (every 5 cycles or on demand) | Drift check between prototype and wireframe |

| Pairs with | For |
|---|---|
| `build-prototype` | Initial scaffold predecessor |
| `harden` | Phase 5 successor — runs once iterate-prototype emits the LOCKED signal |
| `support-gotcha` | Captures gotchas during iteration |
| `support-wiki-lint` | Validates gotcha + convention writes |