maintainability.md
46 lines · review/specialists/maintainability.md at 3f79d81
1# Maintainability Specialist Review Checklist
3Scope: Always-on (every review)
4Output: JSON objects, one finding per line. Schema:
5{"severity":"INFORMATIONAL","confidence":N,"path":"file","line":N,"category":"maintainability","summary":"...","fix":"...","fingerprint":"path:line:maintainability","specialist":"maintainability"}
6Optional: line, fix, fingerprint, evidence, test_stub.
7If no findings: output `NO FINDINGS` and nothing else.
9---
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.
Raw lines 1 to 10
Categories
Raw lines 11 to 1213### Dead Code & Unused Imports
14- Variables assigned but never read in the changed files
15- Functions/methods defined but never called (check with Grep across the repo)
16- Imports/requires that are no longer referenced after the change
17- Commented-out code blocks (either remove or explain why they exist)
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)
19### Magic Numbers & String Coupling
20- Bare numeric literals used in logic (thresholds, limits, retry counts) — should be named constants
21- Error message strings used as query filters or conditionals elsewhere
22- Hardcoded URLs, ports, or hostnames that should be config
23- Duplicated literal values across multiple files
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
25### Stale Comments & Docstrings
26- Comments that describe old behavior after the code was changed in this diff
27- TODO/FIXME comments that reference completed work
28- Docstrings with parameter lists that don't match the current function signature
29- ASCII diagrams in comments that no longer match the code flow
30- User-facing strings (errors, toasts, labels) whose guarding condition changed in this diff while the text did not
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
32### Duplicated Behavior with Defects
33- Divergent copies that produce a demonstrated incorrect result, miss required error handling, or violate the same contract
34- Report the concrete defect and its evidence through normal Fix-First handling; matching syntax or repeated line counts alone are not findings
35- Optional shared-helper extractions belong to the core shared-code check. Do not duplicate its proposals or turn structural preferences into defects
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
37### Conditional Side Effects
38- Code paths that branch on a condition but forget a side effect on one branch
39- Log messages that claim an action happened but the action was conditionally skipped
40- State transitions where one branch updates related records but the other doesn't
41- Event emissions that only fire on the happy path, missing error/edge paths
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
43### Module Boundary Violations
44- Reaching into another module's internal implementation (accessing private-by-convention methods)
45- Direct database queries in controllers/views that should go through a service/model
46- Tight coupling between components that should communicate through interfaces
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