code-review-guideline

name	code-review-guideline
description	The review methodology for every review task, including post-implementation self-review. Covers reviewer-mode reset, diff scoping with `git status`/`git diff`, severity labels, file-line evidence, fix snippets, verification evidence, second-pass re-review after fixes, escalation for high-risk changes, and topic-specific lenses for maintainability, QA, security, performance/reliability, project structure, UI/components, and e2e tests.
when_to_use	Apply at the start of EVERY review task — "review", "PR", "audit", "check this change", or a self-review of your own diff before claiming completion.
user-invocable	false

Code Review Guideline

Apply these rules at the start of every code review, regardless of the change type or domain.

Reviewer-Mode Reset

Self-review is not independent review, so this project makes it a separate required phase with explicit evidence. After implementation, the reviewer stops editing, rereads the request, inspects the diff, and reviews the produced change as if another author wrote it.

Guidelines:

• MUST perform a reviewer-mode reset before post-implementation self-review.
• MUST inspect git status and the relevant git diff before reading surrounding files.
• MUST judge only the diff and affected behavior, not the implementation intent.
• MUST fix Critical or Major findings in a later implementation phase, then perform a second-pass re-review.
• MUST report verification evidence or skipped verification before completion.
• SHOULD escalate high-risk changes per escalation.md instead of calling them merge-ready based on self-review alone.

Review Scoping

See scoping.md for:

• Discovering what changed via git diff / git status / gh pr diff
• Distinguishing in-scope (the diff) from out-of-scope (pre-existing)
• Reading surrounding code to understand caller/callee context
• Handling untracked files and partial diffs

Severity Classification

See severity.md for:

• Critical, Major, Minor, Nit definitions with concrete project examples
• Required severity for each major issue category (security, data loss, broken e2e, etc.)
• How severity drives the final verdict (Approve / Approve with Nits / Request Changes)

Repository Review Policy Overlay

When the review output is a posted pull-request review — the CI reviewer — REVIEW.md at the repo root is the authoritative policy and overrides the vocabulary below where they differ. The internal Critical/Major/Minor/Nit triage still drives self-review; the posted report follows REVIEW.md.

Guidelines:

• MUST apply REVIEW.md on top of this methodology for any posted PR review, and let it win on conflict.
• MUST collapse the posted report to REVIEW.md's label set (Important / Nit) and open the summary with its one-line tally when REVIEW.md defines them, instead of the four-tier report sections below.
• MUST run every mandatory check REVIEW.md lists on a posted review and raise a finding for each miss, grading it by the severity floors below (a miss that breaks the requirement is Important).
• MUST treat every acceptance criterion of the linked issue that the diff leaves unmet or unverifiable as an Important posted finding.
• MUST report every finding in a posted review — REVIEW.md sets no nit cap, so do not drop or summarize findings away (repeated identical nits may share one comment).
• MUST NOT report, in a posted review, findings the repo policy excludes — CI-enforced Biome lint/format and TypeScript errors — even though the severity floors below would otherwise rate them Critical.
• MUST keep a posted review COMMENT-type (never APPROVE / REQUEST_CHANGES), per the project's GitHub operation guidelines; the reviewer is advisory and does not gate merges.

Evidence-Based Reporting

See evidence.md for:

• Mandatory file:line citations
• Diff-style fix snippets (- removed / + added)
• The full review-report structure (Summary, Strengths, Findings by severity, Recommended Actions)
• Linking findings to the topic-specific guideline that was violated

Review Tone

See tone.md for:

• Constructive, blame-free language
• Stating the "why" behind each concern
• Explicit assumption-flagging when uncertain
• Acknowledging strengths

Escalation

See escalation.md for:

• How to make findings trivially applicable by the caller without requiring another reviewer to reinterpret them
• Keeping the review phase reporting-only, without mutating the codebase or delegating the review
• How to surface recurring guideline gaps as a "Guideline gap:" note in the report
• When a finding requires the caller's decision (framed as a "Decision needed:" entry)
• When high-risk changes require user review, CI/PR review, or explicit acceptance before being called merge-ready

Topic-Specific Guidelines

Consult the appropriate skill for detailed review checklists in each lens. These are the reviewer's lens; they layer on top of the developer-facing guidelines linked at the bottom and add "what to flag" rather than "how to write".

Lens	Skill
Readability, naming, complexity, abstraction boundaries, scope discipline, dead code	the project's maintainable-code guidelines
Verifying e2e coverage, snapshot handling, flakiness, manual verification, lint/format gate	the project's quality-assurance guidelines
OWASP-lens application security — secrets, input validation, access control, XSS, SSRF, auth, supply chain	the project's application-security requirements
Data-layer query cost (N+1), server/client boundary cost, caching correctness, asset/image optimization, bundle weight, error and observability hooks	the project's performance-and-reliability requirements

In addition to the lenses above, the reviewer MUST also load the project's own topic-specific skills when they overlap the diff — repository structure and file placement via the project's project-structure guidelines, and components, hooks, styling, and UI implementation via the project's React guidelines. Consult whichever ones overlap the change.

Guidelines:

• MUST choose every topic-specific lens that materially overlaps the diff before reporting findings.
• SHOULD cite the owning lens when a finding depends on a specialized project rule.
• MUST NOT treat this table as exhaustive when the diff has an obvious topic covered by a developer-facing skill below or by a project-specific skill such as the project's project-structure guidelines or the project's React guidelines.

Developer-Facing Guidelines (defer, do not duplicate)

Developer-facing skills own how to write project-conforming code. The review skill owns how to report whether the diff followed those rules.

Topic	Skill
Format/lint loop, change scope discipline, and dependency rules	the project's development guidelines
End-to-end test structure, conventions, and commands	the project's end-to-end testing guidelines
Unit test structure, conventions, mocks/fixtures, and commands	the project's unit-test guidelines

In addition, the reviewer MUST defer to the project's own developer-facing skills — repository structure and file placement via the project's project-structure guidelines, and component conventions, hooks, styling, and UI implementation via the project's React guidelines. Cite whichever ones overlap the change instead of restating their rules.

Guidelines:

• MUST defer to these developer-facing skills when checking that a change conforms to project conventions.
• MUST cite and link the owning guideline instead of restating its detailed rule in the review report.