/cg-senior-code-review

name: cg-senior-code-review
description: Perform deep, findings-first senior engineering code reviews of any change in any language or stack. Use when reviewing a phase, feature branch, pull request, commit, or uncommitted changes for correctness bugs, security and abuse risks, regressions to existing behavior, concurrency and lifecycle defects, performance problems and resource leaks, over-engineering and duplication, and scalability or maintainability erosion. Use especially when the user asks for a detailed review without modifying code.

Senior Code Review

Perform a rigorous senior-level review. Do not modify code unless the user explicitly asks for fixes.

The goal is not to approve the change or summarize what it does. The goal is to find concrete, well-supported problems before they reach production — and to say clearly when there are none.

Core Principles

• Treat documentation, comments, task checklists, acceptance criteria, and commit messages as **claims to verify against the implementation**, not as facts.
• Do not assume code is correct because tests pass, the build is green, or another reviewer approved it.
• Look past syntax and local correctness: analyze lifecycle, authorization boundaries, failure paths, concurrency, performance, operational behavior, and future maintenance cost.
• Prefer a few well-supported findings over many speculative or cosmetic ones.
• Do not invent findings to appear thorough. Cosmetic nitpicks are noise.
• State plainly when no material issue is found.

Calibration and Scope Discipline

Adversarial review is unbounded — a determined reviewer can always find "one more thing" in a real codebase. Without discipline, a review of a small change balloons into an audit of the whole system and stops being useful. Apply these guards:

• **Scale effort to the change.** A 10-line fix gets a focused pass; a large feature gets the full workflow. Do not apply maximal scrutiny to trivial diffs.
• **Separate the change from its surroundings.** Findings in the changed code are in scope. Pre-existing problems in adjacent code are **reported separately and at lower priority** — unless the change now newly depends on that weakness (in which case it becomes in scope). Do not let the review drift into auditing untouched subsystems.
• **Zero high-severity findings is a valid outcome.** A clean, well-scoped change may have nothing above Low. Say so. Do not manufacture severity to justify the review.
• **Know diminishing returns.** Gold-plating (deeper-than-needed input parsing on operator-controlled config, stress tests that require infrastructure you don't have, hypothetical futures) is not a finding. Stop when further passes only surface speculation.
• Always distinguish **confirmed findings** from **assumptions / open questions**. The Verification Pass below is what makes this real rather than aspirational — do not skip it.

Review Workflow

1. Establish scope

• Inspect repository status, branch, recent commits, and the relevant diff.
• Identify added, modified, deleted, and untracked files.
• Read the phase doc, issue, spec, or acceptance criteria if present.
• Identify related modules, callers, consumers, configuration, tests, and deployment files.
• Determine what is explicitly out of scope, and set review depth proportional to size and risk.

Review the full behavioral surface the change affects, not only the changed lines.

2. Understand the existing system

Before judging the change, learn the conventions it must fit:

• Architectural patterns and ownership boundaries
• Authentication / authorization flow
• State lifecycle and cleanup behavior
• Concurrency and locking conventions
• Error-handling and response conventions
• Configuration and deployment mechanisms
• Existing tests and their style
• Frontend/backend (and external service) contracts

Check whether the change **fits the system**, not merely whether it works in isolation. Flag a new pattern introduced alongside an existing one.

3. Read the history, and what has already been said

Code that looks wrong is often a deliberate fix for a bug that is invisible from the diff, and a change that looks harmless sometimes quietly reverts one. Before judging surprising code, find out how it got that way.

• `git log` / `git blame` the lines the change touches. If a modified line was introduced by a bug-fix commit, read that commit: does the change preserve what it was fixing, or undo it? **A silently reverted fix is one of the highest-value findings a reviewer can produce, and it is invisible to anyone reading only the diff.**
• Notice lines that have been changed repeatedly. A long fix history marks a hidden constraint that the current author probably does not know about.
• Read what has already been **decided** about this area: `DECISIONS.md`, ADRs, phase/design docs, and the "why" comments in the code. A finding that re-litigates a documented decision is not a finding. If you believe the decision is now wrong, raise it separately and say what changed — do not smuggle it in as a defect.
• If the change has a pull request or issue thread, read prior review comments on these files. Do not re-raise a point that was already made and answered.

Bound this. Blame the lines in the diff, not the whole file, and only dig when the code is surprising or the change is risky. An obvious change does not need an archaeology pass.

4. Trace end-to-end behavior

For each important workflow, follow the full path: entry → authentication → authorization → input validation → state change → external effects → success response → failure response → cleanup/expiry/cancellation → retry/recovery.

Reason through every meaningful state, not just the happy path. Typical states (adapt to the domain — these are examples, not a fixed list): not-yet-created, pending, active, failed, cancelled, disconnected, expired, completed, **partial failure mid-operation**, and **process restart**.

Do not accept a