4R Code Review
When to Use
Use this skill when a coding task is reported complete and BEFORE declaring it done, committing, pushing, or opening a PR — especially when the change was produced wholly or partly by a coding agent.
Use it to run a systematic, stack-agnostic review across four dimensions — Risk, Readability, Reliability, Resilience — that classifies findings by severity, surfaces fixable defects, and returns an explicit accept/block decision.
Do NOT use this skill to write the feature, design architecture from scratch, or audit non-code artifacts (use reviewer for PRDs, specs, and API contracts). This skill reviews a code diff, not prose.
Operating Workflow
- Scope the diff. Run
git diff / git diff --staged (and git status) to get exactly what changed. Review the diff and its blast radius, not the whole repo.
- Tier the review. Match effort to risk (see Decision Rules). Do not burn a deep 4R pass on a one-line doc typo; do not shortcut a change that touches auth, data, or money.
- Confirm intent match. Verify the change does what the task asked AND ONLY that. Flag edits outside the intended scope, stray files, and unrequested behavior changes.
- Run the 4R passes. Evaluate each dimension against
references/4r-dimensions.md. Prioritize the AI failure patterns listed there — agent code passes the eye test and fails differently than human code.
- Gather evidence. Run the test suite / linter / build when available. Treat "looks correct" as unproven until executed. Record commands and results.
- Classify and decide. Tag every finding with severity, score each R 0–2, and return one verdict: Approve / Approve with follow-up / Request changes / Escalate.
Core Rules
- Evidence over intention: tests run, errors handled, limits set, and observability must be VISIBLE in the change, not assumed.
- Code that looks correct is not evidence that it is correct. Trace the unhappy paths explicitly.
- Complexity is a budget. A change that adds branches, state, or abstraction must justify the cost; reject or simplify accidental or AI-inflated complexity.
- Be specific and actionable. Never say "security is missing" — name the file, line, failure mode, and the fix direction.
- Never approve a change with a Blocker in Risk or Resilience. A residual risk must be explicit, bounded, and proportional.
The 4R Dimensions
| R |
Central question |
Covers |
| Risk |
Does this add disproportionate risk to security or production? |
Auth, secrets, trust boundaries, input validation, injection, blast radius, rollback. |
| Readability |
Can another engineer maintain this without rebuilding the author's intent? |
Naming, structure, duplication, complexity budget, AI slop. |
| Reliability |
Is there real evidence it works on normal AND edge inputs? |
Tests that catch bugs, edge cases, error handling, timeouts, correctness. |
| Resilience |
When it fails, does the system recover or cascade? |
Retries with backoff, fallback, graceful degradation, observability, isolation. |
Full per-dimension checklists, AI-specific failure patterns, and acceptance criteria are in references/4r-dimensions.md — read it before the 4R passes.
Decision Rules
| Situation |
Action |
| Diff is trivial (docs, comments, formatting) |
Quick pass: intent match + Risk scan only; skip deep 4R. |
| Diff touches auth, secrets, payments, data, or infra |
Full 4R + mandatory Escalate consideration; no Blockers allowed. |
| Agent-generated logic, new integration, or 2+ files |
Full 4R; prioritize AI failure patterns and test quality. |
| Tests absent where change warrants them |
Reliability ≤ 1; Request changes unless risk is low AND justified in writing. |
| Blocker in Risk or Resilience |
Block. Do not approve regardless of other scores. |
| Change exceeds reviewer's authority or domain |
Escalate to specialized/human review. |
Severity
| Severity |
Meaning |
| 🔴 Blocker |
Probable vulnerability, data loss, critical regression, plausible cascade, unbounded risk in a sensitive zone. |
| 🟠 High |
Missing tests on a critical path, absent timeout, wrong retry, excessive complexity in core logic, weak observability at a critical point. |
| 🟡 Medium |
Improvable readability, bounded uncovered edge case, documentable debt without immediate impact. |
| 🔵 Low |
Naming, minor structure, non-critical simplification. |
Scorecard
Score each R 0–2 (0 = insufficient, 1 = acceptable with reservations, 2 = solid). Merge rule: minimum 1 per dimension, no 0 in Risk or Resilience, target average ≥ 1.5. Any security Blocker or plausible cascade invalidates the aggregate until fixed.
Output Contract
Produce the report in assets/4r-review-report.md. Required sections: Context, one block per R (verdict Pass/Concern/Block + findings table), a severity-tagged findings list, the 0–2 scorecard, and a Final Decision (status + residual risk + required actions before merge + follow-ups). End with one explicit sentence: whether the change may be committed/pushed or must return to iteration.
Quality Checklist
Before returning the review, verify:
References
references/4r-dimensions.md — per-dimension checklists, AI failure patterns, acceptance criteria. Read before the 4R passes.assets/4r-review-report.md — report template. Fill for every review.
1---2name: 4r-code-review3description: Trigger: 4R code review, review this change, review agent code, pre-commit review, is this done, quality gate before commit. Run a Risk/Readability/Reliability/Resilience review on a completed change before declaring it done.4license: Apache-2.05---67# 4R Code Review89## When to Use1011Use this skill when a coding task is reported complete and BEFORE declaring it done, committing, pushing, or opening a PR — especially when the change was produced wholly or partly by a coding agent.1213Use it to run a systematic, stack-agnostic review across four dimensions — **Risk, Readability, Reliability, Resilience** — that classifies findings by severity, surfaces fixable defects, and returns an explicit accept/block decision.1415Do NOT use this skill to write the feature, design architecture from scratch, or audit non-code artifacts (use `reviewer` for PRDs, specs, and API contracts). This skill reviews a code diff, not prose.1617## Operating Workflow18191. **Scope the diff.** Run `git diff` / `git diff --staged` (and `git status`) to get exactly what changed. Review the diff and its blast radius, not the whole repo.202. **Tier the review.** Match effort to risk (see Decision Rules). Do not burn a deep 4R pass on a one-line doc typo; do not shortcut a change that touches auth, data, or money.213. **Confirm intent match.** Verify the change does what the task asked AND ONLY that. Flag edits outside the intended scope, stray files, and unrequested behavior changes.224. **Run the 4R passes.** Evaluate each dimension against `references/4r-dimensions.md`. Prioritize the AI failure patterns listed there — agent code passes the eye test and fails differently than human code.235. **Gather evidence.** Run the test suite / linter / build when available. Treat "looks correct" as unproven until executed. Record commands and results.246. **Classify and decide.** Tag every finding with severity, score each R 0–2, and return one verdict: Approve / Approve with follow-up / Request changes / Escalate.2526## Core Rules2728- Evidence over intention: tests run, errors handled, limits set, and observability must be VISIBLE in the change, not assumed.29- Code that looks correct is not evidence that it is correct. Trace the unhappy paths explicitly.30- Complexity is a budget. A change that adds branches, state, or abstraction must justify the cost; reject or simplify accidental or AI-inflated complexity.31- Be specific and actionable. Never say "security is missing" — name the file, line, failure mode, and the fix direction.32- Never approve a change with a Blocker in Risk or Resilience. A residual risk must be explicit, bounded, and proportional.3334## The 4R Dimensions3536| R | Central question | Covers |37|---|---|---|38| **Risk** | Does this add disproportionate risk to security or production? | Auth, secrets, trust boundaries, input validation, injection, blast radius, rollback. |39| **Readability** | Can another engineer maintain this without rebuilding the author's intent? | Naming, structure, duplication, complexity budget, AI slop. |40| **Reliability** | Is there real evidence it works on normal AND edge inputs? | Tests that catch bugs, edge cases, error handling, timeouts, correctness. |41| **Resilience** | When it fails, does the system recover or cascade? | Retries with backoff, fallback, graceful degradation, observability, isolation. |4243Full per-dimension checklists, AI-specific failure patterns, and acceptance criteria are in `references/4r-dimensions.md` — read it before the 4R passes.4445## Decision Rules4647| Situation | Action |48|---|---|49| Diff is trivial (docs, comments, formatting) | Quick pass: intent match + Risk scan only; skip deep 4R. |50| Diff touches auth, secrets, payments, data, or infra | Full 4R + mandatory Escalate consideration; no Blockers allowed. |51| Agent-generated logic, new integration, or 2+ files | Full 4R; prioritize AI failure patterns and test quality. |52| Tests absent where change warrants them | Reliability ≤ 1; Request changes unless risk is low AND justified in writing. |53| Blocker in Risk or Resilience | Block. Do not approve regardless of other scores. |54| Change exceeds reviewer's authority or domain | Escalate to specialized/human review. |5556### Severity5758| Severity | Meaning |59|---|---|60| 🔴 Blocker | Probable vulnerability, data loss, critical regression, plausible cascade, unbounded risk in a sensitive zone. |61| 🟠 High | Missing tests on a critical path, absent timeout, wrong retry, excessive complexity in core logic, weak observability at a critical point. |62| 🟡 Medium | Improvable readability, bounded uncovered edge case, documentable debt without immediate impact. |63| 🔵 Low | Naming, minor structure, non-critical simplification. |6465### Scorecard6667Score each R 0–2 (0 = insufficient, 1 = acceptable with reservations, 2 = solid). Merge rule: minimum 1 per dimension, no 0 in Risk or Resilience, target average ≥ 1.5. Any security Blocker or plausible cascade invalidates the aggregate until fixed.6869## Output Contract7071Produce the report in `assets/4r-review-report.md`. Required sections: Context, one block per R (verdict Pass/Concern/Block + findings table), a severity-tagged findings list, the 0–2 scorecard, and a Final Decision (status + residual risk + required actions before merge + follow-ups). End with one explicit sentence: whether the change may be committed/pushed or must return to iteration.7273## Quality Checklist7475Before returning the review, verify:76- [ ] Review is based on the actual diff, with tests/linter/build run when available.77- [ ] Intent match confirmed: change does what was asked and nothing extra.78- [ ] All four R dimensions evaluated; AI failure patterns checked on agent code.79- [ ] Every finding cites a file/line, the failure mode, and an actionable fix.80- [ ] Severity assigned by impact; scorecard filled; merge rule applied.81- [ ] No Blocker left in Risk or Resilience before any Approve.82- [ ] Final decision is explicit and unambiguous.8384## References8586- `references/4r-dimensions.md` — per-dimension checklists, AI failure patterns, acceptance criteria. Read before the 4R passes.87- `assets/4r-review-report.md` — report template. Fill for every review.
GustavoGutierrez