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.

1. Correctness: happy paths, edge cases, errors, empty states, permissions,

state transitions, and rollback behavior are handled.

1. Integration: changed modules fit together without contract breaks,

duplicated ownership, or hidden assumptions.

1. Simplicity: the solution is no more complex than necessary.
2. Cleanup: repeated logic, dead code, temporary code, noisy logs, unused files,

and unused dependencies are removed.

1. Security/privacy: auth, access control, secrets, sensitive data, injection

risks, and audit needs are safe.

1. Performance: expensive queries, N+1 patterns, unnecessary renders, redundant

network calls, and blocking work are addressed.

1. Validation: chosen checks are appropriate for the risk.
2. 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.