Review Implementation
Overview
Review code against markdown requirements and produce evidence-backed findings. When the user asks for fixes, apply targeted changes that bring the implementation back to the docs without expanding scope.
Modes
- Use review-only mode when the user asks to review, assess, audit, verify, or find issues.
- Use fix mode when the user asks to fix, update, refactor, complete, apply changes, or make the implementation match the docs.
- In fix mode, keep changes minimal and reversible. Do not add features that are not justified by the docs.
Workflow
1) Intake and Discovery Gate
- Read all provided.md files and extract explicit requirements, constraints, and acceptance criteria.
- Read repo guidance such as AGENTS.md, README, architecture notes, and existing task or PRD files when relevant.
- Inspect affected code, tests, fixtures, routes, schemas, migrations, services, components, permissions, config, and observability surfaces as needed.
- Identify the current behavior, expected behavior, data flow, integration points, validation options, and likely blast radius.
- Ask only when a critical decision cannot be made safely after discovery.
2) Map Requirements to Evidence
- Build an internal traceability map: requirement -> status -> code evidence -> gap -> action.
- Classify each requirement as satisfied, partial, missing, conflicting, overbuilt, or deferred.
- Use file/line evidence for important claims. Do not rely on general impressions when code can be inspected.
3) Run Multi-Pass Review
Review in this order:
- Requirements coverage: every requirement is satisfied or explicitly unresolved.
- Correctness: happy paths, edge cases, errors, empty states, permissions, state transitions, and rollback behavior are handled.
- Integration: changed modules fit together without contract breaks, duplicated ownership, or hidden assumptions.
- Simplicity: the solution is no more complex than necessary.
- Cleanup: repeated logic, dead code, temporary code, noisy logs, unused files, and unused dependencies are removed.
- Security/privacy: auth, access control, secrets, sensitive data, injection risks, and audit needs are safe.
- Performance: expensive queries, N+1 patterns, unnecessary renders, redundant network calls, and blocking work are addressed.
- Validation: chosen checks are appropriate for the risk.
- Documentation/operability: docs, release notes, migrations, rollback, monitoring, or support notes are updated when required.
Treat overbuilt code as a review finding when it adds features, abstractions, state, dependencies, or workflow paths not required by the docs.
4) Apply Focused Fixes
- Fix issues directly in code with minimal, targeted changes.
- Split overly long files/functions only when the split reduces real review or maintenance risk.
- Remove or simplify overbuilt code that is not justified by the docs.
- Preserve existing patterns unless the docs or code evidence justify a change.
- If PRD or phase files are part of the request, update checkboxes, validation notes, discoveries, and change logs only when implementation evidence supports the update.
5) Validate with Evidence
- Choose the smallest sufficient validation for the risk: static checks, unit tests, integration tests, API-level E2E, browser/UI checks, simulator checks, screenshots, manual smoke checks, or observability checks.
- Run relevant checks when available and appropriate. If checks are unavailable, too costly, or not allowed, state the gap and use the best available evidence.
- Do not run broad or expensive validation by reflex when a narrower check proves the changed behavior.
Report Format
Lead with the result that matters most:
- In review-only mode, list findings first in severity order with file/line references, then summarize coverage, validation, and residual risk.
- In fix mode, summarize fixes applied, validation performed, and any remaining findings or risks.
- If no issues are found, say so clearly and name any validation gaps.
- For critical blockers, stop and ask. For non-critical ambiguity, make the best reasonable decision, record the assumption, and continue.