Code Review

---
name: code-review
description: Review a branch or diff against PRD/PLAN and project standards. Asks single vs multi-angle when omitted. Use when reviewing a PR or invoking /code-review.
---

## STOP - Read before ANY tool call

1. Read `{{GUARDRAILS_PATH}}`
2. Read `_shared/sdd-artifacts/SESSION.md`; load session-state for `$Cwd`
3. If the relevant gate is not approved: **STOP** - ask user **(pt-BR)** - do **NOT** Write/Shell
4. SDD/develop skills: after **ONE** step/task, **STOP** session - handoff only
5. This skill body is **English**; user-facing prompts may be **(pt-BR)**

### Step -1 - Gate check (report in chat before continuing)

```
Gate check:
[ ] guardrails.mdc read
[ ] SESSION.md read; session-state loaded
[ ] PIPELINE.md read (SDD skills only)
[ ] User confirmed current action (sim)
-> If any unchecked: STOP
```

---

## Trigger

Invoke when the user asks for: `/code-review`, `review this PR`, `code review`.

**Review mode (mandatory choice - no silent default):**

| Mode | Explicit invoke examples |
|------|--------------------------|
| **Single** | `single`, `single-angle`, `simples` |
| **Multi-angle** | `multi-angle`, `multi-ângulo`, or `ângulos: qualidade, aceite, segurança` (subset allowed) |

If the invocation does **not** name single **or** multi-angle: **STOP** after gate check (-1) / before deep diff analysis - ask once **(pt-BR)** and wait. Do **not** assume single. Do **not** assume multi.

```text
Modo de code-review?
1) single - um revisor (passos -1..8)
2) multi-ângulo - qualidade + aceite + segurança (ou diga o subset)
```

## Outcome

A structured **review report** with severity tiers (critical / important / nice-to-have) and a clear decision: **Approved**, **Approved with reservations**, or **Changes required**. Write the report in **pt-BR** in chat-aligned reviews (technical terms may stay in English). Does not modify code unless the user asks for fixes in a follow-up.

## Required input

| Input | Rule |
|-------|------|
| Base branch | `main`, `develop` - ask once if missing |
| Feature branch | Current branch or named branch |
| PRD / PLAN (SDD) | Optional in invocation; **resolve in step 0.5** if omitted (see `references/sdd-resolution.md`) |
| Review mode | Explicit in invoke **or** answer to step 0.25 - never silent default |

Ask the user **only after** step 0.5 if zero or multiple PRD/PLAN pairs remain ambiguous. For a quick review without SDD artifacts, base branch + changed paths suffice after 0.5 reports no artifacts.

## Lazy-load (only when needed)

| When | Path (after sync) |
|------|-------------------|
| SDD artifact discovery (step 0.5) | `{{TOOLKIT_ROOT}}/skills/_shared/sdd-artifacts/STORAGE.md` |
| Repo context | `{{TOOLKIT_ROOT}}/skills/_shared/developer-common/step-0-context.md` |
| Before code analysis (.NET) | `{{TOOLKIT_ROOT}}/skills/_shared/dotnet-guidelines/clean-architecture.md`, `csharp-patterns.md` |
| Pre-PR gate (.NET) | `{{TOOLKIT_ROOT}}/skills/_shared/dotnet-guidelines/checklist.md` |
| .NET coverage report | `{{TOOLKIT_ROOT}}/skills/test-coverage/reference.md` (when PRD/user/PLAN requires coverage) |
| Principles | `{{TOOLKIT_ROOT}}/skills/_shared/code-guidelines/principles/principles-cheatsheet.md` |
| Policy / N+1 / contracts (WS16a) | `{{TOOLKIT_ROOT}}/skills/code-review/references/policy.md`, `n-plus-one.md`, `contracts.md` |
| Caveman Mode (if active) | `{{TOOLKIT_ROOT}}/skills/_shared/caveman/CAVEMAN.md` - **Full cap** |
| Final Git hygiene | `{{TOOLKIT_ROOT}}/skills/_shared/developer-common/step-7-checklist.md` |
| Spawn native vs fallback (capability `subagents`) | `{{TOOLKIT_ROOT}}/skills/_shared/agents/SPAWN.md` |
| Reference index (routing only) | `{{TOOLKIT_ROOT}}/skills/code-review/reference.md` |
| Process step detail (lazy) | `{{TOOLKIT_ROOT}}/skills/code-review/references/<section>.md` |

Prefer project `docs/standards/` or repo `AGENTS.md` over generic guidelines when both exist.

**Never by default:** do not preload all `references/*.md`, full guideline packs, or `code-guidelines/languages/**`. Load **one** `references/<section>.md` per Process step — never full `reference.md` when a section file exists (`SKILL-REFERENCE-RETRIEVAL.md`).

## Reference routing

| Situation | Path |
|-----------|------|
| SDD artifact resolution (0.5) | `references/sdd-resolution.md` |
| Report template | `references/report-template.md` |
| Verification / approval / coverage | `references/verification.md` |
| Policy family (skills/rules/git gates) | `references/policy.md` |
| N+1 / hot-path performance | `references/n-plus-one.md` |
| Contracts (SDD / CHANGE / API / plan markers) | `references/contracts.md` |
| .NET checklist | `references/dotnet-checklist.md` |
| Frontend checklist | `references/frontend-checklist.md` |
| Code smells | `references/code-smells.md` |
| Multi-angle mode | `references/multi-angle.md` |
## Process

Read `references/<section>.md` for procedural tables and checklists — **not** full `reference.md`.

### Step -1b - Caveman Mode (Full cap)
1. Read `{{SDD_ROOT}}/preferences.json` (create `{ "caveman_mode": false, "caveman_level": "full" }` if missing).
2. If `caveman_mode` is false: continue without compression.
3. If true: load `{{TOOLKIT_ROOT}}/skills/_shared/caveman/CAVEMAN.md`; apply **Full** participation cap + prefs `caveman_level` (Lite skills never escalate); show once: `[Caveman] Modo ativo (respostas compactas, level={effective}). Digite caveman off para desativar.`
4. Honor `caveman on|off|status|lite|full|ultra` (and `stop caveman` / `normal mode`) during the session.
5. Auto-Clarity + never-compress gates/drafts/paths per `CAVEMAN.md`.

### 0. Workspace
Confirm target repo (not this toolkit repo unless that is the subject). Detect stack (`*.sln` -> .NET; `angular.json` -> Angular). Read `AGENTS.md` / `README.md`. Load dotnet-guidelines only for .NET reviews.

For every reviewed path, discover `AGENTS.md` from repository root to the path.
The closest applicable local instruction governs local guidance, unless it conflicts
with higher-authority system, host, or repository instructions; expose such a
conflict in the report. Do not apply an instruction from a sibling directory.

### 0.25 Review mode (single vs multi-angle)
Resolve mode from the invocation **or** from the user's answer to the Trigger prompt.

| Signal in invoke / reply | Mode |
|--------------------------|------|
| `single` / `single-angle` / `simples` / `1` | Single reviewer (steps -1..8 only) |
| `multi-angle` / `multi-ângulo` / `2` / named `ângulos: …` | Multi-angle (see `references/multi-angle.md`) |

If still unset: **STOP** - ask the Trigger prompt **(pt-BR)** - do not continue to 0.5/1 until answered. Novice-friendly: never pick a default for them.

### 0.5 Resolve SDD artifacts
Load `STORAGE.md`. Follow **`references/sdd-resolution.md`**. Use full paths in the report. If one PRD/PLAN pair -> read both before the diff review. If none after a full search -> note **SDD limitation** in the report (technical review only). If ambiguous -> ask once in pt-BR with numbered options.

### 1. Scope the diff

```bash
git fetch origin  # when remote comparison is needed
git diff <base>...<head> --stat
git diff <base>...<head>
git log <base>..<head> --oneline
```

Default `<head>` to current branch. List files; confirm with user before deep review if the set is large.

### 2. SDD traceability (when artifacts found or user provided)
Skip this section only when step 0.5 found no PRD/PLAN (document limitation - do not claim artifacts do not exist).

- PLAN progress bar and step statuses match completed work
- Each **Completed** / **Concluido** step has deliverables checked; no **Pending** steps with code already merged
- PRD acceptance criteria mapped to implementation and tests

Flag PLAN/PRD drift as **important** (not necessarily blocking if scope is otherwise correct).

### 3. Standards and guidelines
1. Project `docs/standards/` or equivalent
2. `{{TOOLKIT_ROOT}}/skills/_shared/dotnet-guidelines/` for .NET (layers, tests: xUnit, Moq, Shouldly, `Should_<Result>_When_<Condition>`)
3. Principles cheatsheet when installed
4. **WS16a families (actionable refs — load when surface matches; pointers only):**
   - Policy → `references/policy.md`
   - N+1 / hot-path → `references/n-plus-one.md`
   - Contracts → `references/contracts.md`

### 4. Code analysis
Review changed files using focus areas + checklists in `references/verification.md`, `references/dotnet-checklist.md`, `references/frontend-checklist.md`, `references/code-smells.md`, and the matching WS16a family refs (`policy` / `n-plus-one` / `contracts`) - do not paste full guideline or policy bodies into the report.

### 5. Run verification (when feasible)
Follow `references/verification.md`. For .NET with a coverage target: run `test-coverage` before final decision; paste the summary into the report section Testes. If `test-coverage` reports **Fail** (< threshold), treat as **Changes required** unless the user documents an accepted exception. Record pass/fail in the report. Missing local run -> note as limitation.

### 6. Decision
Apply approval criteria in `references/verification.md` (**Approved** / **Approved with reservations** / **Changes required**).

### 7. Write report
Use `references/report-template.md`. Be specific: `path:line`, explain **why**, suggest **how** to fix. Include positives.

### 8. Optional PR (user-driven)
Create a PR only when the user asks and review is not **Changes required**:
1. Ensure the feature branch is pushed (`/push` after confirmation if needed).
2. Hand off to **`/open-github-pr`** (do not open the GitHub web UI compare flow from this skill; `/open-github-pr` owns CLI/templates/confirmation/auto-merge).

No MCP work-item linking or mandatory corporate PR templates.

## Multi-angle mode (when chosen)
Run **only** after step **0.25** resolved to multi-angle. Follow `references/multi-angle.md` (SPAWN first; parallel Task when `native`; fallback sequential in-parent). Parent synthesizes into **one** report using `references/report-template.md`. Decision matrix and coverage gates unchanged.
## Must not

- Write or update PRD/PLAN files (hand off to `/sdd-spec` / `/sdd-plan`)
- Auto-merge, auto-approve, or rewrite code without user request
- Work-item tracker APIs, external PR platform APIs, or obsolete guideline paths
- Block on coverage only when no target applies - when PRD, PLAN, user, or a `test-coverage` report defines a threshold (default **80%** on changed production files), treat below threshold as **Changes required**
- Paste entire guideline files into the review output
- Claim no PRD/PLAN or skip step 0.5 / SDD traceability without searching all locations in `STORAGE.md`
- Assume **single** or **multi-angle** when the user did not name either (always ask - step 0.25)
- Force multi-angle as a pipeline gate, or create separate mandatory blind-reviewer skills
- Hard-fail multi-angle when `subagents` is `none` or Task is unavailable (use **fallback** sequential **in-parent** per `SPAWN.md`)
- Paste guideline packs into Task child prompts
- Create `framework-upgrade` or any new product skill folder from this skill (WS16b OOS — needs a separate approved feature)
- **AI co-author trailers** - in any form. Under NO circumstances should you include `Co-authored-by: Cursor <cursoragent@cursor.com>`, `Co-authored-by: Antigravity`, or any other AI agent attribution in commit messages or PR descriptions.

## Handoff

| Situation | Next |
|-----------|------|
| After O3 (`orchestrate-develop`) completes | First `/run-tests`, then `/code-review`; after review changes, `/run-tests` again, then the security role/prompt review of the diff. The security handoff is `{{TOOLKIT_ROOT}}/skills/_shared/agents/prompts/security.md`, using only a documented host mechanism or bounded in-parent fallback; never claim a `/security` command. |
| New feature / PRD from review findings | `/sdd-spec` - paste or summarize review items; do **not** write PRD in this skill |
| Coverage below threshold | `/test-coverage` -> then `/dotnet-developer` or `/sdd-develop` |
| Fixes needed | `/developer` / `/sdd-develop` / stack `*-developer` (user chooses) |
| After fixes (recommended) | Ask re-review / bank / docs — see § Recommended post-review loop |
| Commit (after living-artifact asks) | `/commit` |
| All SDD steps done + approved | User opens PR in GitHub UI or merges per repo policy |

### Recommended post-review loop (not mandatory)

When the decision is **Changes required** (or the user fixed findings), **ask each** and wait (**sim** / **pular**) — never force. Any review change requires the post-review `/run-tests` stage before the security handoff:

```text
Fluxo recomendado após o review:
1) Corrigir com /developer ou /sdd-develop (ou *-developer) — já feito / fazer agora?
2) Rodar /code-review de novo para validar as correções? (sim / pular)
3) Atualizar memory-bank (refresh-light)? (sim / pular)   [só se bank existir]
4) Atualizar documentação do projeto? (sim / pular)       [só se docs/plan existirem]
```

On **sim** for (2) → new `/code-review` session. On **sim** for (3) → `/memory-bank-init` `refresh-light`. On **sim** for (4) → `/document-implement` if plan has pending work, else `/document-plan` as needed. Then offer `/commit` (commit skill also asks bank/docs if still pending).

## Finding shape

Review only the sections the diff touches. Each finding names a file and a line, with severity `critical`, `important`, or `advisory`. Do not add a praise section. A `critical` finding stops blocking only after a fix and a new review, at most three rounds. Do not downgrade it to proceed. Render the questions above in the user chat language.