# Sk Code Review

> Stack-agnostic code-review for sk-code: findings-first severity, security/correctness minimums, and surface evidence.

- Skill: `michelkerkmeester/sk-code-review` (Agent Skill, multi-file: 141 files)
- Install (CLI): `npx get-skill add michelkerkmeester/sk-code-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/michelkerkmeester/sk-code-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: MichelKerkmeester (https://skillmd.com/u/michelkerkmeester)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/michelkerkmeester/sk-code-review

---


# sk-code-review Mode - Stack-Agnostic Findings-First Review

Universal findings-first review baseline paired with `sk-code` surface standards evidence for the detected code surface.

## 1. WHEN TO USE

### Activation Triggers

Use the `sk-code-review` mode (of the sk-code family) when:
- A user asks for code review, PR review, or merge readiness.
- A workflow dispatches `@review` for pre-commit or gate validation.
- A user requests security/correctness risk analysis before merge.
- A user wants severity-ranked findings with file:line evidence.

### Keyword Triggers

`review`, `code review`, `pr review`, `audit`, `security review`, `request changes`, `findings`, `blocking issues`, `merge readiness`

### Use Cases

1. Review-only pass: findings-first output with no code edits.
2. Gate validation: a pass or fail that follows severity for orchestrated workflows, with any score advisory only.
3. Focused risk pass: security, concurrency, correctness, or removal-focused review.

### When NOT to Use

- Feature implementation without review intent; load the surface packet (`sk-code-skilled`) that carries the implement doctrine.
- Pure documentation editing where code behavior is not being assessed.
- Git-only workflow tasks (branching, rebasing, commit hygiene) without code quality evaluation intent.
- Applying review fixes after findings are accepted; load the surface packet (`sk-code-skilled`) that carries the implement doctrine.
- Author-side quality gates before review; use `sk-code-quality`.
- Root-cause debugging; use the surface's `workflow-debug.md` doctrine.
- Verification evidence collection; use the surface's `workflow-verify.md` doctrine.

---

## 2. SMART ROUTING

The hub bundles this mode for a code review, a pull-request review, merge readiness or a security and correctness pass over a diff.
Its vocabulary is `review`, `code review`, `pr review`, `audit`, `security review`, `request changes`, `findings`, `blocking issues` and `merge readiness`.
The first resource it loads is `references/review-core.md`, the doctrine both `@review` and `@deep-review` read.

Review keeps no detection of its own.
The quality runner's explain entry is the one resolver, and it applies the shared detection contract, [`stack-detection.md`](../shared/references/stack-detection.md) section 2.
A surface the hub's router bundles from request words is only a candidate: it applies to the files the resolver places in it.

The rule-override algorithm it hands to the review lives in [`review-core.md`](./references/review-core.md) section 9.
Read [`ROUTER.md`](./ROUTER.md) before selecting skill-local resources; open only the matched files.

---

## 3. HOW IT WORKS

### Phase 1: Scope and Baseline

1. Check the two efficiency gates in section 8 before scoping anything: M-1 skips a review whose pull request is unchanged since the last one, and M-2 skips a diff below its opt-in evidence threshold unless it touches a sensitive path. A skip ends the review there, with the status line alone.
2. Inspect the review target (`git diff`, staged diff, file list, or commit range).
3. Load baseline standards from the `sk-code-review` mode (of the sk-code family).
4. Resolve the rule sources for the reviewed files in one call, from the reviewed repository's root, where `<hub>` is the sk-code folder this mode was loaded from (`.skilled/skills/sk-code` in the repository that ships it):

   ```bash
   git diff --name-only --diff-filter=d <range>   # the reviewed paths that still exist
   node <hub>/sk-code-quality/scripts/quality-gate.cjs --explain <file> [<file>...]
   ```

   Pass only paths that exist as regular files. One deleted or missing path makes the runner stop the whole call with `FILE_NOT_FOUND`, exit 3, which would drop every surface and override for the files that do exist.

   - For a diff, `--diff-filter=d` leaves the deleted paths out.
   - For a file list, drop any path that is not a regular file.
   - List a deleted path on the `Not checked:` line when its removal matters to the review, such as a deleted test or a removed caller.

   It prints one `code-quality-explain/v1` JSON document and always exits 2, because it runs nothing. Read each `files[]` entry's `surfaces`, `surface_skills` (the folder each surface loads from), `checklists` (each with its `source`, `sources` and parsed `overrides`) and the document's `config.hygiene.disabled`.

   Exit 3 on that filtered list is a usage or root fault: name it on the `Not checked:` line and review those files against the baseline only. [`runner-contract.md`](../sk-code-quality/references/runner-contract.md) section 3 owns the fields.
5. Load `sk-code` surface standards evidence for the surfaces the resolver returned. A surface the hub's router bundled from request words is a candidate, and it applies only to the files the resolver places in it: the file's `surfaces` holds its label, or one of its checklists applies to the file. A candidate that holds no reviewed file is not loaded and not named in `Surface evidence used`.
6. With no file paths to review, nothing is resolved. The bundle keeps `sk-code-skilled` only when the working directory is inside the hub's own checkout, the same git common dir as the hub folder. Anywhere else it drops `sk-code-skilled`, because a word such as "typescript" says nothing about whose code it is.
7. Read the connected code: the callers of each changed function, the functions each changed function calls, the tests that cover it, and the README or docs that describe it. Anything you could not read goes on the `Not checked:` line.

### Phase 2: Surface Alignment

1. Load standards from `sk-code` for the resolved surfaces only, each for the files the resolver placed in it.
2. Apply precedence matrix:
   - Baseline security/correctness minimums and the rest of the floor always apply.
   - Apply the `## Rule overrides` rows of the checklists the resolver returned. Use the precedence and outcomes of [`review-core.md`](./references/review-core.md) section 8: the repository checklist, then a specific surface, then the SKILLED fallback, then the default lens.
     A checklist whose `overrides.refused` is true contributes no row. A hygiene rule in `config.hygiene.disabled` counts as a `none` row from the repository config.
   - Surface style/process/verification conventions win on conflicts.
3. If precedence cannot be resolved deterministically, escalate before scoring. Two rows at the same level that disagree apply the default, go under `Conflicts` and are named in Next Steps.

### Phase 3: Findings-First Analysis

1. Analyze for security and correctness first.
2. Analyze quality/performance, test adequacy, contract safety, and architecture concerns.
3. Analyze KISS/DRY and SOLID violations (SRP/OCP/LSP/ISP/DIP) with evidence.
4. Analyze removal opportunities with safe-now vs deferred classification.
5. Produce findings ordered by severity (`P0`, `P1`, `P2`), numbered once across all three groups so the first `P1` finding continues after the last `P0` finding. A finding with no case is not reported.
6. For every actionable finding, classify fix scope as `instance-only`, `class-of-bug`, `cross-consumer`, `algorithmic`, `matrix/evidence`, or `test-isolation`. If unknown, default to class/cross-consumer until a producer/consumer inventory proves instance-only.

#### Reach Calibration

A `P0` or `P1` finding names its reach in its `Case:` line, and a finding that cannot name one is `P2`.
The rule, its exceptions for validated input and for data that crosses a trust boundary, and the limit on the low-confidence escalation rule are in [`review-core.md`](./references/review-core.md) section 2.

#### Numeric Severity Calibration

Use numeric calibration only as reviewer context, never as the gate.
A finding may include an optional advisory `riskScore` to communicate relative risk, and reviewers may adjust that score by `+/-2` for local context such as exploitability, blast radius, user impact, confidence, or proven containment.
The blocking decision still comes only from the `P0`/`P1`/`P2` severity contract.
Do not introduce `score>=4` or any other numeric threshold as a blocker.

#### Instance-Only Opt-Out

A finding may use the narrow fix path only when it meets every condition of the instance-only opt-out in [`fix-completeness-checklist.md`](./assets/fix-completeness-checklist.md) section 2.
Otherwise, run the full fix completeness checklist.

### Phase 4: Output and Next Action

Required output contract:

```markdown
## Code Review Summary

**Files reviewed**: X files, Y lines changed
**Overall assessment**: [APPROVED / REQUESTED_CHANGES / COMMENTED]
**Baseline used**: [sk-code (`sk-code-review`)]
**Surface evidence used**: [resolved surface labels in order, such as `<specific surface>, SKILLED` or `SKILLED` | UNKNOWN]
**Quality gate evidence**: [present | absent]
Rule sources: [checklist files]. Overrides: [rule id none|replace from checklist file, or none]. Refused: [checklist files, or none]. Ignored: [rule id from checklist file, or none]. Conflicts: [rule id and both checklist files, or none]

## Findings

### P0 - Critical
1. [path:line] Title
   - Case: [the input or situation that produces the wrong result. A finding with no case is not reported]
   - Risk (for a performance finding, name the workload it assumes, such as row count, request rate or payload size)
   - User impact: what users or callers bear if this fix is deferred
   - Finding class: [instance-only | class-of-bug | cross-consumer | algorithmic | matrix/evidence | test-isolation]
   - Scope proof: [grep/test evidence proving class coverage or instance-only status]
   - affectedSurfaceHints: [optional string array of short producer/consumer surface names; recommended for actionable findings, required for cross-consumer findings]
   - riskScore: [optional advisory number only; never gating]
   - Recommended fix

### P1 - High
2. [path:line] Title
   ...

## Removal/Iteration Plan

## Next Steps

Not checked: [one line naming what mattered but could not be checked, and why, or "nothing material"]
```

The `Rule sources:` line is defined in [`review-core.md`](./references/review-core.md) section 8: the checklists the review read, then each override outcome group, with `none` for an empty group and `Rule sources: none` when no file was resolved.
It never starts with `Review status:`, `Not checked:` or `Overall assessment`, so the final-line checks read the rest of the report as before, and `scripts/check-review-final-line.js` checks the line's own format when it is present.

`Quality gate evidence` reads `present` when a `sk-code-quality` run verdict was handed to the review as input, and `absent` otherwise. Either value leaves every baseline check in place. The verdict is input evidence only, so no check is skipped because the gate already ran it, and no gate count renumbers a finding.

The `Overall assessment` value names the same status as the final `Review status:` line, and so does a `Recommendation` line, such as the one the review agent's PR shape carries.
`scripts/check-review-final-line.js` fails a report whose values disagree, and `scripts/check-review-findings.js` fails a `Recommendation` or a final status that approves or comments over a P0 or P1 finding, or requests changes with none.

After reporting findings, request explicit next action before any implementation follow-up.

### Final-line exact-string contract (MANDATORY)

Every review MUST end with exactly one of the following plain-text lines as the **absolute final line** of the output (no trailing whitespace, no variation):

```
Review status: APPROVED
```

```
Review status: REQUESTED_CHANGES
```

```
Review status: COMMENTED
```

Directly above the status line, separated from it by one blank line, every full review carries one `Not checked:` line naming what mattered but could not be checked and why, or `Not checked: nothing material`.
An optional `AGENT_IO_RESULT` block, when requested, goes above the `Not checked:` line and never below the status line.
The M-1 and M-2 skip outputs (§8) are the status line alone and carry no `Not checked:` line.

**Example output bottom:**

```
...
## Next Steps
1. Fix the null-deref at src/foo.ts:42
2. Add input validation for the `/api/bar` endpoint

Not checked: behavior under concurrent writes to /api/bar; no test database was available

Review status: REQUESTED_CHANGES
```

Downstream automation parses this final line via exact string match.
Do not vary the format, add trailing punctuation, or wrap in Markdown formatting.
The sole exception is the documented M-1 / M-2 skip output (§8): those lines begin with the exact `Review status: COMMENTED` and append a parenthetical reason, so a leading-verdict (grep / `startsWith`) parse still yields `COMMENTED`.
A normal review must still end with one of the three exact lines above.

---

## 4. RULES

### ✅ ALWAYS

- Keep findings first; summaries follow findings.
- Enforce baseline security/correctness minimums regardless of surface.
- Include file:line evidence for actionable findings.
- State assumptions when evidence is incomplete.
- Identify `sk-code` surface evidence used for standards alignment.
- Read each file's surfaces, checklists and overrides from the quality runner's `--explain` resolver, never from a detection of your own.
- State the applied overrides on the one `Rule sources:` line, `none` included.

### ⛔ NEVER

- Override surface-specific conventions with generic baseline style preferences.
- Approve code with unaddressed P0 security/correctness defects.
- Produce vague findings without concrete evidence.
- Mix unrelated cleanup into targeted fix recommendations.
- Let an override row drop or reword a floor rule, or apply a row from a checklist the resolver did not return.
- Implement fixes during review. Report findings only; implementation is a separate follow-up step.

### ⚠️ ESCALATE IF

- Surface detection is ambiguous and affects standards or verification commands.
- Baseline and surface guidance conflict in a non-deterministic way.
- Two override rows at the same precedence level disagree on one rule for one file.
- Large diff size prevents reliable severity assignment without narrowed scope.
- Requested remediation exceeds review scope and becomes architecture redesign.

### Extension Floors

A repository, a surface packet or a mode a user adds to the hub may raise these floors or add checks beside them. None of them may lower, skip or reword one. `scripts/check-rule-copies.js` pins each line below, so a reword fails the canary.

- Baseline security and correctness minimums apply to every review, and surface guidance never relaxes them.
- No review is approved while a P0 finding is unaddressed.
- P0 blocks merge, P1 must be fixed before merge, and P2 is advisory and never blocks.
- A dispatcher adds the `CODE-REVIEW` marker line as the first line of the rendered review prompt.
- Every review ends on exactly one of the three status lines in section 3.
- The mode writes only its PR-state cache file in the reviewing user's cache directory, never into the reviewed repository.

The `Write` entry in this file's `allowed-tools` exists for that cache file alone. The hub's `mode-registry.json` states the same scope in this mode's `writeScopeNote`.

---

## 5. REFERENCES

### Core References

- [review-core.md](./references/review-core.md) - Shared review doctrine: severity model, evidence rules, precedence, finding schema, and the floor, default lens and `Rule sources:` line.
- [rule-overrides.md](../shared/references/universal/rule-overrides.md) - The shared `## Rule overrides` format, rule ids, hard floor and precedence that review and quality both read.
- [review-ux-single-pass.md](./references/review-ux-single-pass.md) - Interactive single-pass review flow, presentation modes, and PR/pre-commit behavior.
- [quick-reference.md](./references/quick-reference.md) - Lightweight index for routing between shared doctrine and single-pass UX guidance.
- [pr-state-dedup.md](./references/pr-state-dedup.md) - Content-hash deduplication for unchanged pull-request reviews.
- [security-checklist.md](./assets/security-checklist.md) - Mandatory security and reliability checks.
- [code-quality-checklist.md](./assets/code-quality-checklist.md) - Correctness, performance, KISS, and DRY checks.
- [solid-checklist.md](./assets/solid-checklist.md) - SOLID (SRP/OCP/LSP/ISP/DIP) and architecture assessment prompts.
- [removal-plan.md](./assets/removal-plan.md) - Safe-now vs deferred removal planning template.
- [test-quality-checklist.md](./assets/test-quality-checklist.md) - Test quality, coverage, and anti-pattern detection.
- [fix-completeness-checklist.md](./assets/fix-completeness-checklist.md) - Finding classes and the producer and consumer inventories a complete fix covers.

### Reference Loading Notes

- Load only the references needed for the selected intents.
- Routing authority: the hub's `SKILL.md` section 2 names `hub-router.json` as the mode vocabulary and `ROUTER.md` as the leaf-set router. This packet's `INTENT_SIGNALS`, `RESOURCE_MAP` and `DEFAULT_RESOURCES` live in its [`ROUTER.md`](./ROUTER.md) section 3.

---

## 6. SUCCESS CRITERIA

- Review output is findings-first and severity-ordered.
- `sk-code-review` mode baseline + `sk-code` surface evidence contract is explicit in report context.
- Security/correctness minimums are always covered.
- Recommended fixes are actionable and scope-proportional.

---

## 7. INTEGRATION POINTS

- Primary review baseline for the runtime's review agent (`@review`), wherever that runtime keeps its agent definitions.
- Dispatched as `@review` by `@orchestrate`, which adds the `CODE-REVIEW` marker. The `/speckit:implement` and `/speckit:complete` workflows name `@review` as the agent for their review step and state the marker for a step that dispatches it. The `/create:*` workflows do not dispatch a review.
- Complements, but does not replace, sibling ownership: the surface packets (`sk-code-skilled`) carry the implement → debug → verify workflow doctrine the acting agent applies to fix accepted findings, and `sk-code-quality` owns author-side gates.

### User-Authored Modes

A repository can add its own mode to the sk-code hub, such as a security surface for its auth code. This is the review side of that mode.

**What a security surface supplies.** It registers as a surface packet (`packetKind: "surface"`, `backendKind: "evidence-base"`) with its own `surfaceDetection` block, router vocabulary and a tie-break slot ahead of the fallback surface.
It supplies read-only evidence: the standards and checklists to load, the markers that place a path inside it, and the verification commands for the code it owns.
It never supplies a severity table, a status value or findings of its own.

**What a consuming workflow may rely on.** When a request scores both this mode and the surface, the hub returns a surface bundle with this mode first and the surface after it.
That bundled surface is a candidate: it applies to the files the quality runner's resolver places in it.
The review then:

- Names the surface's label in `Surface evidence used`.
- Applies the surface's style, process and verification guidance under the precedence matrix in section 2.
- Honors the `## Rule overrides` rows of the checklists its `quality` block declares at the specific-surface level.
- Keeps its own `P0`/`P1`/`P2` findings, report shape and final status line.

A caller parses the report the same way whichever surface was loaded.

**What it may not change.** The Extension Floors in section 4 bind every user mode. A surface may add checks beside a floor and may raise one, and it may never lower, skip or reword one.

The playbook scenario `CR-028` replays a user security surface through both routing stages.

---

## 8. PR-STATE EFFICIENCY GATES

### 8.1 M-1: PR-State Content-Hash Dedup

Prevents redundant re-reviews when a PR has not changed since the last review.

The gate hashes the diff and the latest commit subject into one signature and looks it up in a cache file in the reviewing user's cache directory. The gate never writes into the reviewed repository. Its one side effect is that file, and deleting it resets the gate.

[`references/pr-state-dedup.md`](./references/pr-state-dedup.md) is the specification. It holds the signature formula, the cache path and key, the optional pathspec scope, the line schema, the retention cap and the cache write.

**Skip behavior:**
When the current signature matches a prior cache entry, the review emits:
```
Review status: COMMENTED (no changes since last review at <prev_sha>)
```
No full review analysis runs. Automation may treat `COMMENTED` as a pass (no new findings).

### 8.2 M-2: Opt-In Minimum Evidence Gate

Skips full review for trivially small diffs to save compute, with a conservative taxonomy that **never skips** high-risk changes.

**Enable gate:**
```bash
export SK_CODE_REVIEW_MIN_CHANGED_LINES=50  # >0 enables; default 0 = disabled
```

**Changed-line counting command:**
```bash
git diff --numstat <base-ref>...HEAD | awk '{added+=$1; removed+=$2} END {print added+removed}'
```

**Conservative skip taxonomy. NEVER skip when diff touches:**

| Risk Class | Path/File Patterns | Rationale |
|---|---|---|
| Security / Authentication / Authorization | `auth*`, `*-auth-*`, `*permission*`, `*credential*`, `*token*`, `*secret*`, `*oauth*`, `*sso*`, `*login*`, `*session*` | Compromised auth defeats everything |
| Config files | `*.config.*`, `*config*.json`, `*config*.yaml`, `*config*.toml`, `*.env*`, `*.ini`, `*.cfg` | One-line config change can break production |
| Persistence | `*.sql`, `*migration*`, `*schema*`, `*db*.ts`, `*repository*`, paths under `/db/` or `/migrations/` | Schema changes risk data loss |
| Dependency manifests | `package.json`, `package-lock.json`, `Cargo.toml`, `Cargo.lock`, `pyproject.toml`, `poetry.lock`, `requirements.txt`, `*.lock`, `Gemfile`, `Gemfile.lock` | Transitive dependency changes are high-risk |
| Sandboxing / Subprocess | `*sandbox*`, `*subprocess*`, `*exec*`, `*spawn*`, `*eval*` | Arbitrary code execution boundaries |
| Public-facing responses | `*.handler.ts`, `*-api*`, `*-route*`, `*-controller*`, paths under `/handlers/`, `/routes/`, `/api/` | User-visible behavior changes |

**Skip behavior:**
When `SK_CODE_REVIEW_MIN_CHANGED_LINES > 0`, total changed lines < threshold, AND no sensitive paths are touched:
```
Review status: COMMENTED (skipped: diff below evidence threshold of N lines, no sensitive paths touched)
```
If sensitive paths ARE touched, the full review runs regardless of line count.

**Gate is ALWAYS opt-in.** Without `SK_CODE_REVIEW_MIN_CHANGED_LINES` set, M-2 has zero effect: all diffs receive full reviews.

### 8.3 SK_CODE_REVIEW_DEPTH (opt-in depth alias)

`SK_CODE_REVIEW_DEPTH=lite|full|ultra` is an optional environment variable the **reviewing agent honors** (resolved env > default), exactly like the §8.2 `SK_CODE_REVIEW_MIN_CHANGED_LINES` gate.
Both are skill guidance the reviewer reads and applies in-loop, not a separate compiled dispatcher; this alias only NAMES and PERSISTS an already-existing routing behavior, adds no new tier, and relaxes no floor:

- `full` (default / unset): the normal ALWAYS + CONDITIONAL + ON_DEMAND routing ([`ROUTER.md`](./ROUTER.md) §3).
- `ultra`: bias intent selection toward the existing `ON_DEMAND` reference set (the deep-dive tier in [`ROUTER.md`](./ROUTER.md) §3) for the session, so a reviewer does not have to repeat "comprehensive / full review" each time.
- `lite`: applies the existing M-2 conservative skip (§8.2) only when `SK_CODE_REVIEW_MIN_CHANGED_LINES` is set above 0. With no threshold set, `lite` skips nothing and every diff receives a full review. It NEVER lowers the ALWAYS tier, the baseline security/correctness minimums, or the P0/P1/P2 contract. It cannot skip a review on a sensitive path (auth/config/persistence/deps/sandbox/public-response), exactly as M-2 already enforces.

The depth alias is advisory routing only; it must never be read as permission to relax a floor.

---

## 9. RELATED RESOURCES

Start with `references/quick-reference.md`, then load task-specific doctrine, assets, or scripts.

### Manual Testing Playbook

Manual testing scenarios for the `sk-code-review` mode (of the sk-code family) live in `manual-testing-playbook/manual-testing-playbook.md`, the root index, plus per-feature sub-files under `manual-testing-playbook/<topic>/<scenario>.md`.
Both the category folder and the scenario file use bare descriptive slugs, with no numeric prefix.

Validate the package with the sk-doc playbook package validator, the first check of the playbook's release checklist:
`validate-playbook-package.cjs --package manual-testing-playbook`.
Then validate the root index with the sk-doc document validator in playbook mode:
`validate_document.py --type playbook manual-testing-playbook/manual-testing-playbook.md`.
The playbook path is relative to this packet, and both validator paths are wherever sk-doc is installed.
Playbook mode applies the playbook rule set.

Execute scenarios in Claude Code or OpenCode sessions for behavioral verification.

---

Related skills: `sk-doc` for skill authoring and packaging standards, `sk-code` for surface-aware standards, and `system-spec-kit` for packet-governed review workflows.

