Nuke Split

Nuke Split

A small helper: 0–1 agents, no preflight, no run_dir (map: references/family-map.md — it sits between the spec producers and nuke-exec). Weaker implementers fail on oversized work long before they fail on hard work — a worker handed five files and a vague boundary drowns in context it cannot hold. This helper re-cuts an existing spec (nuke-audit's or nuke-review's fix-spec, nuke-spec's build spec, or any file following references/fix-spec-template.md) as fine as its seams allow: one concern ≈ one file per sub-task is the target; the executing tier's budget is the ceiling, never the goal. The original file is never modified. nuke-exec applies this same protocol inline at preflight when its own re-measure finds oversized tasks; standalone split exists to pre-cut a spec before handing it to a foreign executor or a fresh session.

The ceilings below say how big a piece may EVER be; the target says how small to aim; the seam rules say WHERE the knife lands. All three bind — a cut that fits the ceiling but crosses a seam is a bad cut, and a multi-file task no seam forces is an uncut task.

Size ceilings — countable, per executing tier

Mirrors references/fix-spec-template.md rule 8 — the template's table is canonical; a divergence here is a bug.

The fine-cut target applies to clerk and worker; top passes through as specced. Knife direction, in order: file boundaries first, folder boundaries to group batches, regions (line ranges) only inside a single oversized file. A multi-file sub-task exists only where a seam forces it — a contract change ordered before its consumers, a definition traveling with its test.

Touched-file mass = sum of wc -l over the task's files (measure, never estimate from memory). An oversized file (a single file past the tier's line budget) is split by region: each sub-task names the file plus an explicit line range or symbol list (retry.ts:1-410 — the RetryQueue class), and gets its own mechanical Accept scoped to that region.

Seam rules — where the knife lands

1. Cut along dependency seams, never through them. When a parent task changes a contract (a signature, schema, export, config shape) and updates its consumers, the contract change is one sub-task and the consumers are others — and the contract sub-task comes FIRST. Order the sub-tasks so no sub-task depends on the output of a later one.
2. One concern per sub-task. A sub-task is describable in one sentence without "and". "Extract the backoff helper AND migrate poll.py to it" is two sub-tasks with an order between them.
3. A definition and its test travel together. The sub-task that adds or changes behavior carries the test that proves it — never a separate "write the tests" sub-task for behavior another sub-task built (a whole-parent test that cannot decompose follows protocol rule 3's duplication note instead).
4. Dependent sub-tasks never run side by side. Sub-tasks of one parent with an order between them go in the SAME batch (one implementer, executed in order) — or, when they cannot share a batch, into consecutive phases. Parallel batches are for independent work only.
5. Region cuts land on symbol boundaries. A line-range sub-task starts and ends at a whole declaration (class, function, section) — never mid-symbol; the range is chosen so its Accept can be verified without reading the other regions.

Protocol

1. Read the spec fully. Family spec (executor context, Gates table, phases, coverage map) → full protocol. Anything else — a plain task list, a TODO file — → degraded mode: apply the same budgets to a flat checklist, skip the coverage map step, and say so in the hand-back.
2. Measure every task: files touched, touched-file mass (wc -l, run now). Tasks already at the target — one concern, one file (or a seam-forced multi-file group), within ceiling — pass through byte-identical; splitting those is churn. Everything else gets the knife, oversized or not.
3. Re-cut everything above the target — seam rules first, ceiling second: pick the seams (dependency order, one concern each, definition+test together), then cut to one file per sub-task wherever the seams permit, then by region within oversized files. Every sub-task carries: its parent's finding/requirement IDs, its own files-or-regions list, and its own Accept — mechanical per the template's rule 1, scoped so the sub-tasks' Accepts together imply the parent's. A parent Accept that cannot be decomposed mechanically (one test covering the whole change) is duplicated onto the last sub-task and noted.
4. Re-batch: batches stay disjoint by file; two sub-tasks sharing a file share a batch; ordered sub-tasks share a batch or land in consecutive phases (seam rule 4); batch caps per the tier table. Phase order is never changed — splitting respects the template's dependency ordering.
5. Update the coverage map: every F-### / REQ-### / U-### that mapped to a split task now maps to all its sub-tasks. A coverage entry lost in the re-cut is a splitter bug — recount both sides before writing (parent map count == new map count).
6. Write <original-name>.split.md next to the original — same template, header gains split-from: <path> · budget: <tier> — and hand back: tasks before → after, batches before → after, the oversized files that forced region splits, and the line to run next: nuke exec <path>.split.md.

Mandates

• Read-only except the single .split.md output. No git commands, no source edits, no edits to the original spec.
• Never weaken an Accept: a sub-task inherits mechanical verification or the split is refused for that task — the hand-back names it and recommends the executing tier be raised instead.
• Counting over judgment: the target (one concern ≈ one file) and the ceilings above are the whole decision procedure; "this task feels big" is not a trigger and "it's probably fine" is not a pass.

When NOT to use

• The spec's tasks already sit at the target — single-concern, single-file (seam-forced groups aside) — run nuke-exec directly; a pass-through split is noise.
• The problem is ambiguity, not size (Accepts unclear, requirements contradictory) → nuke-spec territory; splitting a mushy task yields smaller mush.
• Sizing a NEW spec: the spec-architect should write right-sized tasks in the first place (references/fix-spec-template.md carries the same budgets); split exists for specs that arrive oversized.