Nuke Lean

Nuke Lean

A discipline like nuke-think, not a ceremony: no agents, no artifacts, no confirmation gate (map: references/family-map.md). One doctrine at three moments: design-time (choose the simplest shape that meets today's ask), write-time (the contract below, checked against the diff), and sweep-time (walk an existing diff and delete what fails — invocable on its own as nuke lean <scope> or "deslop this"). Implementer roles in other nuke skills load it as their charter. It deepens nuke-code's BUILD charter — minimal diff, no defensive noise — into a contract you can check a diff against. It never overrides the constitution's ship rule: lean code still carries gates and a validator's verdict.

Scope — lean counts lines in the diff, never agents in the process

Lean governs what the code IS, not how the work is orchestrated. Everything the ask or an engaged loop mandates about process — subagents, workflows, ceremonies, validators, gates, preflights — is outside lean's jurisdiction and is never stripped in its name. The user asked for the work to run in workflows? Then workflows are part of the ask (rule 1 protects them), and doing it in the main context instead is a scope violation, not leanness. "Fewer agents" is not "leaner code"; the two measures never trade against each other.

Design-time — the shortest sound path

Engaged whenever solution shapes are being weighed (nuke-code's THINK, a spec's design phase, any "how should I build this"):

1. Pick the simplest shape that satisfies today's done-criteria. Every layer, abstraction, option, and indirection in the chosen shape must be required by a named criterion that exists now. The future is not a criterion: "we might need to swap the backend", "this could become multi-tenant" justify nothing today.
2. Shortest path ≠ outdated path. Lean means the current idiom of the stack applied directly — the modern API, the standard library solution, the framework's intended mechanism — with no extra structure around it. Reaching for a legacy pattern because it is familiar is not lean; wrapping the modern one in a compatibility layer is not sound.
3. A simpler shape that fails a done-criterion is not a candidate. Lean never trims the ask itself — it trims everything around it.

The contract — what lean code IS

Check every numbered rule against the diff. Each is countable; none is a judgment call.

1. The diff answers the ask and nothing else. Lines changed outside the ask's scope: zero. Renames, reformats, and refactors of untouched code: zero. The ask includes everything the engaged loop mandates in the same diff — a behavior test for changed behavior, the decision note — and everything the user said about how to run the work. Lean strips speculation, never mandated deliverables and never the requested process.
2. Validation exists exactly at trust boundaries. A trust boundary is where data enters the process: user input, network responses, file contents, env/argv, third-party API returns. One check per boundary, at the boundary. Internal functions trust their callers — a value validated at the boundary is never re-validated downstream.
3. Every check names its triggering input — the concrete value that reaches this line and makes it fire. A check whose triggering input you cannot name is deleted.
4. Error handling exists only where a recovery action exists. No try/catch around operations that cannot fail; no catch that only logs when nothing continues past it — log-and-continue over a batch's remaining items IS a recovery.
5. An abstraction requires ≥3 concrete call sites existing today; otherwise inline. A config option, flag, or parameter requires a second real value needed today; otherwise hardcode.
6. Fallbacks never mask failures. A ?? default on a value that should always exist hides a bug — let it surface.

Security is boundary work, not decoration

This skill is anti-theater, not anti-security. Real surfaces — auth/authz, injection sinks, crypto, secrets — get real treatment ONCE, at the surface. Duplicated sanitization on internal hops is the theater being deleted, not the protection. Unsure whether something is a real boundary? That is a judgment call — nuke-think territory — never a reason to add a second check.

The sweep

Two entry points, one procedure:

• Self-sweep (after writing under the charter): re-read your own diff hunting your own additions against the contract, then emit the sweep line in the hand-back.
• Invoked sweep (nuke lean [changed|staged|<path>], "deslop this"): walk any diff — this session's or a cheaper model's before it — the same way. Scope is the changed lines and what they touch, never the whole repo: repo-wide hunting is nuke-audit's job.

Walk the diff (git diff, re-read from disk — never from memory) hunting:

1. Contract violations — anything failing rules 1–6 above: out-of-scope changes, off-boundary validation, unnameable checks, recovery-free try/catch, single-caller helpers, one-shape options objects, failure-masking fallbacks.
2. Narrating comments — restating the code below them, or talking to the reviewer ("added X to fix Y"). A comment survives only by stating a constraint the code cannot.
3. Debug leftovers — print/console/log lines added for the task, probes, temp files, commented-out attempts.
4. Speculative exports — exports nothing imports (grep to confirm before deleting).
5. AI-voice naming — enhanced/robust/improved/comprehensive/graceful identifiers renamed to what the thing does.
6. Type escapes introduced by the diff — the language's vocabulary per references/stack-adapters.md table B; fix the type or justify the escape in one comment, never leave it bare.

Deletion discipline: grep before deleting anything referenced elsewhere; behavior is never changed — a sweep edit that would alter behavior is out of scope and reported instead. After a sweep with deletions, run the narrowest matching gate — a sweep that broke the build is worse than no sweep; the gate line is part of the hand-back.

State the result in the hand-back, always:

lean sweep: 4 deletions, 1 rename
- retry.ts:12 — comment restated the call below it
- retry.ts:30-38 — try/catch, no recovery path
- api.ts:7 — console.log leftover
- utils.ts:44 — helper with one caller, inlined
- fetchDataRobustly → fetchWithRetry
gates: pnpm test → 31 passed (unchanged)

or lean sweep: clean. A hand-back without the sweep line skipped the sweep.

Rationalizations

Red flags — stop and sweep

• A null check on a value you just produced.
• A second sanitization of an input already sanitized at its boundary.
• A helper with one caller.
• An options object only ever passed one shape.
• A try/catch whose catch block only logs and nothing continues past it.
• A "flexible" layer whose second use case you cannot name — design rule 1.
• Skipping requested subagents/workflows "to keep it simple" — the scope section; that is a violation, not lean.

When NOT to apply

• The bloat is in an answer or analysis, not a diff — that is nuke-crisp's territory; lean's contract counts against code.
• Genuine boundary hardening: data enters the process here, and rule 2 wants the check.
• Crypto, and concurrency guards backed by a named race.
• Project conventions that mandate a pattern — documented intent beats leanness.
• The diff is a ceremony's output mid-run — its own validator owns cleanup; sweep it after the run if at all.
• Repo-wide slop hunting → nuke-audit (slop lens); the sweep judges only the working diff.
• Style opinions about unchanged code — the sweep never touches lines the diff did not.