thermo-nuclear-code-quality-review

Overview

An unusually strict review of implementation quality, maintainability, abstraction quality, and codebase health. Above all, be ambitious about structure: do not stop at local cleanup. Actively hunt for the code judo move, a restructuring that preserves behavior while making the implementation dramatically simpler, smaller, more direct, and more elegant. Prefer deleting complexity over rearranging it.

Run this skill only on explicit request. The repo command schema has no disable-model-invocation field, so explicit-only is carried by the description wording and the slash command, not by auto-suggestion.

Steps

1. Read SKILL.md (this file) and scope the diff: read the current branch's changes against its merge base, then list the files touched and the concepts each change introduces.
2. Model the ideal shape first. Before judging the diff, ask what the simplest behavior-preserving implementation would look like. That target is the bar.
3. Hunt for the code judo move. For every meaningful change, look for a reframing that makes whole branches, helpers, modes, conditionals, or layers disappear. Prefer the solution that feels inevitable in hindsight.
4. Check structural health against the Standards below: file size, spaghetti growth, directness, type and boundary cleanliness, canonical-layer ownership, and orchestration or atomicity.
5. Prioritize and report. Lead with structural regressions and missed simplifications, keep behavior identical, and prefer a few high-conviction findings over a long list of nits.

Standards

Apply every standard. Treat each as a presumptive blocker unless the author justifies it clearly.

• Be ambitious about simplification. Look for the reframing that deletes categories of complexity, not the version that spreads the same complexity around. If a path deletes complexity, push hard for it.
• Guard the 1000-line threshold. Do not let a change push a file from under 1000 lines to over 1000 lines without a very strong reason. Prefer extracting helpers, subcomponents, or modules. If the diff crosses that line, ask whether to decompose first.
• Block spaghetti growth. Be highly suspicious of new ad-hoc conditionals, scattered special cases, or one-off branches bolted onto unrelated flows. Push the logic into a dedicated abstraction, helper, state machine, or policy object instead of tangling an existing path.
• Clean the design, do not just accept working code. If behavior can stay the same while the structure gets meaningfully cleaner, push for the cleaner version. Do not rubber-stamp "it works" code that leaves the codebase messier.
• Prefer direct, boring code over magic. Treat brittle, ad-hoc, or magical behavior as a quality problem. Flag thin wrappers, identity abstractions, and pass-through helpers that add indirection without buying clarity.
• Keep type and boundary contracts clean. Question unnecessary optionality, unknown, any, or cast-heavy code when a clearer boundary could exist. If a branch leans on a silent fallback to paper over an unclear invariant, ask to make the boundary explicit.
• Keep logic in its canonical layer. Call out feature logic leaking into shared paths or implementation details leaking through an API. Reuse the existing canonical helper instead of a near-duplicate, and move logic to the package or module that already owns the concept.
• Treat needless sequential orchestration and non-atomic updates as smells when the cleaner structure is obvious: parallelize independent work, and restructure related updates so state cannot land half-applied.