Code Review

code-review

Overview

| Field | Contract | | --- | --- | | Purpose | Apply one review discipline for diffs, feedback, and completion claims. | | Primary input | PR, commit, pending diff, codebase scope, reviewer feedback, or completion claim. | | Primary output | Findings-first verdict, feedback response, verification gate result, or fix-review cycle. | | Boundary | Do not claim done/fixed/passing without fresh verification evidence. | | Next handoff | Fix highest-severity findings, re-run verification, then ship when ready. |

Use one review discipline everywhere: receive feedback rigorously, request adversarial review, and make completion claims only with fresh evidence.

There is no separate review command or wrapper. Invoke this skill directly (/code-review) for standalone reviews, feedback reception, and completion gates. cook, fix, and ship dispatch the code-reviewer agent directly with their own scoped context (phase brief, root-cause claim, readiness evidence) — they share this skill's verdict contract but do not re-run the standalone protocol below on top of their own review steps.

Resources

| Practice | Load When | File | | --- | --- | --- | | Receiving feedback | Reviewer comments are unclear, risky, or conflict with local context | references/code-review-reception.md | | Requesting review | Cook/fix finished a phase, before merge, or standalone review is requested | references/requesting-code-review.md | | Verification gates | Before any done/fixed/passing/complete claim | references/verification-before-completion.md |

Modes

| Mode | Use | | --- | --- | | Standalone review | PR, commit, --pending, or scoped codebase audit | | Feedback reception | User pastes review feedback or a reviewer finding | | Completion gate | Before any done/fixed/passing/complete claim | | Fix-review cycle | User asks to fix review blockers and re-review |

Support Skill Triggers

Load a support skill as a review lens when the diff contains the trigger:

| Trigger | Load | | --- | --- | | weak or missing test evidence | engineering-practices (references/testing.md) | | auth, user input, secrets, PII, webhook, external integration | engineering-practices (references/security.md) | | framework/library/API behavior depends on version or current docs | source-grounding | | production behavior lacks logs, metrics, traces, or alerting | engineering-practices (references/observability.md) | | schema/data/API migration, deprecation, backward compatibility | engineering-practices (references/migration.md) | | public docs, setup, API docs, or ADR should change | engineering-practices (references/docs.md) |

Standalone Review Protocol

Use this protocol for standalone review requests (/code-review or an explicit review ask).

| Mode | Resolve Diff With | | --- | --- | | #123 | gh pr diff 123 after confirming gh exists and is authenticated | | ` | git show | | --pending | git diff HEAD plus staged/unstaged awareness | | codebase parallel` | scoped module audits with separate review lenses |

If the mode's tool is unavailable, stop and report the missing dependency. Do not silently fall back to another mode.

Step 1 - Resolve Diff And Scope

1. Resolve the diff for the selected mode.
2. Record changed files, line counts, and risky file categories.
3. Find the governing plan/spec/intent. If none exists, review against the stated intent and flag "no governing artifact".

Step 2 - Scout Review Context

Run scout --review over the diff. The scout report must identify:

• changed files and adjacent contracts
• governing plan/spec/intent, if found
• data/auth/migration/concurrency/boundary risks
• edge-case probes for adversarial review

Step 3 - Spec Compliance Gate

Handle this inline before delegating:

• Does each meaningful change map to a plan/spec/intent item?
• Is anything outside declared scope?
• Does any change violate acceptance criteria or public contract?

Any critical spec violation forces final verdict BLOCK, even if the code quality pass is clean.

Step 4 - Code Quality And Adversarial Review

Spawn code-reviewer with minimal context:

• diff or review package path
• spec compliance findings
• scout --review report
• explicit acceptance criteria or stated intent

For broad diffs, split by clear ownership and deduplicate findings after reviewers return.

On explicit @advisor mention — or on user request for a diff touching security, data, or a public contract — add an advisor pass alongside code-reviewer: hand it the diff, governing intent, and scout report as a compact bundle. The advisor answers the strategic question ("is this the right change at all?"); code-reviewer findings still drive the verdict table alone.

Run the adversarial pass unless the strict exemption applies: APPROVE`

• WARNING -> REQUEST CHANGES
• BLOCK -> BLOCK

Output findings first, grouped by severity, then the verdict line.

Receiving Feedback Protocol

Load references/code-review-reception.md when feedback arrives. Use it to verify claims before editing, separate valid feedback from unsupported feedback, and respond with evidence.

Verification Gate

Load references/verification-before-completion.md before any completion claim. Use it to ensure done/fixed/passing claims are backed by fresh command output or equivalent evidence, not reasoning.

Fix-Review Cycle

When review blocks and the user asks to fix:

1. Fix the highest-severity actionable findings first.
2. Re-run focused verification for the changed area.
3. Re-run review on the updated diff.
4. Stop after 3 failed cycles and report the remaining blocker.

Use a different repair approach each cycle. Repeating the same fix with different wording is not a new approach.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: danielleit241
• Source: danielleit241/forge
• License: ISC

Install and usage instructions live in the source repository linked above.