doc-code-review-report

Doc Code Review Report

Overview

Review the user's text or document as a claim source, then verify those claims against the real codebase. Produce an evidence-backed review report, not a summary, and separate confirmed issues from inference.

Read references/report-template.md only when you need a ready-made report scaffold.

Workflow

1. Normalize the review input.

• Accept plain text, Markdown, notes, PR descriptions, API docs, or design documents.
• Extract concrete claims: intended behavior, request flow, data fields, state changes, error handling, and unfinished work markers.
• If the input is broad, narrow it to the specific flow, module, or interface under review.

1. Locate the implementation before judging it.

• Find the real entry points first: routes, pages, handlers, services, schedulers, workers, repositories, generated clients, OpenAPI specs, or protocol types.
• Prefer concrete call paths over keyword-level guesses.
• If the document describes a frontend flow, trace both UI state transitions and backend requests.

1. Verify behavior claim by claim.

• Check whether the implemented logic matches the stated requirement or document claim.
• Distinguish:
  • documented but not implemented
  • implemented but undocumented
  • implemented differently from the document
  • behavior cannot be confirmed from current code

1. Review for correctness and bug risk.

• Look for broken conditions, missing branches, invalid assumptions, stale state, race windows, missing null or empty handling, unchecked errors, and inconsistent data transformations.
• Treat "works on happy path only" as a real finding when failure branches are absent or contradicted by the input document.

1. Cross-check frontend and backend contracts when the flow crosses layers.

• Confirm method, path, path params, query params, body fields, enum values, response fields, and error shapes.
• Compare frontend request builders, generated API clients, backend handlers, service DTOs, protocol definitions, and local OpenAPI or schema files.
• Flag mismatches such as renamed fields, optional-vs-required drift, type drift, enum drift, and response shape assumptions unsupported by backend code.