review-code-maintainability

Before scanning, read docs/decisions/ ADRs if they exist. Use documented architectural decisions to distinguish intentional patterns from accidental inconsistency. Do not flag documented exceptions as findings.

Act as a principal-level software engineer, software architect, and prompt-driven code review specialist.

Your task is to perform a comprehensive optimization, maintainability, and structural consistency review of this repository. Assess the codebase for redundancy, inconsistency, missed reuse opportunities, weak abstractions, and recurring engineering gaps, then produce a practical refactor plan that improves maintainability without altering business behavior.

Your mission is not just to find obvious duplicates. You must actively look for families of similar issues across the repository, including repeated patterns that appear with minor variations, inconsistent implementations of the same concern, and areas where the same engineering intent has been solved multiple different ways.

---

Activation Triggers

Run this review when:

• A feature or module is marked complete (feature-level scope)
• At the end of each development sprint (full codebase scope)
• When structural drift is suspected (inconsistent patterns emerging across modules)
• Before major refactoring work to identify priorities
• After multiple features have landed without intermediate review

---

Review Objectives

Focus on identifying:

1. Duplicate or near-duplicate logic, copy-paste implementations, repeated validation, repeated condition chains, and redundant workflows.
2. Opportunities to extract reusable abstractions such as helper functions, shared services, utility modules, base classes, adapters, hooks, middleware, or common components.
3. Constants and values that should be centralized, including magic numbers, repeated strings, status labels, route names, error messages, configuration values, and environment-specific settings.
4. Repeated types, DTOs, schemas, interfaces, models, and request/response structures that should be unified.
5. Large or overloaded files, classes, and methods that should be decomposed for clarity, reuse, and testability.
6. Weak module boundaries, poor folder organization, circular dependencies, and misplaced responsibilities.
7. Repeated database, API, logging, exception-handling, and authorization patterns that should be standardized.
8. Naming inconsistencies, dead code, stale abstractions, unused imports, and obsolete helpers.
9. Clear, evidence-based performance improvements such as unnecessary recomputation, avoidable duplicate queries, inefficient loops, or repeated allocations. Do not recommend speculative micro-optimizations.
10. Refactors that would materially improve testability and reduce future maintenance cost.
11. Inconsistent error contract patterns, including multiple shapes for similar errors, repeated error translation logic, or mixed approaches to user-facing and internal error handling.
12. Repeated parsing, serialization, transformation, mapping, or normalization logic that should be centralized.
13. Inconsistent configuration access patterns, including direct environment reads scattered through the codebase, partially duplicated config loaders, or mixed defaulting behavior.
14. Domain rules or business policies implemented in multiple places, especially if the same rule is enforced separately in controllers, services, validators, UI code, jobs, or database layers.
15. Repeated control flow for retries, backoff, polling, idempotency, rate limiting, caching, batching, or pagination that should be standardized. Specifically flag: missing rate limiting on authentication or expensive endpoints implemented inconsistently across services, unbounded pagination parameters without a maximum cap enforced at a shared layer, and ReDoS-prone regex patterns applied to user input that should be centralized and reviewed for catastrophic backtracking.
16. Frontend duplication such as repeated form logic, validation rules, loading states, empty states, error rendering, table behavior, modal patterns, or data-fetching orchestration.
17. Backend duplication such as repeated controller scaffolding, request guards, service orchestration, repository access patterns, transaction handling, or response formatting.
18. Logging and observability inconsistencies, including repeated log message templates, missing context propagation, mixed severity usage, or inconsistent metrics and tracing hooks. Specifically flag: security-relevant events that are not consistently logged across services (failed authentication, permission denials, admin actions, data exports), PII or sensitive data appearing in log output without masking, and missing correlation IDs or request context that would make incident investigation difficult.
19. Test duplication, weak test structure, repeated fixture setup, brittle mocks, inconsistent factories, and missing opportunities for shared test utilities.
20. Dependency hygiene issues such as duplicated utility libraries, overlapping packages, wrapper abstractions with little value, or modules coupled to too many concrete dependencies.
21. Workflow and tooling duplication across scripts, CI pipelines, code generation, build steps, linting, formatting, and local developer commands.
22. Public contract drift across API handlers, clients, SDKs, schemas, validators, and documentation.
23. UI, API, and database naming drift where the same concept is represented with different terms, shapes, or statuses across layers.
24. State management inconsistencies, including duplicated derived state, conflicting sources of truth, or business state spread across unrelated modules.
25. File and module placement issues where code exists in technically functional but semantically wrong locations, making future navigation and ownership harder.
26. Cross-cutting concerns implemented ad hoc, including auth, auditing, correlation IDs, feature flags, permissions, tenancy, localization, serialization, and response shaping.
27. Unsafe or maintainability-harming patterns around async behavior, resource lifecycle, cleanup, event listeners, subscriptions, timers, worker jobs, or background processing.
28. Areas where a change to one concept would currently require touching too many files, indicating poor cohesion or excessive coupling.
29. Documentation drift inside the codebase, including misleading comments, stale READMEs, outdated examples, mismatched type comments, and code that no longer matches its stated intent.
30. Places where introducing a shared abstraction would be premature, over-engineered, or harmful. Explicitly call these out so the refactor plan stays pragmatic.
31. AI-generation artifacts: identify patterns typical of multi-session AI-generated code, including over-verbose boilerplate, redundant inline comments that merely restate what the code does, inconsistent naming conventions across files generated in different sessions, unnecessary abstraction layers that add indirection without reducing duplication, and structural inconsistencies that suggest the code was generated without awareness of adjacent modules.
32. Test coverage delta: for every new module, service, utility, or Lambda handler identified in this review, flag whether corresponding unit or integration tests exist. Highlight untested public interfaces, untested business-critical paths, and any service boundaries that lack contract tests.
33. Code commenting and documentation compliance: verify that all modules have file-level docstrings explaining purpose and architectural role, all classes have docstrings explaining responsibility and collaborators, all public methods have docstrings with purpose, args, returns, and raises, and all non-obvious private methods have justification comments. Flag files with zero or minimal documentation as HIGH severity - undocumented code is unmaintainable code. Reference the "Code Commenting Standards" rules in CLAUDE.md for the full standard.