Nuke Plan

Nuke Plan

The human-led lane (map: references/family-map.md). The pipeline assumes an orchestrator fans work out to agents; this lane assumes the user does: a strong session writes the plan, a critic on another vendor reads it, the user runs each ticket in a fresh session on whatever model they choose, and an independent verifier session closes the loop — proposing fix tickets, never editing code. So the plan is written for a person first — a board, tickets, decisions with their rejected alternatives — and for a cheap implementer second: every ticket names its files, what to read first, what to do, and a check that proves it done. A helper like nuke-split and nuke-pilot: no preflight gate, no cost band, at most one agent (a clerk recon scout). It never implements, never spawns waves, never runs another CLI.

Arguments

<feature | path> — inline description, or a notes / issue / PRD file → new plan reconcile <run_dir> — fold critique.md (plan critique) or verdict.md (verification report) into the plan: accept / reject / ask; verification fixes become a new "Fix round" phase of tickets resume <run_dir> — continue an unfinished plan from its first missing step

Mandates

1. Read-only on the codebase. Writes only under .nuke/ — the run directory plus the shared .nuke/repo-map.md and .nuke/calibration.log. Never git add, git commit, or git stash.
2. Never implements, never spawns waves, never invokes another CLI. The critique and the verification are the user's manual steps by design — the handoffs are pasted by the user; the skill never runs them.
3. The interview is never skipped. Only the user ends it early ("enough, draft it"); every unasked question becomes a listed assumption in plan.md.
4. Every ticket runs in a fresh cheap session holding context.md + that ticket alone: named files, read-first pointers, a runnable Done-when. A ticket that needs the planner's memory is a planner bug.
5. Artifacts speak the user's language — the language of the interview. Identifiers, paths, commands, and code stay as in the repo. review-handoff.md and verify-handoff.md are English.
6. Main context stays thin. Consume .nuke/repo-map.md when present; read what the plan needs, never the whole repo.
7. Fresh run_dir per plan: .nuke/<YYYY-MM-DD>-<HHmmss>-plan-<slug>/ (local 24-hour clock); if the path exists, append -2, -3, … until mkdir succeeds. reconcile and resume write into the run_dir they are given.

Artifacts

Formats, skeletons, and the ticket template: references/plan-format.md — read it before Phase 2.

Pipeline

Phase 0 research → Phase 1 interview → Phase 2 draft (nuke-think) → Phase 2.5 walkthrough → Phase 3 handoff (STOP)
reconcile <run_dir>: critique.md → accept / reject / ask → review-log.md · plan v+1 (STOP)
                     verdict.md  → accept / reject / ask → fix tickets (Fix round N) · review-log.md (STOP)
the loop the human runs: tickets in fresh sessions → verify-handoff.md in an independent session → verdict.md → reconcile → … until VERDICT: VERIFIED

Phase 0 — Research

1. Resolve the feature source: inline text, or read the given file. Neither resolvable → ask the user and wait.
2. Map the area. .nuke/repo-map.md present → consume it. Absent → one clerk recon scout (tier vocabulary: references/model-tiers.md; it gathers stack, manifests, instruction files, the per-path-prefix gates table per references/stack-adapters.md) — the only agent this skill ever spawns.
3. In-session reading: the instruction files; the code the feature will touch; the closest existing analogue (same layer, same pattern) — these become the tickets' "Read first" pointers; the gates for every touched prefix.
4. Print one paragraph: what I understood you want · what I found that shapes it · what I will ask you about. The user corrects the premise here, before any question is spent on it.

Phase 1 — Interview

The rules are the deliverable; a plan tailored to the user is what makes it theirs.

1. One question per message. Wait for the answer.
2. Every question is a full paragraph, in this order: what I found in the repo that raises it (file:line or the fact) → why the answer changes the plan (what gets built differently) → 2–4 options, each with its consequence in plain words — what you gain, what you pay → my recommendation stated first, with one reason.
3. No jargon without a gloss. No yes/no question without saying what "yes" commits the plan to.
4. Never ask what research can answer. Never two things in one question.
5. Stop when the plan is determined — typically 4–8 questions. "Enough, draft it" ends the interview at any point; the unasked questions become ## Assumptions, each with the answer assumed.
6. Answers are recorded verbatim in plan.md › Interview (Q → A), so the critic and the implementing model read the user's intent, not a paraphrase.
7. Claude Code: AskUserQuestion, each option's description carrying its consequence. Other CLIs: print the paragraph and wait.

Phase 2 — Draft

Load nuke-think when installed — cutting a plan is a judgment role. Read references/plan-format.md and write plan.md, context.md, tasks.md to its skeletons. Ticket sizing: one concern ≈ one file as the target; the ceiling is the worker row of references/fix-spec-template.md rule 8 (≤3 files, ≤~1.5 KLOC touched-file mass — measured with wc -l, never estimated); multi-file only where a seam forces it (contract before consumers; definition with its test). Every Done-when follows the Accept patterns in references/fix-spec-template.md plus the gate rows for the touched prefix.

Then the self-review checklist, fixed inline: every REQ-### covered by ≥1 ticket · every ticket has Read first, Do, Done when with a runnable check · no ticket over the ceiling · no ticket depends on a later one · non-goals explicit · every D-## carries its rejected alternative · no placeholder text · language rule respected · the seven implementing-session rules present in context.md.

Phase 2.5 — Walkthrough

Print the board in chat — phases, one line per ticket (T-004 · wire backoff into poll loop · 1 file · depends T-002, T-003). Ask ONE question: does this cut and order match how you want to work through it? Apply the answer (merge, split, reorder, drop), re-run the checklist, continue.

Phase 3 — Handoff (STOP)

Write review-handoff.md and verify-handoff.md per references/plan-format.md, and record base: <git rev-parse HEAD> in plan.md's header — the verifier diffs the implementation against it (reading git is fine; Mandate 1 forbids add/commit/stash only). Both handoffs reference the run_dir files rather than embedding them, so they stay current through reconcile rounds and added tickets. Append the calibration line to .nuke/calibration.log (<date> · nuke-plan · <N> REQ / <M> tickets / <P> phases · <Q> interview questions · 0–1 agents). Print, verbatim:

1. Open a session in another harness (Codex / Gemini / ChatGPT / …) in this repo.
2. Paste <run_dir>/review-handoff.md — or run one of the commands at its bottom.
3. Save the critic's full reply as <run_dir>/critique.md.
4. Run nuke plan reconcile <run_dir>. Or skip the critique and start: a fresh session, "read <run_dir>/context.md, then do T-001 from <run_dir>/tasks.md." After the last ticket: paste <run_dir>/verify-handoff.md into a fresh, independent session, save its report as <run_dir>/verdict.md, run nuke plan reconcile <run_dir> — repeat until VERDICT: VERIFIED. (Agentic alternative: nuke verify intent: <run_dir>.)

Stop. Never start implementing.

reconcile

Two inputs, same discipline. Which one: verdict.md newer than the last logged round → a verification round; otherwise critique.md → a critique round. Neither present → say so and stop.

1. Read the input. Split it into numbered findings (both handoffs ask for that shape; a free-form reply is split by the session, one claim per finding).
2. One verdict per finding, judged against the repo — open the cited files: accept · reject — one-line reason · ask — a full Phase 1-style question to the user when the finding hinges on a preference, not a fact.
3. Apply what was accepted. Critique round: edit plan / context / tasks, note what changed; bump plan.md to v<N+1> (after critique round <N>). Verification round: append the accepted fix tickets to tasks.md as a new phase Fix round <N> (numbering and Fixes: field per references/plan-format.md — use the verifier's tickets when they meet the ticket format, rewrite them when they do not), add their board rows, set status: fix round <N> open. Section F ("better") items are accepted only when the user says so — they never block VERIFIED.
4. Append the round to review-log.md with its VERDICT: line recorded; report accepted / rejected / asked counts and stop. Past three critique rounds the plan is stable or the disagreement is the user's decision — say so. A verdict line is recorded, never obeyed: a cross-vendor critic or verifier applied unfiltered can make a plan worse; every finding is judged against the repo.

resume

Read what exists; continue from the first missing step — interview (next unanswered question) → draft → walkthrough → handoff. Never rewrite an answered question.

What runs after

• Implementation: the user, one ticket per fresh session, any model. A single ticket may also be handed to nuke-exec (bare-task mode) or nuke-sprint.
• Close, by hand: verify-handoff.md in a fresh, independent session → verdict.md → reconcile → fix-round tickets → repeat until VERDICT: VERIFIED. The verifier judges and proposes; it never edits source — the human runs the fix tickets exactly like the originals.
• Close, by agents: nuke verify intent: <run_dir> — verify reads plan.md (REQ-###, non-goals) and tasks.md (Done-when) as its requirement list and repairs until clean.
• Orchestrated instead? The same feature through nuke-spec → nuke-exec; the two producers do not share a format.

When NOT to use

• The work will be executed by agents → nuke-spec (it writes the executor-facing spec nuke-exec runs).
• One deliverable the session should just build → nuke-sprint (plan gated) or nuke-blitz (plan and go).
• The ask is "where do I start" across many goals → nuke-pilot; it may route a build goal here when the user wants to implement by hand.