/thermo-nuclear-code-quality-review

name: thermo-nuclear-code-quality-review
description: >-
  Run an extremely strict maintainability review for abstraction quality,
  giant files, and spaghetti-condition growth. Use when the user explicitly
  asks for a thermo-nuclear review, thermonuclear review, deep code quality
  audit, or an especially harsh maintainability review. Not for ordinary
  review requests — those belong to the built-in code-review skill. This
  file is also the canonical rubric loaded by the
  thermo-nuclear-code-quality-review agent.

Thermo-Nuclear Code Quality Review

Use this skill for an unusually strict review focused on implementation quality, maintainability, abstraction quality, and codebase health.

Above all, this skill should push the reviewer to be **ambitious** about code structure. Do not merely identify local cleanup opportunities. Actively search for "code judo" moves: restructurings that preserve behavior while making the implementation dramatically simpler, smaller, more direct, and more elegant.

How to Run

This skill is the **canonical rubric**. There are two ways it gets used:

1. **Directly** (`/essentials:thermo-nuclear-code-quality-review`) — gather the review scope yourself, then apply the rubric below in this session:

• Branch: `git rev-parse --abbrev-ref HEAD`
• Diff vs main: `git diff main...HEAD` (fall back to `git diff HEAD` for

uncommitted work if there is no branch diff)

• Read the full current contents of every changed file — not just the diff

hunks. Structural judgments require seeing the whole file (especially the 1k-line rule).

• If there are no changes to review, say so and stop.

2. **Via the `thermo-nuclear-code-quality-review` agent** — the agent loads this skill as its complete rubric and applies it to the diff and file contents in its prompt. Prefer the agent when you want the review to run in an isolated context (e.g. dispatched in parallel, or to keep the main session uncluttered).

Apply the rubric **only** to what the diff and current file contents show. Trace cross-file impact when a change touches a module boundary.

Core Prompt

Start from this baseline:

> Perform a deep code quality audit of the current branch's changes. > Rethink how to structure / implement the changes to meaningfully improve code quality without impacting behavior. > Work to improve abstractions, modularity, reduce Spaghetti code, improve succinctness and legibility. > Be ambitious, if there is a clear path to improving the implementation that involves restructuring some of the codebase, go for it. > Be extremely thorough and rigorous. Measure twice, cut once.

Non-Negotiable Additional Standards

Apply the baseline prompt above, plus these explicit review rules:

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.
• Prefer the solution that makes the code feel inevitable in hindsight.
• Assume there is often a "code judo" move available: a re-organization that uses the existing architecture more effectively and makes the change dramatically simpler and more elegant.
• 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 from under 1k lines to over 1k lines without a very strong reason.**

• Treat this as a strong code-quality smell by default.
• Prefer extracting helpers, subcomponents, modules, or local abstractions instead of letting a file sprawl past 1000 lines.
• If the diff crosses that threshold, explicitly ask whether the code should be decomposed first.
• Only waive this if there is a compelling structural reason and the resulting file is still clearly organized.

2. **Do not allow random spaghetti growth in existing code.**

• Be highly suspicious of new ad-hoc conditionals, scattered special cases, or one-off branches inserted into unrelated flows.
• If a change adds "weird if statements in random places", 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 cleanliness when they affect maintainability.**

• Question unnecessary optionality, `unknown`, `any`, or cast-heavy code when a clearer type boundary could exist.
• Prefer explicit typed models or shared contracts over loosely-shaped ad-hoc objects.
• If a branch relies on silent fallback to paper over an unclear invariant, ask whether the boundary should be made explicit instead.

6. **Keep logic in the canonical layer and reuse existing helpers.**

• Call out feature logic leaking into shared paths or implementation details leaking through APIs.
• Prefer existing canonical utilities/helpers over bespoke one-offs.
• Push code toward the right package, service, or module instead of normalizing architectural drift.

7. **Treat