Iteration Writing Guide (Test Execution -> Analysis -> Autonomous Fixing)

Goal and Positioning

• This guide is used for a single iteration: run tests for the first time -> analyze issues -> let Codex fix them autonomously -> retest and converge.
• The goal is to reduce human intervention and rapidly close the loop around the existing outputs of Draft / Plan / Code until the work reaches an acceptable state.

Inputs

• Plan document: technical acceptance checklist and execution order as the authoritative acceptance boundary
• Code document: record of implemented content and test cases that have not yet been executed
• Draft document: business semantics reference; if Draft conflicts with Plan, Plan takes precedence

Flow

1. Initial test execution

• Run the full test suite and collect statistics such as total / passed / failed / skipped / duration.
• Record failure details, including test identifier, error summary, and evidence such as log or screenshot paths.

2. Issue analysis and classification

• Locate root causes based on failed test cases and logs, and classify them by type such as function / logic / contract / performance / environment.
• Mark severity and impact range; when necessary, suggest test adjustments if the tests themselves do not match Plan acceptance.

3. Autonomous fixing

• Let Codex fix the issues autonomously while preserving readability and consistency. Synchronize contracts / types when needed.
• Run relevant tests as needed to verify the fixes and avoid unnecessary ripple changes.

4. Retest and convergence

• Rerun the full test suite and compare against the initial result to confirm that failures are cleared or that remaining blockers are explicitly identified.
• Run quality checks through pnpm, such as typecheck / lint / format:check, and record the results.

5. Output conclusion and filing

• Summarize the issues that are resolved, unresolved, or deferred, together with the reasons, and map the result to the Plan acceptance checklist.
• Produce an Iteration record document as input to Review.

Recording Points for Each Step (Used with the Template)

• Initial test result: statistics, failure list, evidence
• Issue analysis and classification: root cause, type, severity, impact range, and relation to Plan acceptance
• Fix implementation: change summary, involved files, related test identifiers, and contract / type synchronization if any
• Retest result: comparison statistics, remaining issues, and reasons
• Quality check (pnpm): summary of typecheck / lint / format:check
• Acceptance conclusion: coverage and conclusion for the Plan acceptance checklist; remaining items and follow-up suggestions

Definition of Done (DoD)

• The full test suite passes, or only explicitly marked and deferrable non-blocking items remain.
• Quality checks through pnpm pass for types, style, and formatting.
• Contract / type changes are synchronized and their impact is recorded; necessary Plan write-backs are produced.
• The Iteration document is complete and can be used directly in Review.

Output and Filing

• At the end of the iteration, output the Iteration document using the template and provide an execution summary briefing.
• If blockers still remain, provide the minimum suggested next action and clarify whether the next step is another Iteration or a Review entry checklist.