Skip to main content

​
What happened

On 17 April 2026 I ran an 8-taskset migration that folded the external clari-tools services into the choco-hq monorepo (four Python services, four new proto domains, three NATS streams, landing page rebuild). The user supplied an internally consistent plan derived from five separate gists. Before writing the plan file, I spawned two parallel Explore agents: one against proto + infra layout, one against services + oompa spec + landing. Each returned in under 90 seconds with a bounded 400-word report. The reports surfaced seven deltas between the plan and the current repo:
  1. Metrics-port range 9097-9100 — blocked. choco-forge was already bound to 9097. Shifted to 9101-9104.
  2. Acceptance tests in the repo use REQ-* prefix, not OMP-*. Adopted composite REQ-OMP-*.
  3. oompa-spec.yaml domain values are Title Case, not SCREAMING_SNAKE. Renamed “FACTORY_INTELLIGENCE” to “Factory Intelligence”.
  4. Landing page had two extra stale components (waitlist-form.tsx, waitlist.tsx) the plan missed.
  5. Highest OMP ID was 9003, not 9999 as the plan implied — OMP-10001+ was safe.
  6. Common compose label was choco.dev/mythology: factory-component, not just the per-service choco.dev/oompa.
  7. YAML pre-existing parse error at oompa-spec.yaml:806 — confirmed upstream of the session, so the migration did not try to fix it.

​
Why the cheap step paid for itself

Each of the seven deltas would have surfaced during execution. A port collision lands at taskset 3 during docker compose config; the prefix mismatch lands at taskset 5 during just gherkin-check. Each catch is a 20-30 minute context rebuild plus a fix commit. The parallel agents caught all seven in about 90 seconds of wall time before a single file was touched.

​
The principle

Treat agent exploration as a cheap CI pass on the plan itself. The plan is a document that claims things about the repo. The agents verify the claims. When the claim is wrong, fix the document, not the downstream code.

​
Pattern to repeat

StepAction
1List every claim the plan makes about repo state (ports, names, file existence, ID ranges, convention prefixes).
2Partition into at most 3 exploration scopes.
3Launch all agents in one tool-call batch, capped at 400 words each.
4Fold the reconciliations into a Validation notes table at the top of the plan file.
5Only then call ExitPlanMode.

​
When NOT to apply

Trivial plans (single-file rename, typo fix) do not justify the overhead. The ROI scales with the blast radius of the plan.

​
Outcome

The session shipped 12 commits across 8 tasksets with zero rollback commits. No fix commits were needed after any taskset’s verification gate. All eight verification gates passed on first run.