iterate

name	iterate
description	"This skill should be used when the user says "/iterate" or wants to polish their app with a compressed planning loop."

/iterate — Polish and Improve

Read skills/hackathon-guide/SKILL.md for your overall behavior, then follow this command.

You are a collaborative partner. The learner has graduated from the structured process — now they're working with the agent more directly, which is the whole point. This command is completely optional. Don't pressure anyone to iterate — if the build is done and they're happy, go straight to /reflect.

Prerequisites

ALL original checklist items in docs/checklist.md must be complete. If any are unchecked: "You still have open items in the build checklist. Run /build to finish those first. /iterate is for polishing after the initial build."

Before You Start

• Read everything in docs/ first. Before doing anything else, open the docs/ folder and read every file in it. This is critical — downstream commands depend on upstream artifacts, and the agent must have full context before starting any work. Do not skip this step.
• Confirm all original items in docs/checklist.md are checked.
• Pay special attention to docs/prd.md — especially "What we'd add with more time." These are natural starting points.
• Note the current architecture from docs/spec.md.
• Read process-notes.md — what happened during the build? Any issues, surprises, or things the learner mentioned wanting to fix?
• Skim the current app code to understand what actually got built (it may have drifted from the spec).
• Append a ## /iterate section to process-notes.md (or ## Iteration N if this isn't the first run).

Flow

1. Learner Describes What to Improve

Ask: "What do you want to work on? Could be a bug, a new feature, UX polish, or anything else."

Let them talk. Don't suggest things yet — hear what they care about first.

2. Quick Review Pass

Before jumping to a mini-checklist, do a quick review of the current state. This is the compressed version of scope→prd→spec — not re-doing those docs, just checking whether the ground shifted during the build.

Read the app code, the original spec, the PRD, and the checklist. Surface what you find:

• Did anything change during the build that affects the nice-to-haves in the PRD? Maybe the data model shifted, or a deferred feature is now trivial because the infrastructure is already there.
• Is the learner's requested improvement aligned with what's realistic given the current architecture?
• Are there quick wins they haven't thought of — things that would take 5 minutes because the scaffolding already exists?

Share 2-3 observations with the learner. Keep it brief — this is a check-in, not a new planning phase. "Based on what we built, adding search filters is actually easy now because the API already supports query params. But the social sharing feature would need a whole new auth flow — bigger than it looks."

3. Scope the Iteration Together

Interview the learner to nail down exactly what they want. One question at a time — draw out what they're picturing, what "done" looks like for this improvement.

If they want something that's too big, help them cut it down. "That's a great idea but it's probably an hour of work on its own. Want to do a simpler version first?"

4. Write the Mini-Checklist

Skip straight to a checklist — no scope/prd/spec cycle. 3-5 items max, using the same five-field format as the original checklist:

- [ ] **N. [Title]**
  Spec ref: `spec.md > [Section] > [Subsection]` (or "New — not in original spec")
  What to build: [...]
  Acceptance: [...]
  Verify: [...]

Append these to docs/checklist.md under an ## Iteration N header (where N increments with each /iterate run). This way /build's "find first unchecked item" logic naturally picks them up.

5. Hand Off to /build

"Your iteration items are added to the checklist. Run /clear, then run /build to start working through them."

The learner runs /build exactly as before — same mode, same verification preferences, same comprehension checks (if opted in). The iteration items just happen to be at the bottom of checklist.md under a new section header.

6. After Iteration Items Are Complete

When the learner comes back (or if they run /iterate again), note what was done:

"Want to keep going? Describe the next improvement and we'll do another round. Or run /reflect when you're done."

Process Notes

Append to process-notes.md:

• What improvement the learner chose and why
• What the review pass surfaced
• How many iteration items were created
• Any observations about how the learner is working with the agent now vs during the structured build

Conversation Style

Everything from the hackathon-guide SKILL.md interaction rules applies here, plus:

• This should feel lighter than the structured commands. The learner has earned autonomy. Be a collaborator, not a guide.
• The review pass is quick. 2-3 observations, not a full audit. Don't make the learner feel like they're back in planning mode.
• Respect their time. If they have 20 minutes left before the hackathon ends, don't propose a 5-item checklist. Scale to the time available.
• Keep handoff brief. Just tell them to run /clear, then /build.