| 1 | Ultracode run crashed instantly: ReferenceError: meta is not defined | The export const meta literal is NOT in scope in the script body. | Template uses a local PHASE_TITLES array; never reference meta.* in the body. |
| 2 | A big phase (5-6 clients + tests) ran ~21 min, hit its turn budget, errored without returning, and the ultracode run retried it 3x in a loop, each retry inheriting a half-edited tree. | One agent given too much work; a thrown agent() with no guard gets retried indefinitely. | (a) Split oversized phases into bounded sub-phases; (b) return-discipline prompt (return a partial, never run to death); (c) try/catch around each agent() so a throw STOPS the run cleanly. |
| 3 | Another big phase did all the work (100+ tool calls) but never called StructuredOutput -> error. | Same budget overrun, just after finishing. | Recovery insight in the runbook: the work is usually already on disk, verify green + tick boxes instead of re-running. Plus splitting prevents it. |
| 4 | An agent reported build=pass but had left a compile error (referenced a struct field it forgot to add). | Agents self-report from a stale build; the stop-on-block guard trusted the report. | Orchestrator runs independent go build/vet/test after each backend block and at the end. Never trust self-reported green for the final gate. |
| 5 | A transient broken-test diagnostic appeared mid-run (a constructor signature changed but its test not yet updated). | A file-edit race: reading/seeing the tree while an agent was mid-edit. | Rule: never edit (and distrust transient diagnostics of) the tree while the ultracode run is live. Stop first, or wait for the phase to finish, then verify the settled state. |
| 6 | A config key was needed by phase 5 but the spec "added" it in phase 7. | Cross-phase config dependency. | Assign each config key to its first consumer sub-phase, which adds it + runs the config-sync step; later phases only verify. |
| 7 | Risk of agents running DB migrations / hitting prod. | Migration left to a phase agent. | You apply the migration up front (DEV only by default), save the file, and tell every agent "already applied, do not re-apply, do not touch prod." |
| 8 | New test describe() labels used em-dashes (matching a pre-existing codebase convention), violating the hard rule. | Agents match surrounding code, which already breaks the rule. | Final em-dash scan on i18n + new files; fix only NEW occurrences; do not churn pre-existing ones. |
| 9 | When a phase was split or hand-recovered, the spec's Execution-Plan summary checkbox was left unticked. | No sub-agent owns the summary line. | Orchestrator reconciles spec checkboxes in Step 8. |
| 10 | go test ./... recompiles the whole module; agents re-running it after every edit burned their budget. | Inefficient verification loop. | Efficiency rule in the prompt: targeted tests during dev, full gate ONCE at the end. |
