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:

1. Requirements coverage: every requirement is satisfied or explicitly unresolved.
2. Correctness: happy paths, edge cases, errors, empty states, permissions, state transitions, and rollback behavior are handled.
3. Integration: changed modules fit together without contract breaks, duplicated ownership, or hidden assumptions.
4. Simplicity: the solution is no more complex than necessary.
5. Cleanup: repeated logic, dead code, temporary code, noisy logs, unused files, and unused dependencies are removed.
6. Security/privacy: auth, access control, secrets, sensitive data, injection risks, and audit needs are safe.
7. Performance: expensive queries, N+1 patterns, unnecessary renders, redundant network calls, and blocking work are addressed.
8. Validation: chosen checks are appropriate for the risk.
9. 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.