--- name: five-phase-build description: Plan, build, integrate, and verify substantial features through evidence-driven phases and fix waves. version: 1.0.0 updated: 2026-08-14 --- # Five-Phase Build ## Phase 0 — Research Read the repository instructions, current code, tests, data flow, design sources, and original user request. Use independent read-only research lanes when the work splits cleanly. Record facts, unknowns, constraints, and current behavior. Do not plan from summaries when primary artifacts are available. Write the source obligation before a large search or compute run: exact input, required output, governing contract or theorem shape, stress/failure model, and the decisive evidence. Search existing internal results and deduplicate semantically equivalent obligations before launching new work. Use `research-harness` when the problem is exploratory or proof-like. ## Phase 1 — Plan and rubric Write a durable plan before substantial implementation. Include: - dependency-ordered build steps and concrete file areas; - disjoint ownership boundaries; - user stories for every relevant role; - refresh, retry, offline/network failure, partial completion, persistence, permissions, and device-specific cases; - measurable definitions of done and the evidence each requires; - questions only for decisions that cannot be resolved safely from context. For high-risk or architectural work, have two independent clean-context max-effort reviewers challenge the plan. Anything flagged for review goes to a clean-context twin; the orchestrator's own reading is not a substitute. Fold every finding into a revision and repeat until both pass or report the unresolved disagreement. ## Phase 2 — Build Build in dependency-ordered waves with Codex `gpt-5.6-sol` at low effort. Each worker owns bounded files, preserves concurrent edits and commits, implements tests for its slice, and reports evidence and risk. Keep expensive jobs within machine limits, including the 1 GB disk floor on every machine in use. Do not use broad checks as a substitute for targeted feedback during iteration. ## Phase 3 — Integrate Review cross-package contracts, machine-produced artifacts, routes, schema, state, permissions, errors, and shared UI behavior. Run focused tests first, then broader safe checks when proportionate and authorized. Resolve collisions deliberately; do not assume worker output composes automatically. ## Phase 4 — Real-user verification Map every planned story to a real user flow. Use a real browser for UI behavior, relevant personas, desktop and mobile viewports, and real infrastructure when safe and currently authorized. Capture key states—approximately once per second for changing flows—and assemble labeled contact sheets. Inspect every frame yourself. For provider/media/storage/streaming/payment/notification work, prove the real round trip only with current spend and production authority: live response, persisted audit state, derivatives or downstream artifacts, served bytes and content type, browser rendering, timing, retries, and failure behavior. Measure the served model from upstream rather than echoing the request, and reject buffer-then-replay as fake streaming. Otherwise mark it unverified. Run route, asset, metadata, and middleware checks through the production start command and production entrypoint; development servers can mask upstream interception. Keep the verification ledger append-only. Retain original timestamps, identifiers, attribution, licenses, and failed observations; record corrections as new, linked evidence. If the product exposes analytics or download counts, test authorization and ownership boundaries as well as numeric accuracy. ## Phase 5 — Independent verdict and fix waves Give two independent clean-context max-effort verifiers the plan, evidence, and relevant primary artifacts. They judge the built reality, not the builder's report. The orchestrator's own inspection is a third check, never a substitute. Any failure creates a bounded fix wave scoped to the findings, followed by fresh E2E evidence and fresh clean-context review. Repeat until all required checks pass. Finish only when required work is integrated, evidence is inspected, reviewers converge where required, a focused commit is landed and synchronized at the deploy source when in scope, and the durable handoff is complete. Publishing and production confirmation remain separate explicit-authority gates. ## Universal wave contract and keeper Every build wave, without exception, owns its verification before it reports. At the end of the same wave, re-read the original human prompt, its phase-0 user story, and the final specification; run the E2E flow for the work just built; capture the four tutorial variants where that infrastructure exists, or at minimum a real-flow recording plus one-second contact sheets; validate that all captured frame MD5 values are distinct; and self-score every story and final-spec step against named evidence. Run the relevant regression suite too. Capture is part of the build wave, never a later evidence wave. Write `docs/evidence/receipts/.md` using the one canonical [evidence receipt schema](../tutorial-verified-done/references/evidence-receipt-schema.md). A report without a schema-valid receipt is `FAIL` by definition. The keeper continuously reconciles workers and receipts. A dead wave is relaunched only for its uncompleted remainder. A failed capture is re-captured before unrelated work begins. A missing or invalid receipt, or any twin `FAIL`, starts an automatic rework wave limited to the validator or twin findings; after repair, rerun the affected E2E capture, regressions, receipt gate, and clean- context twins. Route around reversible technical blockers. Escalate only an exact external boundary: a publish click, physical device, missing credential, current spend authority, production mutation, outbound communication, destructive action, or human values decision. For long runs, persist checkpoints, leases, and resume instructions. Age alone is not evidence that a run is stuck; do not terminate a productive deep run without a verified failure or resource-safety reason. ## Source IDs and tutorial completion Assign every requirement a stable ID linked to its raw source turn, transcript, or microphone submission. Plans and reviewers reconcile against those primary bytes, not only a summary. At the completion of every five-phase build, apply `tutorial-verified-done`: project each phase-0 story step into layperson narration with zero technical detail, a visible action, and a visible outcome; render narrated desktop/mobile light/dark tutorial variants; and preserve one-second frames, four contact sheets, four audio-derived transcripts, checksums, and served-artifact identity. Any failed, stale, empty, dead-end, visually divergent, or transcript-mismatched run requires repair and a full affected-flow re-record. Validators and loose media alone are not proof. End every phase receipt with an R/E/K/Ce decision: recovery and verification state, cheapest capable method, user-time and surprise impact, tradeoffs, and the most valuable next item. Evidence receipts use the canonical schema linked above; do not restate or fork it.