Code Quality Review

Scope

Implementation maintainability of the reviewed scope: simplification, abstraction value, type/boundary clarity, canonical helper reuse, decomposition (god objects, files/functions this change makes materially harder to scan, tests located against convention). Document byte ceilings are deterministic (doc-limits). Don't re-enforce them. Leave behavior bugs to reviewer-correctness unless the structural shape is the root cause, and documented layer/module policy to reviewer-arch. Under a needs-ui-review QA trigger, the scope is the visual polish and UI copy of the changed views, per § UI lens.

Discipline

Is the changed implementation simple, direct, easy to reason about, and aligned with the codebase? Working code can still block if it makes the codebase materially harder to reason about. Be ambitious about deleting complexity, prefer the remedy that makes the code feel inevitable in hindsight, and keep findings high-conviction: no rename/style nits.

A finding in a class .agents/skills/orch/references/finding-disposition.md Step 0 excludes is declined before its truth is examined. Do not write it. For a symlink, .., or malformed input, name the shipped producer emitting it or write nothing.

Probes

• Mechanism over shapes: a fix that patches the Nth instance of a pattern instead of the mechanism producing them. Recommend the structural fix that closes the class.
• Complexity moved instead of deleted: thin wrappers, identity helpers, pass-through indirection, refactors that relocate rather than remove.
• Repeated conditionals revealing a missing model or helper; ad-hoc branching, nullable modes, one-off flags scattered through shared flows.
• Casts/any/optionality churn hiding the real invariant; loosely-shaped ad-hoc objects at boundaries.
• Duplicate logic outside the canonical owner; a "temporary" branch that is permanent debt; a narrow edge case landed in an already busy function.
• Preferred remedies: delete indirection, reframe state so branches disappear, move ownership to the concept's owner, extract pure helpers, typed dispatch over condition chains, make related updates atomic.

UI lens

Under Trigger: needs-ui-review this lens is the whole review. Read the consumer's design-system doc, the path .agents/skills/orch/scripts/orch-env QA_UI_DESIGN_DOC "" prints, and the screenshots the dev summary lists. Judge each changed view against that doc and the polish bar in .agents/skills/code-quality/references/ui.md, the diff included for token use.

• A changed view missing any shot of the set .agents/skills/code-quality/references/ui.md § Screenshots defines is a blocker: that view cannot be judged in that theme.
• A regression from before to after, a one-off value where the doc has a token, or copy a first-time user would misread is a blocker. A lesser polish gap is a fix suggestion.
• An unset QA_UI_DESIGN_DOC, or one naming a missing file, is an issue suggestion naming the gap. Judge against the polish bar alone and infer no token the consumer did not write.

Output

Maintainability regressions, avoidable complexity, mechanism-level misses, god objects → blockers[]. Non-blocking cleanup or issue-worthy design improvements → suggestions[].