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, observability, 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 or a managed review product — REVIEW.md at the repo root is the authoritative policy and overrides the vocabulary in this skill where they differ. The internal Critical/Major/Minor/Nit triage and verdict mapping still drive 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, instead of the four-tier report sections and severity labels used internally.
• MUST suppress the internal verdict vocabulary in posted output: no Approve / Approve with Nits / Request Changes verdict appears in a posted review.
• 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 in severity.md (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 REVIEW.md's do-not-report list excludes (CI-enforced checks, lockfiles, generated files), even where the severity floors 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, XSS, SSRF, supply chain	the project's application-security requirements
Server/client boundary cost, caching correctness, asset/image optimization, bundle weight, error and observability hooks	the project's performance-and-reliability requirements
File placement, directory tiers, routing conventions	the project's project-structure skill
Component/hook construction, tier boundary, styling composition, test-id hooks	the project's component guidelines
Appearance — token roles, control selection, copy, accessibility intent	the project's UI design principles

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.

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, dependency rules	the project's development guidelines
Error handling and error reporting	the project's observability 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
Repository layout, file placement, routing conventions	the project's project-structure skill
Component conventions and stores	the project's component guidelines
Visual design vocabulary	the project's UI design principles
PTCGP card model, deck rules, dataset conventions	the project's PTCGP domain skill

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.