Files
gstack/review/specialists/maintainability.md
T
c25bcb2f16 fix(review): catch loosened-input consumers and stale user-facing strings
The Enum & Value Completeness check fired only on newly added values, so a
diff that widens what a validator, parser or guard accepts, and breaks an
unchanged downstream consumer outside the diff, was a blind spot. Widen the
check's trigger (heading unchanged) and add a consumer-grep bullet. Teach
the maintainability specialist to flag user-facing strings whose guarding
condition changed while the text did not.

Adopts #2141 (rewritten on current main; the section heading is kept).

Co-authored-by: Arno V <38716+aversini@users.noreply.github.com>
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
2026-10-08 06:21:11 +00:00

2.6 KiB

Maintainability Specialist Review Checklist

Scope: Always-on (every review) Output: JSON objects, one finding per line. Schema: {"severity":"INFORMATIONAL","confidence":N,"path":"file","line":N,"category":"maintainability","summary":"...","fix":"...","fingerprint":"path:line:maintainability","specialist":"maintainability"} Optional: line, fix, fingerprint, evidence, test_stub. If no findings: output NO FINDINGS and nothing else.


Categories

Dead Code & Unused Imports

  • Variables assigned but never read in the changed files
  • Functions/methods defined but never called (check with Grep across the repo)
  • Imports/requires that are no longer referenced after the change
  • Commented-out code blocks (either remove or explain why they exist)

Magic Numbers & String Coupling

  • Bare numeric literals used in logic (thresholds, limits, retry counts) — should be named constants
  • Error message strings used as query filters or conditionals elsewhere
  • Hardcoded URLs, ports, or hostnames that should be config
  • Duplicated literal values across multiple files

Stale Comments & Docstrings

  • Comments that describe old behavior after the code was changed in this diff
  • TODO/FIXME comments that reference completed work
  • Docstrings with parameter lists that don't match the current function signature
  • ASCII diagrams in comments that no longer match the code flow
  • User-facing strings (errors, toasts, labels) whose guarding condition changed in this diff while the text did not

Duplicated Behavior with Defects

  • Divergent copies that produce a demonstrated incorrect result, miss required error handling, or violate the same contract
  • Report the concrete defect and its evidence through normal Fix-First handling; matching syntax or repeated line counts alone are not findings
  • Optional shared-helper extractions belong to the core shared-code check. Do not duplicate its proposals or turn structural preferences into defects

Conditional Side Effects

  • Code paths that branch on a condition but forget a side effect on one branch
  • Log messages that claim an action happened but the action was conditionally skipped
  • State transitions where one branch updates related records but the other doesn't
  • Event emissions that only fire on the happy path, missing error/edge paths

Module Boundary Violations

  • Reaching into another module's internal implementation (accessing private-by-convention methods)
  • Direct database queries in controllers/views that should go through a service/model
  • Tight coupling between components that should communicate through interfaces