/thermo-nuclear-code-review

name: thermo-nuclear-code-review
description: >
  Run an extremely strict structural and architectural quality review on a diff, branch,
  or file set, hunting for "code judo" moves that dramatically simplify the implementation
  — not correctness bugs or style nits.
metadata:
  user-invocable: true
  argument-hint: "[PR URL, branch, or file paths]"
  keywords: [thermonuclear, code judo, maintainability audit, harsh review, deep code review]
allowed-tools: Bash, Read, Glob, Grep

Thermo-Nuclear Code Quality Review

An unusually strict review focused on structural quality, architectural health, abstraction cleanliness, and codebase maintainability. This is not a correctness review — it asks whether the code is making the codebase *better* or *worse*.

The guiding principle is **code judo**: actively search for restructurings that preserve behavior while making the implementation dramatically simpler, smaller, more direct, and more elegant. Do not stop at "this could be a bit cleaner." Look for moves where whole branches, helpers, modes, conditionals, or layers disappear entirely. Prefer the solution that feels inevitable in hindsight.

Scope — What This Review IS and IS NOT

| This review covers | This review does NOT cover | |---|---| | Structural quality and architectural health | Correctness bugs (use a dedicated correctness-focused review) | | Abstraction quality and decomposition | Style nits and formatting | | Complexity growth and spaghetti detection | Test coverage gaps | | Layer violations and architectural drift | Security vulnerabilities | | File size and modularity | Performance micro-optimizations | | Type boundary and contract cleanliness | Linting violations |

If a correctness review or repo-specific rule enforcement is needed, run that separately. This skill is the architectural conscience.

Review Context

• **Pin the fixed point first**: Establish what the diff is measured against before reading any code. Use whatever the user supplies — a PR URL, branch, commit SHA, tag, `main`, or `HEAD~5`. If none is given, ask. Then capture the diff once with a three-dot (merge-base) comparison: `git diff <fixed-point>...HEAD`, and the commit list with `git log <fixed-point>..HEAD --oneline`. Before analyzing, confirm the ref resolves (`git rev-parse <fixed-point>`) and the diff is non-empty — a bad ref or empty diff should fail here, not surface as a confusing empty review.
• **Full-file reads required**: For every file with >10 lines changed, read the entire file, not just diff hunks. Structural review depends on surrounding patterns, file size before the change, and consistency with existing conventions.
• **Pre-change file size matters**: For files already >800 lines, note the pre-change line count — the 1000-line threshold (Standard 1) is evaluated against the post-change total.
• **Large diffs**: For diffs >200 changed lines, save to a temp file for reference during analysis.
• **Code smell baseline**: Apply `references/code-smells.md` alongside the standards — an always-on set of Fowler structural smells (Feature Envy, Data Clumps, Primitive Obsession, Shotgun Surgery, etc.) that catches structural problems the numbered Standards don't name explicitly.
• **Skip what tooling enforces**: RuboCop, ESLint, Prettier, and type-checkers already block formatting, naming-convention, and lint issues. Do not spend findings on what CI catches — the review's value is the structural judgement no linter can make.
• **Concrete suggestions**: For each finding, identify the specific standard or smell violated, locate the exact file and line range, and draft a concrete code judo move or restructuring — not a vague observation.

---

Non-Negotiable Standards

0. Be ambitious about structural simplification

Do not stop at "this could be a bit cleaner." Look for opportunities to reframe the change so that whole branches, helpers, modes, conditionals, or layers disappear entirely. Assume there is often a code judo move available — a reorganization that uses the existing architecture more effectively and makes the change dramatically simpler. If you see a path to delete complexity rather than rearrange it, push hard for that path.

1. Do not let a PR push a file past 1000 lines without a very strong reason

Treat crossing 1000 lines as a structural smell. Prefer extracting helpers, subcomponents, modules, or local abstractions instead of letting a file sprawl. If the diff crosses that threshold, explicitly call it out. Only waive this if the file is clearly organized and the growth is structurally justified — not just "I added more methods here because this is where the other ones are."

2. Do not allow random spaghetti growth

Be highly suspicious of new ad-hoc conditionals, scattered special cases, or one-off branches inserted into unrelated flows. If a change adds if-statements in unrelated code paths, treat that as a design problem, not a stylistic nit. Prefer pushing the logic into a dedicated abstraction, helper, state machine, policy object, or separate module instead of tangling an existing path. Call out changes that make the surrounding code harder to reason about, even if they technically work.

3. Bias toward cleaning the design, not just accepting working code

If behavior can stay the same while the structure becomes meaningfully cleaner, push for the cleaner version. Do not rubber-stamp "it works" implementations that leave the codebase messier. Strongly prefer simplifications that remove moving pieces altogether over refactors that merely spread the same complexity around.

4. Prefer direct, boring, maintainable code over hacky or magical code

Treat brittle, ad-hoc, or "magic" behavior as a code-quality problem. Be skeptical of generic mechanisms that hide simple data-shape assumptions. Flag thin abstractions, identity wrappers, or pass-through helpers that add indirection without buying clarity.

5. Push hard on type and boundary cleanlin