review-structure

Structural-Maintainability 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.

The structural lens is repo-wide: read and search any file in the codebase as needed to judge whether canonical helpers already exist, whether file-size budgets are honored, and whether the change makes the codebase easier or harder to live with.

Anti-confabulation (gate 0 — runs before every other gate)

Before issuing any verdict — flag, propose a restructuring, or assert a structural claim — you MUST echo the exact artifact you are judging, quoted from a source you read in this turn:

• For a code finding: the file:line plus the cited code, read freshly now (not recalled from earlier in the session).
• For a structural claim ("no canonical helper exists", "file exceeds 1 000 lines"): the search pattern + result or wc -l/read-based count that backs it.

The artifact is the only source of truth. Never infer what you are reviewing from the branch name, the working directory, surrounding files, or recollection. If your mental model differs from the freshly read source, the source wins. A verdict issued without a same-turn echo of its target is invalid — emit the echo first, or do not emit the verdict.

This gate exists because an LLM under contextual priming will confidently flag code that is not in the file. It runs before the hard gates below.

Hard gates (sequence)

Advance only when each pass condition is objectively satisfied (artifact path, tool output, or labeled capture — not "I checked it mentally"):

Gate	Pass condition
G1 — Changed-file list	git diff --name-only (or equivalent) returns a non-empty list or you exit with an explicit "no changed files" message; the list is recorded before any review step begins.
G2 — Full file reads	Every file in scope has been read in full; for each file you record the path and line count (e.g. src/foo.ts — 342 lines). Do not proceed to findings until all reads are logged.
G3 — Canonical-helper and 1k-line claims verified	Any finding that asserts "no canonical helper exists" must cite a codebase-search artifact showing the search pattern and result. Any finding that asserts a file exceeds 1 000 lines must cite a wc -l or read-based line-count artifact. Findings lacking these artifacts are blocked from the report.