code-review-gate-skill

English | 简体中文

Evidence-backed code review. Static-first, probe-driven, and gated.

The skill sources live in skills/code-review-gate/ (English) and skills/code-review-gate-zh/ (Chinese), independently of any host's installation directory. The current stable release is v0.2.3; see VERSION.

Most AI reviews stop at “this looks risky.” This skill produces a review you can audit: every finding points to a location, a contract or code path, and a severity; every gate decision is rendered from machine-readable JSON. It reads the diff, surrounding source, tests, and project rules — no build, test run, or coverage report required.

It never modifies the code under review.

Latest news

v0.2.3 (2026-11-09)

Added

• code-review: add environment preflight for v0.2.3

Full update history

Release status

v0.2.3 is a stable release within the scope described below. Pre-1.0 contract or format changes will be documented in NEWS.

• Severity is three levels: high, medium, low. Records written by the earlier four-level version, including any critical value, are not compatible; collect-metrics rejects them. Re-run the review or migrate the records before using them with this release.
• Scope: static-first review with four probes and JSON-derived report/gate output. It does not replace tests, CI, or human review.
• Validation: 116 offline pipeline, NEWS, installation, bilingual, locale, and source-freshness tests; clean-project end-to-end gate runs; additional probe smokes. These are regression checks, not a general recall claim. Concurrency-defect detection has not been validated.

For the next stable release, update VERSION (for example, to 0.1.1) and push it to main. After Validate skills succeeds, the release workflow generates NEWS from commits, updates the README release information, and publishes the version tag and GitHub Release. Existing releases are preserved; failed CI does not publish.

Contents

• Latest news
• Release status
• Why this skill
• Quick start
• How it works
• Evidence contract
• Configuration
• What this is not
• Validation
• Requirements
• Repository layout
• Contributing
• License

Why this skill

No self-grading.

The implementation context does not sign off on its own work. Four probes run in fresh contexts, each files its own evidence, and the gate is derived from those records.

This is separation of duties, not independent human adjudication; all probes still use the same model.

Quick start

Install

Run this command inside your project:

# English (default)
npx -y skills add kyy-logs/code-review-gate-skill --agent codex --skill code-review-gate --yes

# Chinese
npx -y skills add kyy-logs/code-review-gate-skill --agent codex --skill code-review-gate-zh --yes

Use --agent claude-code for Claude Code. Codex installs to .agents/skills/<skill>/; Claude Code installs to .claude/skills/<skill>/. Node.js 22.20+ is required. Install one language per project. The Python installers also accept --lang en|zh-CN and default to English.

Run

Ask in Claude Code:

Review these changes with code-review-gate.

Or invoke the skill directly:

/code-review-gate

For a fixed range:

Use code-review-gate on commits abc123..def456

The skill supports two review modes:

• worktree — staged, unstaged, and untracked changes against the current HEAD.
• commits — a fixed base..head range.

Read the result

docs/work/active/{slug}/
├── code-review.md      # human report
├── review-snapshot.json
└── probes/
    ├── behavior-review.json
    ├── test-coverage.json
    ├── repo-guard.json
    └── impact-analysis.json

How it works

The four probes use the same model in fresh contexts. This is separation of duties, not independent human review. A passing gate is not human approval, CI, or proof that no issues remain. The current skill has no separate reviewer or finding-verification stage; raw findings feed the report and gate.

1. Scope — determine worktree or commits; record base and head as commit IDs, then init the run with --mode to pin review-snapshot.json.
2. Probes — dispatch four independent agents with the same scope and diff, each writing its own probe JSON. Run in batches if host capacity is limited, or record a serial fallback if agents are unavailable. Cross-probe duplicates are retained and counted; actual speed and token savings remain unverified.
3. Sync — validate probe JSON and derive counts with collect-metrics.
4. Reconcile — high findings must be closed or marked false-positive by the probe.
5. Report — render the human report’s fact sections from JSON, then verify them.
6. Gate — source freshness, required-probe failures, and open high findings block the merge.

The four probes

Probes are intentionally narrow. behavior-review is not a linter, and repo-guard is not a general bug scanner.

Language and stack coverage

The default repo-guard workflow selects .java, .ts, .tsx, and .vue files for pattern scanning. The built-in rule pack includes Java- and Spring-specific guidance; selecting an extension does not establish complete framework or language coverage.

AI semantic checks can inspect relevant code beyond those extensions, but their results depend on the model and available contracts, source, and tests. The historical cases below exercise particular stacks and skill snapshots; they do not establish equally validated support across all stacks. Use applicable project rules and record unverified dependencies or language-specific behavior.

Evidence contract

Every finding records:

High-severity findings must cite the actual method signature and the contract they violate, or a concrete code path. A hunch is capped at medium until the evidence is checked.

Configuration

references/probes.yaml controls the probe registry:

Project-specific rules can live in .code-review/rules/, or be pointed to with CODE_REVIEW_RULES_DIR:

export CODE_REVIEW_RULES_DIR=/path/to/rules

A project rule package replaces the built-in package; it is not merged with it.

What this is not

• Not a replacement for tests, CI, or human review.
• Not a guarantee that a clean report means the change is correct.
• Not a coverage tool: coverage is used when provided, not required.
• Not a fixer: it does not modify the code under review.

Validation

Offline tests check JSON validation, derived counts, report consistency, installation, and gate behavior. Passing them does not establish defect-detection recall, false-positive rates, or the correctness of an AI finding.

A controlled comparison against a single-agent review, measuring missed defects, false positives, wall-clock time, and token usage on the same cases and model configuration, has not yet been established. The historical runs below are snapshot-specific observations and do not demonstrate an improvement over that baseline.

• Baseline: commit 494a39bb, before behavior-review was extracted into a standalone probe. The snapshot validates the shared finding and gate co