Code Quality Review
Review the current branch diff for structural quality. Preserve behavior, but actively look for a simpler design that
deletes concepts, branches, wrappers, or layers instead of moving complexity around.
Review Boundaries
- Review only the changed code and the surrounding code needed to judge it.
- Treat repository conventions and existing canonical helpers as the source of truth.
- Skip formatter and linter findings that automation already reports.
- Prefer a small set of high-confidence structural findings over cosmetic notes.
- Do not propose a large refactor unless its benefit is clear and it stays within the change's ownership boundary.
Review Criteria
Check each meaningful change for:
- Simpler structure — Can a different model or ownership boundary remove branches, modes, helpers, or layers?
- Cohesive control flow — Flag scattered special cases, repeated conditions, deep nesting, and mixed responsibilities.
- Useful abstractions — Flag thin wrappers, generic magic, speculative extension points, and duplicate helpers.
- Clean boundaries — Keep feature logic in its canonical module and make types and invariants explicit.
- Reasonable file size — Treat a change that pushes a file above 1,000 lines as a decomposition signal unless the
file has a clear structural reason to stay whole.
- Sound orchestration — Flag unnecessarily sequential independent work and updates that can leave related state
partially applied when a clearer atomic design exists.
- Legibility — Prefer direct, boring code with clear names and comments that explain only non-obvious reasons.
Boundary and state checks
Apply these checks only where the diff touches the relevant contract:
- Input and domain model — Validate external data at entry and carry that validated contract internally. Prefer
existing types that exclude invalid combinations over repeated guards or casts that hide a broken model. Do not
remove checks at a separate trust boundary or require a type-system redesign for clear, local code.
- Retries and partial failure — For operations that can be retried, check the outcome after a second run and after
interruption between side effects. Flag duplicate effects or incomplete recovery against the operation's contract;
do not assume that every operation must be idempotent.
- Mutable ownership — Before proposing locks or serialized execution, check whether independent actors can own
separate state. When state must be shared, identify the writer and the mechanism that enforces safe updates. Preserve
a correct existing transaction or synchronization model rather than forcing a single-writer rewrite.
Use existing complexity and duplication reports as evidence when available, not universal pass/fail thresholds.
Recommend a split or shared helper only when it improves cohesion or gives one business decision one owner; similar
syntax alone is not enough. Do not require Crapper, Dryer, or new tooling to complete a review.
Finding Bar
Report a finding only when you can name:
- the file and relevant hunk;
- the concrete maintenance cost or failure mode;
- the smallest practical remedy; and
- why the remedy is better than the current design.
Treat these as blockers unless the implementation has a clear justification:
- a structural regression or avoidable boundary leak;
- a file newly crossing 1,000 lines without useful decomposition;
- ad hoc branching added to an already busy flow;
- duplicated logic where a canonical helper exists;
- an abstraction, cast, or optional contract that adds indirection without clarity; or
- a clear simplification that removes substantial incidental complexity.
Do not block on personal style, hypothetical future needs, or a rewrite that is only differently complex.
Output
Order findings by impact:
- Structural regressions and simpler designs
- Control-flow, boundary, abstraction, and type problems
- File-size, modularity, and legibility concerns
For each finding, use:
[severity] file:line — finding
Impact: concrete cost or risk
Fix: smallest practical remedy
End with APPROVE when no blocking finding remains, or CHANGES REQUESTED with the blocker count. Be direct and
respectful.
Attribution
Boundary and state checks and metric limits are adapted from Robert C. Martin's
ub-mode — Architecture, Crapper, and Dryer.
1---2name: code-quality-review-23description: "Audit a diff for structural maintainability and unnecessary complexity."4license: MIT5compatibility: cline, claude, opencode, amp, codex, gemini, cursor, pi6hint: Use for a deep review of maintainability, abstraction quality, and avoidable complexity7user-invocable: true8disable-model-invocation: true9metadata:10 source: https://skillmd.com/skills/jellydn/code-quality-review-211---1213# Code Quality Review1415Review the current branch diff for structural quality. Preserve behavior, but actively look for a simpler design that16deletes concepts, branches, wrappers, or layers instead of moving complexity around.1718## Review Boundaries1920- Review only the changed code and the surrounding code needed to judge it.21- Treat repository conventions and existing canonical helpers as the source of truth.22- Skip formatter and linter findings that automation already reports.23- Prefer a small set of high-confidence structural findings over cosmetic notes.24- Do not propose a large refactor unless its benefit is clear and it stays within the change's ownership boundary.2526## Review Criteria2728Check each meaningful change for:29301. **Simpler structure** — Can a different model or ownership boundary remove branches, modes, helpers, or layers?312. **Cohesive control flow** — Flag scattered special cases, repeated conditions, deep nesting, and mixed responsibilities.323. **Useful abstractions** — Flag thin wrappers, generic magic, speculative extension points, and duplicate helpers.334. **Clean boundaries** — Keep feature logic in its canonical module and make types and invariants explicit.345. **Reasonable file size** — Treat a change that pushes a file above 1,000 lines as a decomposition signal unless the35 file has a clear structural reason to stay whole.366. **Sound orchestration** — Flag unnecessarily sequential independent work and updates that can leave related state37 partially applied when a clearer atomic design exists.387. **Legibility** — Prefer direct, boring code with clear names and comments that explain only non-obvious reasons.3940### Boundary and state checks4142Apply these checks only where the diff touches the relevant contract:4344- **Input and domain model** — Validate external data at entry and carry that validated contract internally. Prefer45 existing types that exclude invalid combinations over repeated guards or casts that hide a broken model. Do not46 remove checks at a separate trust boundary or require a type-system redesign for clear, local code.47- **Retries and partial failure** — For operations that can be retried, check the outcome after a second run and after48 interruption between side effects. Flag duplicate effects or incomplete recovery against the operation's contract;49 do not assume that every operation must be idempotent.50- **Mutable ownership** — Before proposing locks or serialized execution, check whether independent actors can own51 separate state. When state must be shared, identify the writer and the mechanism that enforces safe updates. Preserve52 a correct existing transaction or synchronization model rather than forcing a single-writer rewrite.5354Use existing complexity and duplication reports as evidence when available, not universal pass/fail thresholds.55Recommend a split or shared helper only when it improves cohesion or gives one business decision one owner; similar56syntax alone is not enough. Do not require Crapper, Dryer, or new tooling to complete a review.5758## Finding Bar5960Report a finding only when you can name:6162- the file and relevant hunk;63- the concrete maintenance cost or failure mode;64- the smallest practical remedy; and65- why the remedy is better than the current design.6667Treat these as blockers unless the implementation has a clear justification:6869- a structural regression or avoidable boundary leak;70- a file newly crossing 1,000 lines without useful decomposition;71- ad hoc branching added to an already busy flow;72- duplicated logic where a canonical helper exists;73- an abstraction, cast, or optional contract that adds indirection without clarity; or74- a clear simplification that removes substantial incidental complexity.7576Do not block on personal style, hypothetical future needs, or a rewrite that is only differently complex.7778## Output7980Order findings by impact:81821. Structural regressions and simpler designs832. Control-flow, boundary, abstraction, and type problems843. File-size, modularity, and legibility concerns8586For each finding, use:8788```text89[severity] file:line — finding90Impact: concrete cost or risk91Fix: smallest practical remedy92```9394End with `APPROVE` when no blocking finding remains, or `CHANGES REQUESTED` with the blocker count. Be direct and95respectful.9697## Attribution9899Boundary and state checks and metric limits are adapted from Robert C. Martin's100[`ub-mode` — Architecture, Crapper, and Dryer](https://github.com/unclebob/ub-mode/blob/3da62bf3fcfd2034de41f30d920d2739e566171f/SKILL.md).