Run Iter

Own the iteration from a useful choice to an evidence-backed result. This is one skill with internal phases; read only the reference for the current phase.

Start with a useful choice

1. Locate the workspace and read applicable repository instructions. Inspect the product, relevant implementation, available tests, and applicable open-source options. Without a Git root, use the user's workspace directory.
2. Run paths --workspace "<workspace>" and status using the loaded helper. These reads do not create storage; status reports exists: false when no external state exists. If migration_required is true, handle the legacy cycle with explicit migrate before continuing; do not initialize over it. Resume unfinished active work without replacing its objective or repeating the menu. After complete or stopped, treat the next iteration request as a new iteration by default, including a bare skill invocation or "continue iterating". Do not require the user to say "start another iteration". Present fresh choices, or use the feature already specified, then use init --new-cycle with the selected proposal and its grants, preserving the old cycle. An explicit request to inspect or discuss the previous result only reads that result; it does not start new work.
3. For a new open-ended iteration, do a lightweight repository review and present 2–3 concrete feature improvements before an exhaustive market survey. Each needs a user benefit, observed problem, smallest scope, metric/acceptance, validation method, main risk, and tradeoff. Recommend one with a reason; mark unmeasured baselines and assumptions honestly.
4. If the user specified a feature, focus on it instead of inventing alternatives. An under-specified direction authorizes investigation, not an unpresented implementation scope.
5. For a new choice, explain that selection authorizes its listed implementation scope. Describe proposed local scenarios, data scope, possible changes, and recovery. Reuse authorization already given in the user's request or conversation; ask only for a missing permission or a material change. Implementation and local testing are separate grants that can be answered together.
6. After selection, initialize with the chosen proposal and only the permissions actually granted. Pass --language en or --language zh-CN to match the conversation; CLI defaults to English. Save the proposal and grants together so interruption does not cause repeated approval questions. See state-schema.md for the proposal and CLI.

Do not require five users, a fixed participant count, or participant recruitment merely to start. When feedback is absent or sparse, offer isolated local scenarios and gather useful repository, competitor, or community evidence. Local scenario success leaves real-user value unverified.

Resume and advance

Resolve <skill-dir> to this loaded skill's directory, not the workspace or a cached absolute path. Keep its scripts, references, and assets together. Use the host's available file, shell, browser, and user-question tools; a plain conversation question works without a dedicated question tool. Python 3.10+ runs the helper with no third-party packages. Use the available Python command (python3, python, or Windows py -3), verify its version, and quote paths. Node.js is needed only for optional installation tooling or the DeepSeek adapter. If a capability is missing, finish independent work and identify the precise remaining need.

python3 "<skill-dir>/scripts/product_loop.py" paths --workspace "<workspace>"
python3 "<skill-dir>/scripts/product_loop.py" status --workspace "<workspace>"

Use the returned storage_root, state_path, inputs_dir, and evidence_dir; do not construct them from the project name or create .product-loop/. Storage defaults to ~/.iter, or an absolute external ITER_HOME, and is isolated by the resolved workspace path. Save proposal/execution JSON in inputs_dir and generated logs in evidence_dir; keep existing user evidence in place. Obtain the host's required write access to this exact storage_root, reusing existing permissions where applicable. If access is unavailable, report the path and blocker without falling back to project storage. Migration, schema version 2, and relocate after a workspace move are described in state-schema.md.

Read workflow-contract.md and the current phase guide, produce its artifact, validate, advance, and immediately continue in the same invocation:

python3 "<skill-dir>/scripts/product_loop.py" validate --workspace "<workspace>"
python3 "<skill-dir>/scripts/product_loop.py" advance --workspace "<workspace>"

At approval, reuse the saved grant for the unchanged concrete proposal. Do not ask again simply because this phase was reached. If no matching grant exists, present the concrete decision and record the user's response before development. Simulation permission alone does not authorize implementation; implementation permission alone does not authorize local data operations.

When the user asks to start development, carry the authorized scope through implementation, necessary verification, and evaluation in the same run. Close the cycle automatically once the work is finished; do not leave it at development or evaluation awaiting another completion request. Use advance --outcome complete when the approved contract passes. Record unresolved failures or blockers honestly and use evaluation's stop outcome when no authorized executable next step remains; an ended cycle need not be a successful one.

At evaluation, use advance --outcome complete|iterate|stop with the report's verdict. Default to one delivery cycle. Use iterate only when the user explicitly requested multiple automatic rounds and a bounded follow-up fits the remaining budget and authorization. A generic "continue iterating" requests one delivery cycle. In the run that reaches complete or stopped, report the outcome and evidence limits, then end the run without asking the user to close it or starting another cycle automatically. A subsequent iteration request follows the new-cycle default above. Completion does not authorize publication or release.

When the user cancels or rejects the iteration, use stop --workspace "<workspace>" --rationale "<reason>" --evidence "<actual user decision>" immediately. This works at any active phase without finishing reports or obtaining implementation permission. Preserve the existing artifacts; a later iteration request follows the new-cycle default. Pausing to resume later is not cancellation. advance --outcome is only for evaluation.

Keep the cycle's saved report language. Old states without language use Chinese; new templates and status provide the expected headings and local-completion sentence. Reference guides are in English, but user-facing discussion and reports follow the selected language.

Pause only for a material decision

Keep progressing through repairable validation failures, deterministic phase changes, and routine implementation choices. Preserve the user's direction even when scoring prefers another option. Research may enrich evidence without reopening approval.

Ask when scope, metric target, acceptance, validation mode, data operations, or material risk changes beyond the grant; show the actual revision and its consequences. Use revise rather than silently changing an approved experiment or state file. Reuse granted permissions within their recorded scope.

Pause only when a material user decision or unavailable necessary authority/access prevents further progress, including truthful cycle closure. When evidence is exhausted or the round budget is reached, record the limits and close through evaluation. Respect separate authorization for production release, pricing, permissions, destructive changes, and communication to others.

Evidence means what it proves

• product_metric evaluates the agreed product outcome with appropriate observed data; it has no universal minimum participant count.
• local_scenario evaluates agreed tasks in the actual application or execution path, using isolated samples or copies by default. Research may contain a baseline plan and pending results; completion requires real execution evidence.
• Record failed or blocked execution and move to evaluation. Missing evidence cannot become success; it can justify iterate or stop.
• For local completion, visibly include the local_completion_limit sentence from status: Local scenarios passed; real-user value remains unvalidated. in English, or 本机场景验证通过；真实用户价值待验证 in Chinese. Imagined personas, passing lint, and feature delivery do not prove real-user demand.