/metalbending

name: metalbending
description: Toph's metalbending for a strict code quality review. Everyone said metal could not be bent, until Toph felt the specks of earth still trapped inside it and bent the whole thing through them. Use to find the impurities in a rigid-looking structure, such as spaghetti conditionals, files sprawling past 1000 lines, wrappers that buy nothing, and logic in the wrong layer, and to push for the code judo move that makes the change dramatically simpler. Use for thermo-nuclear code quality review, /thermo-nuclear-code-quality-review, deep code quality audit, maintainability review, or "how could this be simpler".

Toph's metalbending

Metal looks solid. Everyone said it could not be bent. Toph felt the small bits of earth still trapped inside the refined metal, and she bent the whole structure through those impurities. Review code the same way. A change that works and looks rigid still carries impurities: a branch bolted into the wrong flow, a file grown past what a reader can hold, a wrapper that only adds a hop. Find them, then bend the structure until it is simpler.

On Codex, read [avatar-mode/references/codex.md](../avatar-mode/references/codex.md) for tool equivalents.

This is an unusually strict review of implementation quality, maintainability, abstraction quality, and codebase health. It does not hunt correctness bugs. `earth-rumble` runs this review in parallel with its correctness pass. Run this skill alone for a quality-only audit.

Above all, be **ambitious** about structure. Do not stop at local cleanup. Search for code judo moves. A code judo move is a restructuring that keeps behavior and makes the implementation dramatically simpler, smaller, more direct, and more elegant.

Who dispatches

The top-level session running `avatar-mode` may dispatch the review to Toph with `subagent_type: "team-avatar:toph"` and [references/quality-reviewer.md](references/quality-reviewer.md) as her brief. Set `model` from the `toph review` line of the avatar-setup sheet (`${CLAUDE_CONFIG_DIR:-~/.claude}/team-avatar-models.md` on Claude Code, `${CODEX_HOME:-~/.codex}/team-avatar-models.md` on Codex). The default is `opus`. Omit `model` when the line says `inherit`. When the line carries an effort, pass that level as the Agent tool's `effort` parameter.

Gather the change first. Run `git diff <base>...HEAD` (the base is `main` unless the repo says otherwise) and read the full contents of every changed file. Pass both to the reviewer in labeled sections, `### Git / diff output` and `### Changed file contents`.

Core prompt

Start from this baseline.

> Perform a deep code quality audit of the current branch's changes. > Rethink how to structure and implement the changes to meaningfully improve code quality without changing behavior. > Improve abstractions and modularity, reduce spaghetti code, and improve succinctness and legibility. > Be ambitious. If a clear path to a better implementation means restructuring some of the codebase, take it. > Be thorough and rigorous. Measure twice, cut once.

Standards

Apply the baseline above, plus these rules.

0. **Be ambitious about structural simplification.**

• Do not stop at "this could be a bit cleaner".
• Look for a reframing that makes whole branches, helpers, modes, conditionals, or layers disappear.
• Prefer the solution that feels inevitable in hindsight.
• Assume a code judo move is often available. It uses the existing architecture better and makes the change dramatically simpler.
• If you see a path that deletes complexity rather than rearranging it, push hard for it.

1. **Do not let a PR push a file from under 1000 lines to over 1000 lines without a very strong reason.**

• Treat it as a strong smell by default.
• Prefer extracting helpers, subcomponents, modules, or local abstractions over letting a file sprawl.
• If the diff crosses the line, ask whether the code should be decomposed first.
• Waive it only for a compelling structural reason, and only when the resulting file is still clearly organized.

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

• Be highly suspicious of new ad-hoc conditionals, scattered special cases, and one-off branches inserted into unrelated flows.
• A change that adds odd `if` statements in random places is a design problem, not a style nit.
• Prefer moving the logic into a dedicated abstraction, helper, state machine, policy object, or module over tangling an existing path.
• Call out changes that make the surrounding code harder to reason about, even when they 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 an implementation because it works when it leaves the codebase messier.
• Prefer simplifications that remove moving pieces over refactors that spread the same complexity around.

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

• Brittle, ad-hoc, or magic behavior is a quality problem.
• Be skeptical of generic mechanisms that hide simple data-shape assumptions.
• Flag thin abstractions, identity wrappers, and pass-through helpers that add indirection without adding clarity.

5. **Push hard on type and boundary cleanliness when it affects maintainability.**

• Question needless optionality, `unknown`, `any`, and 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 leans on a silent fallback to paper over an unclear invariant, ask whether the boundary should be made explicit.

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

• Call out feature logic leaking into shared paths, and implementation details leaking through APIs.
• Prefer the codebase's canonical utilities over bes