wave-based-dispatch

What this skill does

# Wave-Based Dispatch

The agent-side dispatch discipline for sequential WO chains. Same pillars as
`parallel-agent-dispatch` — disjoint ownership, return contracts, shared-file
exclusion — but the gates **between** waves are different from the gates
**inside** a wave. This skill is those between-wave gates.

## When to Use This Skill

| Use wave-based dispatch when… | Use `parallel-agent-dispatch` alone when… | Use `exclusive-lock-dispatch` when… |
|-------------------------------|-------------------------------------------|--------------------------------------|
| A later WO needs a file, type, or API the earlier WO defines | All WOs operate on disjoint, lock-free scopes | One tool holds an exclusive lock and N agents need its outputs |
| A research probe (Ghidra decomp, spec experiment, API trace) gates downstream scope | Scope is fully known up front | Lock-holder is slow enough to amortise via pre-dump |
| Two candidate agents would both modify the same shared manifest / tracker / build file | Shared-file exclusion list is small and stable | Pre-computed artefacts can replace re-running the lock holder |
| A bug surfaced during orchestrator-apply needs the same context as the dispatched agent | Issues are recoverable inside a single wave | Lock contention is the only sequencing reason |

The three skills compose: each wave is itself a `parallel-agent-dispatch`,
lock-holding waves use `exclusive-lock-dispatch` for the pre-dump, and
this skill covers the boundary between waves.

## Picking Wave-Based Over Parallel

| Trigger | Why parallel fails | Wave-based response |
|---------|---------------------|---------------------|
| **Dependency chain** — WO-B imports types from WO-A | WO-B's brief is stale before WO-A lands; the agent guesses or stalls | WO-A in wave 1, WO-B in wave 2 referencing WO-A's landed paths |
| **Shared lock** — Ghidra project, taskwarrior bulk modify, single-writer cache | Second concurrent invocation fails with a lock error; orchestrator burns a turn diagnosing | Lock holder runs alone in its wave; downstream waves read pre-dumped artefacts |
| **Orchestrator-edit contention** — multiple agents return verbatim patches against the same `CMakeLists.txt` / `justfile` / manifest | Last-writer-wins silently loses the earlier edit; merge conflicts pile up at apply time | Stage edits to those files between waves so the orchestrator applies them serially |

If any trigger matches, the work belongs in waves. Inside each wave,
`parallel-agent-dispatch` still applies as the per-agent contract.

## The Research-Before-WO Gate

When the scope of a downstream WO depends on information that only a tool
run can produce — Ghidra decomp, a live API trace, the actual structure
of a binary format, a benchmark — run that probe as **its own first wave**
before the implementation WO is written.

The reason is concrete: the implementation WO's *size* collapses once
the probe lands. A WO scoped as "unknown — possibly days, depends on the
binary's actual layout" turns into "plumb a known pointer from offset
0x40 to the existing decoder, hours" once the research wave produces a
spec artefact. Writing the brief before the research lands locks in the
worst-case framing and the agent burns its window re-deriving the
information.

Process:

1. Wave 1 brief asks the probe agent to write findings to gitignored
   scratch (`tmp/research/format-spec.md`, `tmp/decomp/strings.txt`,
   `tmp/api/probe-results.json`).
2. Probe agent returns a Return Contract that lists the artefact paths.
3. Implementation WO is written **after** wave 1 closes, citing those
   paths verbatim and forbidding re-running the probe.
4. If the artefacts are insufficient, the implementation agent returns
   `partial` with the missing question in `Orchestrator action needed`,
   and the orchestrator dispatches a follow-up probe wave rather than
   letting the implementation agent improvise.

See `agent-patterns-plugin:exclusive-lock-dispatch` when the probe tool
holds an exclusive lock — the pre-dump mechanics there are the right
shape for the research wave's brief.

## The Pilot-Before-Fan-Out Gate

When the **same transformation** will be applied to N items (repos, files,
packages, services), validate the whole recipe on **one representative
pilot end-to-end — including the riskiest unknown — before fanning out**.
Wave 1 is the pilot; wave 2 is the fan-out, and it *mirrors* the landed
pilot rather than re-deriving the recipe N times in parallel.

The reason is concrete: a parallel fan-out over an unvalidated recipe
multiplies a single wrong assumption into N broken outputs, and you pay
for all N before discovering the flaw. Proving it once converts the
fan-out agents' job from "figure out how" to "replicate this exact,
working example" — which is both cheaper and far more reliable.

Process:

1. **Wave 1 = the pilot.** Pick the *simplest representative* item. Do
   the full transformation, and explicitly confirm the **load-bearing
   unknown** — the one thing that, if it didn't work, would invalidate
   the entire approach (a build externalization, an API contract, a
   migration codemod's output).
2. **Gate.** The pilot's own gates (build/test/lint) must pass **and**
   the risky unknown must be confirmed before any fan-out brief is
   written.
3. **Wave 2 = the fan-out.** Each agent is told to mirror the landed
   pilot — cite its path verbatim as the reference implementation — with
   per-item detection only for the parts that genuinely vary.
4. **If the pilot reveals the approach is wrong, re-plan.** Cheap,
   because only one item was touched.

Distinct from the Research-Before-WO Gate above: research produces a
*spec / artefact* to scope an unknown ("what should we build?"); a pilot
produces a *working reference implementation* of a repeatable change
("we know what to build — is the recipe sound, and does the risky step
actually work?"). Reach for research when the scope is unknown; reach for
a pilot when the scope is known but the recipe is unproven.

## Six-Gate Verification Table Between Waves

No brief for wave N+1 is written until wave N's gates pass. The gate set
is fixed — drifting the gates between waves is how regressions slip in.

| # | Gate | Signal | Why it matters between waves |
|---|------|--------|------------------------------|
| 1 | Build | Project compile / typecheck recipe succeeds | Wave N+1 will import wave N's symbols; broken build poisons the next brief |
| 2 | Tests | Project test recipe succeeds (with the wave's flag set when applicable) | Hidden regressions compound across waves |
| 3 | Module smoke | Module-level smoke recipes (CLI subcommand smoke, `tools-plugin:cli-smoke-recipes`) pass | Catches integration breaks the unit tests miss |
| 4 | Taskwarrior status | Tasks for the wave drain to `done`; no orphans | Wave N's queue must be empty before wave N+1's tasks are filed |
| 5 | Feature-tracker drain | Tracker entries touched by the wave advance from `in progress` to `done`, with evidence pointers | Sidecar status survives the session; the next wave can cite landed work |
| 6 | Clean tree | `git status --porcelain` empty | Loose ends become invisible work after the next wave lands on top |

A gate failure rolls back to **fix in place, retry the gate** — never to
"dispatch wave N+1 and paper over it." If the wave is unrecoverable,
revert it and re-brief.

## The ~10-Line Inline-Fix Threshold

When a wave returns and a small bug surfaces during the orchestrator's
apply step, the orchestrator has a choice: fix it inline, or file a
follow-up WO for the next wave. The threshold is approximate but
load-bearing:

| Situation | Decision |
|-----------|----------|
| ~10 lines of fix, orchestrator already has the symbolic context | Fix inline |
| Fix spans multiple files or needs the agent's exploration log | Follow-up WO in the next wave |
| Fix is mechanical (rename, reformat, missing import) | Fix inline |
| Fix requires a design judgement | Follow-up WO