review

review2506 wordsMITv1.0.0Repo-owned

review

Use for session, scoped, PR, range, full audit, simplification, and source/provenance reviews with evidence-first findings. NOT for feature implementation or benchmarking.

Quick Start

Install:

npx skills add github:wyattowalsh/agents --skill review -y -g --agent antigravity --agent claude-code --agent codex --agent crush --agent cursor --agent gemini-cli --agent github-copilot --agent grok --agent opencode

Use: /review [--mode <mode[,mode]> | path | audit | PR# | simplify <target> | source <source-or-path>]

Works with Claude Code, Gemini CLI, OpenCode, and other agentskills.io-compatible agents.

Repo skill (hand-maintained)

Composed compose-custom-wave-1 from skills/review/SKILL.md with full SKILL disclosure. Do not run wagents docs generate on this file (HAND-MAINTAINED sentinel).

What It Does

Use /review as the canonical first-party review entrypoint. It covers code review, session diffs, scoped files, PRs, full audits, behavior-preserving simplification review, source/provenance review for external skills, specialist audit lenses, browser-grounded frontend/a11y/web-quality review, review history, delta reports, false-positive learnings, SARIF output, Conventional Comments output, and approval-gated fix passes.

Modes

$ARGUMENTS	Mode	Action
--mode session|scoped|pr|range|audit|simplify|source|history|delta|learnings|fix	explicit mode	Run only the selected mode against the provided or inferred target
repeated --mode or comma-separated --mode scoped,source	multi-mode	Run read-only modes as separate lanes and merge through Judge
empty + changed files in git diff --name-only HEAD	session	Review changed files only
empty + no changed files	menu	Show review modes; never start a full audit implicitly
file or directory path	scoped	Review that path
audit	full audit	Review the repository through triage, specialist lanes, and judge reconciliation
PR number or PR URL	PR	Review PR diff and stated intent
git range such as HEAD~3..HEAD	range	Review changes in that range
simplify analyze <target>	simplify analyze	Read-only simplification opportunity review
simplify apply <target>	simplify apply	Behavior-preserving edit only after the simplification gate passes
simplify explain <target>	simplify explain	Explain complexity and safer simpler shapes without editing
source triage <source>	source triage	Classify external source reputation, install syntax, and dedupe risk
source inspect <path>	source inspect	Review local source files, hooks, scripts, frontmatter, and commands
source commands <path>	source commands	Extract and classify executable surfaces
source provenance <source>	source provenance	Check owner, URL, license, commit/hash, registry/source-list consistency, and access date
source decision <source-or-path>	source decision	Recommend install-now, inspect, keep-global, build-local, or avoid
source scan <path>	source scan	Run static source audit helper and interpret JSON output
--lens security|supply-chain|ci|sql|data|frontend|a11y|web-quality|mcp|agentic|docs|skill-assets	specialist	Overlay an explicit specialist lens on the selected scope
path under skills/<name>/, SKILL.md, evals/*.json, or skill catalog/research docs	scoped + skill-assets	Review as a skill asset using skill-creator structural patterns, portability, eval, package, and generated-surface gates
--format sarif	output modifier	Emit SARIF v2.1 findings in addition to or instead of text
--format conventional	output modifier	Emit Conventional Comments-compatible PR review output
history [project]	history	Read stored review history
diff [project] or delta [project]	delta	Compare current and previous stored reviews
learnings add|list|check|clear	learnings	Manage false-positive review learnings
fix <finding-ids> or apply approved findings	fix pass	Apply only explicitly approved findings through references/auto-fix-protocol.md
unrecognized or ambiguous	clarify	Ask one concise scope/mode question

Critical Rules

1. Never start a full audit from empty args unless the user says audit.
2. Never edit files during read-only review, source/provenance review, history, delta, or simplify analyze/explain.
3. Never apply fixes without explicit approval of selected findings.
4. Never vendor third-party skill files into skills/ during source/provenance review.
5. Always verify citation anchors before reporting findings.
6. Always state degraded-mode limits when validation tools are unavailable.
7. Always separate evidence from inference.
8. Always preserve unrelated dirty work.
9. Do not present honest-review, simplify, or external-skill-auditor as installable or invocable skills. Rewrite active references to /review, /review simplify, or /review source; leave only clearly historical or research evidence mentions.
10. For skill assets, apply skill-creator paradigms before reporting a no-finding result: run or cite audit/package/eval evidence when available, inspect references and eval coverage, and classify generated docs/catalog drift separately from source defects.

Canonical Vocabulary

Use these canonical terms exactly.

Term	Meaning
review	Evidence-first inspection of code, diffs, PRs, repositories, sources, or proposed simplifications
scope	The exact files, directories, PR, git range, source, or snippet under review
triage	First pass that classifies scope, risk, changed files, specialist lenses, and validation requirements
finding	A discrete issue with citation, reasoning, severity, confidence, evidence, and recommended action
strength	A positive review observation that explains what should be preserved
confidence	Score from 0.0 to 1.0; report >= 0.7, mark 0.3-0.7 unconfirmed, discard < 0.3 unless P0/S0
severity	Priority/scope classification such as P0-P3 and S0-S3
citation anchor	A verified [file:start-end] source location or source/provenance anchor
reasoning chain	Why the finding matters, written before the finding statement
evidence	Tool, source, test, docs, grep, dependency, or research proof that supports or rejects a finding
lens	Specialist perspective such as security, supply chain, CI, SQL, data, frontend, a11y, web quality, MCP, agentic, or docs
skill asset	A SKILL.md, skill directory, skill eval, skill script, reference, package, catalog row, or generated skill doc reviewed through skill-creator structural patterns
simplification lens	Behavior-preserving review of complexity, invariants, semantic-change risk, and clarity opportunities
source/provenance lens	Review of external skill/source trust, executable surfaces, owner, license, credentials, network behavior, and dedupe
approval gate	Mandatory pause before editing files or applying fixes
learning	Stored false-positive dismissal used to reduce repeated noise in future reviews
mode	Explicit or inferred review workflow such as session, scoped, PR, range, audit, simplify, source, history, delta, learnings, or fix
shard map	Wave 0 ownership plan for large parallel reviews, with lane IDs, shard IDs, file/source ownership, coverage expectations, and merge status

Auto-Detection

1. Step — Parse explicit --mode flags first. Split comma-separated values and preserve repeated flags.

2. Step — If explicit modes are present, run only those modes. Infer the target when safe, but never infer edit approval.

3. Step — If no explicit mode is present, infer from args: empty changed diff -> session, empty clean tree -> menu, path -> scoped, PR number/URL -> PR, git range -> range, audit -> full audit, simplify -> simplification, source or external skill/source language -> source/provenance.

4. Step — When the selected scope is a skill asset, automatically attach the skill-assets lens unless the user explicitly asks for a different lens only.

5. Step — Multiple read-only modes run as separate lanes and reconcile through Judge.

6. Step — fix and simplify apply are edit-capable. Never run them from inference alone and never mix them into a read-only bundle without explicit approved finding IDs.

7. Step — --lens modifies the selected mode; it does not invent scope.

8. Step — --format modifies output only; it does not choose scope.

9. Step — Feature work, benchmarking, broad refactors, installs, or implementation requests without approved findings are out of scope.

Scope Boundaries

In scope: review findings, source/provenance decisions, simplification analysis, simplification explanations, narrowly gated simplification apply passes, stored review history, review deltas, false-positive learnings, and approved post-review fixes.

Out of scope: new features, product implementation, benchmark design, broad refactors, live external installs, destructive cleanup, exploit execution, unaudited source promotion, and unapproved fixes.

Classification Logic

1. Step — Decide whether the request is review, simplification, source/provenance, state/history, output formatting, or implementation.

2. Step — Reject implementation unless it is an approved finding fix or a simplify apply target that passes the eligibility gate.

3. Step — Reject source installs unless the user separately requests a live install after the source/provenance decision.

4. Step — For skill assets, require skill-creator structural evidence before accepting or rejecting a skill change: dispatch table, empty-args handler, reference index, critical rules, canonical vocabulary when needed, scope boundaries, progressive disclosure, script/eval/package proof, portability, and generated docs/catalog consistency.

5. Step — When two modes could apply, prefer the read-only mode first and ask one concise question only if the target or approval state is unclear.

Scaling Strategy

Size	Strategy
Small	One file, snippet, or narrow source: run a single reviewer pass with the full finding contract
Medium	2-5 related files: split by file ownership when safe and reconcile through judge protocol
Large	PR, git range, or mixed module diff: triage first, then assign non-overlapping review lanes by risk
Full audit	Create a Wave 0 shard map, assign risk-tiered non-overlapping lanes, run specialist lenses, and reconcile through Judge
Source/provenance bundle	Split metadata, executable surfaces, credentials/network, license/provenance, and dedupe checks

Progressive Disclosure

Start with this file only. Load reference files after dispatch and only for the chosen mode or lens. Do not preload all references for small reviews.

Review Pipeline

1. Step — Triage: identify scope, changed files, public contracts, project instructions, dependency graph, risk tier, and specialist lenses.

2. Step — Shard: for large or multi-mode work, produce a Wave 0 shard map before spawning reviewers.

3. Step — Analyze: inspect code/source using content-adaptive reviewers. Keep ownership non-overlapping when parallelizing.

4. Step — Verify: check every non-trivial finding against source lines, tests, grep evidence, docs, or external research.

5. Step — Judge: normalize, assign canonical RV-* IDs, dedupe, resolve conflicts, apply confidence thresholds, rank by severity/confidence/blast radius, and preserve strengths.

6. Step — Report: present findings first, ordered by severity, with concise evidence and an approval gate.

7. Step — Fix pass: only after explicit approval of selected finding IDs, load references/auto-fix-protocol.md, preview diffs, apply narrowly, and verify.

Finding Contract

Every finding uses this order:

1. Citation: verified [file:start-end], PR hunk, source URL, command output anchor, or provenance anchor.
2. Reasoning: why this matters and what breaks if it is left alone.
3. Finding: one concise statement of the issue.
4. Severity and confidence: P0-P3/S0-S3 plus 0.0-1.0 confidence.
5. Evidence: source/tool/research/test proof; include degraded-mode limits when tools are unavailable.
6. Recommendation: smallest safe next step.

Use references/finding-contract.md for full schema and scoring.

Lens Contracts

Load references only when the selected mode needs them.

Need	Read
finding schema and scoring	references/finding-contract.md
triage/scaling	references/triage-protocol.md
review checklists	references/checklists.md
reviewer team prompts	references/team-templates.md
creative review lenses	references/review-lenses.md
research validation	references/research-validation.md
judge reconciliation	references/judge-protocol.md
self-verification	references/self-verification.md
output variants	references/output-formats.md
SARIF output	references/sarif-output.md
Conventional Comments output	references/conventional-comments.md
CI annotations and automation	references/ci-integration.md
dependency graph and blast radius	references/dependency-context.md
supply-chain security	references/supply-chain-security.md
specialist lens map	references/specialist-lenses.md
skill asset and skill-creator paradigms	references/skill-asset-review.md
simplification lens	references/simplification-lens.md
simplification taxonomy	references/simplification-taxonomy.md
source/provenance lens	references/source-provenance-lens.md
approval-gated fixes	references/auto-fix-protocol.md
review state, history, delta, learnings	references/review-state.md

Simplification Lens

/review simplify is behavior-preserving. It may identify or apply clarity improvements only when the target, unchanged invariants, validation basis, and scope boundaries are explicit.

• analyze: read-only report.
• explain: teaching/explanation only.
• apply: edit only a concrete file/symbol/snippet or tightly bounded diff after the eligibility gate passes.

Reject semantic changes, bug fixes, API changes, validation changes, security-policy changes, performance-only work, or broad refactors under simplification mode.

Source/Provenance Lens

/review source is the trust gate for external skills and sources. Use source-list and read-only inspection before any install or promotion decision. Inspect hooks, scripts, command substitutions, allowed tools, package scripts, network calls, credential behavior, filesystem writes, provenance, license, owner, commit/hash, and dedupe against repo-owned skills.

Never run candidate scripts during audit except static/syntax checks in a staged local path. Do not install or sync external skills unless the user explicitly requests that live action.

Browser-Grounded Review

For frontend, a11y, web-quality, docs UI, and other browser-dependent review, prefer Chrome DevTools MCP through the repo-managed chrome-devtools MCPHub attached-browser configuration. Use browser snapshots, console/network evidence, and screenshots from Chrome DevTools MCP when available. If Chrome DevTools MCP is unavailable, state degraded mode before falling back to existing smoke tests or Playwright-oriented project checks.

Skill-Asset Review

When the scope is a skill asset, load references/skill-asset-review.md and apply skill-creator paradigms as review evidence. Use deterministic skill-creator scripts when available, but do not treat a high audit score as the whole review. Check whether the skill’s structure, dispatch behavior, evals, references, scripts, package portability, public docs, and generated catalog surfaces match the intended behavior.

Skill-asset review is read-only unless the user invokes a valid fix pass or a separately approved implementation request. Do not run live installs, live behavioral evals, or sync apply while reviewing skill assets.

Harness Portability

This SKILL.md is portable and prompt-first. It deliberately omits a root model override and skill-scoped hooks.

Harness	Behavior
Claude Code	Uses portable skill metadata and argument hints. Skill hooks require separate validate_hooks.py and package proof before being added.
Codex	Skill discovery and any hook behavior are projected through repo/plugin config such as config/hook-registry.json, not assumed from this file.
OpenCode	Skill discovery comes from repo opencode.json and skill paths; models/plugins/overlays stay in OpenCode config.
Grok Build CLI	Uses Claude-compatible skill mirroring and .grok/skills discovery where available.
Generic Skills CLI targets	Core prompt must install cleanly through npx skills add and repo sync dry-runs.

State Management

Review history, deltas, and false-positive learnings persist in the active harness home directory, not in the repository.

• Base path: ~/.{gemini|copilot|codex|claude}/reviews/ (harness-dependent; Claude Code defaults to .claude).
• State file naming: {YYYY-MM-DD}-{project-slug}-{mode}[-{run_id}].json under the reviews directory.
• Learnings: {reviews}/learnings/{project-slug}.json for false-positive dismissals.
• Slug rule: lowercase project names with non-alphanumeric runs replaced by hyphens; empty slugs become unnamed.
• Collision: same-day reruns use distinct run_id suffixes; saves do not silently overwrite prior review state files.
• Operations: use scripts/review-store.py for save/load/list/diff and scripts/learnings-store.py for add/check/list/clear.
• Read-only modes: history, delta, and learnings list never edit reviewed source files.
• Cleanup: user-owned; no automatic pruning. Do not commit review JSON into the repo.
• Details: load references/review-state.md for envelope fields, diff semantics, and harness path table.

Script Index

Script	Purpose
scripts/check.py	Run review skill validation, eval validation, package dry-run, and audit
scripts/project-scanner.py	Triage project/file risk and review triggers
scripts/finding-formatter.py	Normalize findings and output variants
scripts/review-store.py	Store/load/list/diff review state
scripts/learnings-store.py	Manage false-positive learnings
scripts/sarif-uploader.py	Help emit/upload SARIF where supported
scripts/source-audit.py	Static audit of local external skill/source directories

Validation Contract

Before considering changes complete, run the focused checks relevant to this skill:

uv run python scripts/check.py

Completion criteria:

1. scripts/check.py exits 0.
2. Bundled validate_skill and validate_evals pass when evals are present.
3. Bundled package.py --dry-run reports portable.
4. Repo-only audit.py grade remains at or above the prior baseline when run from the monorepo (optional for portable installs; degraded mode is acceptable elsewhere).
5. Regenerate docs/catalog surfaces when SKILL.md, references, or evals change.
6. Any remaining legacy-name references are classified as wrappers, migration notes, generated evidence, or historical research.

Public Metadata

Field	Value
Source Type	repo-owned
Display Source	github:wyattowalsh/agents
Source Kind	repo
Installability	portable command
Review State	reviewed
Target Agents	antigravity, claude-code, codex, crush, cursor, gemini-cli, github-copilot, grok, opencode

General

Field	Value
Name	review
License	MIT
Version	1.0.0
Author	wyattowalsh

Claude Code

Field	Value
Argument Hint	`[—mode [mode[,mode]]

Related Skills

designDesign, build, refactor, and audit user-facing interfaces.

orchestratorReview and orchestrate parallel execution via subagent waves, teams, and pipelines. Use when 2+ independent actions need coordination.

security-scannerProactive security assessment with SAST, secrets detection, dependency scanning, and compliance checks. Use for pre-deployment audit.

tech-debt-analyzerSystematic tech debt inventory with complexity analysis, dead code detection, and remediation planning. Track debt over time.

Full SKILL.md

skills/review/SKILL.md

---
name: review
description: Use for session, scoped, PR, range, full audit, simplification, and source/provenance reviews with evidence-first findings. NOT for feature implementation or benchmarking.
argument-hint: "[--mode <mode[,mode]> | path | audit | PR# | simplify <target> | source <source-or-path>]"
license: MIT
user-invocable: true
metadata:
  author: wyattowalsh
  version: "1.0.0"
---

# Review

Use `/review` as the canonical first-party review entrypoint. It covers code review, session diffs, scoped files, PRs, full audits, behavior-preserving simplification review, source/provenance review for external skills, specialist audit lenses, browser-grounded frontend/a11y/web-quality review, review history, delta reports, false-positive learnings, SARIF output, Conventional Comments output, and approval-gated fix passes.

`honest-review`, `simplify`, and `external-skill-auditor` are not separate skills. Their behavior lives here as `/review`, `/review simplify`, and `/review source`.

Default posture: read-only, evidence-first, and scoped. Do not perform feature work, broad rewrites, installs, or fixes until the user explicitly approves selected findings or invokes a mode that permits edits and passes its gates.

## Canonical Vocabulary

Use these canonical terms exactly.

| Term | Meaning |
| --- | --- |
| **review** | Evidence-first inspection of code, diffs, PRs, repositories, sources, or proposed simplifications |
| **scope** | The exact files, directories, PR, git range, source, or snippet under review |
| **triage** | First pass that classifies scope, risk, changed files, specialist lenses, and validation requirements |
| **finding** | A discrete issue with citation, reasoning, severity, confidence, evidence, and recommended action |
| **strength** | A positive review observation that explains what should be preserved |
| **confidence** | Score from 0.0 to 1.0; report >= 0.7, mark 0.3-0.7 unconfirmed, discard < 0.3 unless P0/S0 |
| **severity** | Priority/scope classification such as P0-P3 and S0-S3 |
| **citation anchor** | A verified `[file:start-end]` source location or source/provenance anchor |
| **reasoning chain** | Why the finding matters, written before the finding statement |
| **evidence** | Tool, source, test, docs, grep, dependency, or research proof that supports or rejects a finding |
| **lens** | Specialist perspective such as security, supply chain, CI, SQL, data, frontend, a11y, web quality, MCP, agentic, or docs |
| **skill asset** | A `SKILL.md`, skill directory, skill eval, skill script, reference, package, catalog row, or generated skill doc reviewed through skill-creator structural patterns |
| **simplification lens** | Behavior-preserving review of complexity, invariants, semantic-change risk, and clarity opportunities |
| **source/provenance lens** | Review of external skill/source trust, executable surfaces, owner, license, credentials, network behavior, and dedupe |
| **approval gate** | Mandatory pause before editing files or applying fixes |
| **learning** | Stored false-positive dismissal used to reduce repeated noise in future reviews |
| **mode** | Explicit or inferred review workflow such as session, scoped, PR, range, audit, simplify, source, history, delta, learnings, or fix |
| **shard map** | Wave 0 ownership plan for large parallel reviews, with lane IDs, shard IDs, file/source ownership, coverage expectations, and merge status |

## Dispatch

Classify `$ARGUMENTS` before reading widely.

| `$ARGUMENTS` | Mode | Action |
| --- | --- | --- |
| `--mode session|scoped|pr|range|audit|simplify|source|history|delta|learnings|fix` | explicit mode | Run only the selected mode against the provided or inferred target |
| repeated `--mode` or comma-separated `--mode scoped,source` | multi-mode | Run read-only modes as separate lanes and merge through Judge |
| empty + changed files in `git diff --name-only HEAD` | session | Review changed files only |
| empty + no changed files | menu | Show review modes; never start a full audit implicitly |
| file or directory path | scoped | Review that path |
| `audit` | full audit | Review the repository through triage, specialist lanes, and judge reconciliation |
| PR number or PR URL | PR | Review PR diff and stated intent |
| git range such as `HEAD~3..HEAD` | range | Review changes in that range |
| `simplify analyze <target>` | simplify analyze | Read-only simplification opportunity review |
| `simplify apply <target>` | simplify apply | Behavior-preserving edit only after the simplification gate passes |
| `simplify explain <target>` | simplify explain | Explain complexity and safer simpler shapes without editing |
| `source triage <source>` | source triage | Classify external source reputation, install syntax, and dedupe risk |
| `source inspect <path>` | source inspect | Review local source files, hooks, scripts, frontmatter, and commands |
| `source commands <path>` | source commands | Extract and classify executable surfaces |
| `source provenance <source>` | source provenance | Check owner, URL, license, commit/hash, registry/source-list consistency, and access date |
| `source decision <source-or-path>` | source decision | Recommend install-now, inspect, keep-global, build-local, or avoid |
| `source scan <path>` | source scan | Run static source audit helper and interpret JSON output |
| `--lens security|supply-chain|ci|sql|data|frontend|a11y|web-quality|mcp|agentic|docs|skill-assets` | specialist | Overlay an explicit specialist lens on the selected scope |
| path under `skills/<name>/`, `SKILL.md`, `evals/*.json`, or skill catalog/research docs | scoped + skill-assets | Review as a skill asset using skill-creator structural patterns, portability, eval, package, and generated-surface gates |
| `--format sarif` | output modifier | Emit SARIF v2.1 findings in addition to or instead of text |
| `--format conventional` | output modifier | Emit Conventional Comments-compatible PR review output |
| `history [project]` | history | Read stored review history |
| `diff [project]` or `delta [project]` | delta | Compare current and previous stored reviews |
| `learnings add|list|check|clear` | learnings | Manage false-positive review learnings |
| `fix <finding-ids>` or `apply approved findings` | fix pass | Apply only explicitly approved findings through `references/auto-fix-protocol.md` |
| unrecognized or ambiguous | clarify | Ask one concise scope/mode question |

## Auto-Detection

1. Parse explicit `--mode` flags first. Split comma-separated values and preserve repeated flags.
2. If explicit modes are present, run only those modes. Infer the target when safe, but never infer edit approval.
3. If no explicit mode is present, infer from args: empty changed diff -> session, empty clean tree -> menu, path -> scoped, PR number/URL -> PR, git range -> range, `audit` -> full audit, `simplify` -> simplification, `source` or external skill/source language -> source/provenance.
4. When the selected scope is a skill asset, automatically attach the `skill-assets` lens unless the user explicitly asks for a different lens only.
5. Multiple read-only modes run as separate lanes and reconcile through Judge.
6. `fix` and `simplify apply` are edit-capable. Never run them from inference alone and never mix them into a read-only bundle without explicit approved finding IDs.
7. `--lens` modifies the selected mode; it does not invent scope.
8. `--format` modifies output only; it does not choose scope.
9. Feature work, benchmarking, broad refactors, installs, or implementation requests without approved findings are out of scope.

## Scope Boundaries

In scope: review findings, source/provenance decisions, simplification analysis, simplification explanations, narrowly gated simplification apply passes, stored review history, review deltas, false-positive learnings, and approved post-review fixes.

Out of scope: new features, product implementation, benchmark design, broad refactors, live external installs, destructive cleanup, exploit execution, unaudited source promotion, and unapproved fixes.

## Classification Logic

1. Decide whether the request is review, simplification, source/provenance, state/history, output formatting, or implementation.
2. Reject implementation unless it is an approved finding fix or a `simplify apply` target that passes the eligibility gate.
3. Reject source installs unless the user separately requests a live install after the source/provenance decision.
4. For skill assets, require skill-creator structural evidence before accepting or rejecting a skill change: dispatch table, empty-args handler, reference index, critical rules, canonical vocabulary when needed, scope boundaries, progressive disclosure, script/eval/package proof, portability, and generated docs/catalog consistency.
5. When two modes could apply, prefer the read-only mode first and ask one concise question only if the target or approval state is unclear.

## Scaling Strategy

| Size | Strategy |
| --- | --- |
| Small | One file, snippet, or narrow source: run a single reviewer pass with the full finding contract |
| Medium | 2-5 related files: split by file ownership when safe and reconcile through judge protocol |
| Large | PR, git range, or mixed module diff: triage first, then assign non-overlapping review lanes by risk |
| Full audit | Create a Wave 0 shard map, assign risk-tiered non-overlapping lanes, run specialist lenses, and reconcile through Judge |
| Source/provenance bundle | Split metadata, executable surfaces, credentials/network, license/provenance, and dedupe checks |

## Progressive Disclosure

Start with this file only. Load reference files after dispatch and only for the chosen mode or lens. Do not preload all references for small reviews.

## Review Pipeline

1. **Triage**: identify scope, changed files, public contracts, project instructions, dependency graph, risk tier, and specialist lenses.
2. **Shard**: for large or multi-mode work, produce a Wave 0 shard map before spawning reviewers.
3. **Analyze**: inspect code/source using content-adaptive reviewers. Keep ownership non-overlapping when parallelizing.
4. **Verify**: check every non-trivial finding against source lines, tests, grep evidence, docs, or external research.
5. **Judge**: normalize, assign canonical `RV-*` IDs, dedupe, resolve conflicts, apply confidence thresholds, rank by severity/confidence/blast radius, and preserve strengths.
6. **Report**: present findings first, ordered by severity, with concise evidence and an approval gate.
7. **Fix pass**: only after explicit approval of selected finding IDs, load `references/auto-fix-protocol.md`, preview diffs, apply narrowly, and verify.

### Large Review Shards

For large or multi-mode reviews, every subagent must receive a lane ID, shard ID, exact scope, coverage expectations, non-goals, and artifact contract before dispatch.

### Judge Handoff

Worker findings use local IDs only. The Judge assigns canonical `RV-*` IDs after all lane artifacts are normalized, deduped, confidence-filtered, and ranked.

## Finding Contract

Every finding uses this order:

1. **Citation**: verified `[file:start-end]`, PR hunk, source URL, command output anchor, or provenance anchor.
2. **Reasoning**: why this matters and what breaks if it is left alone.
3. **Finding**: one concise statement of the issue.
4. **Severity and confidence**: P0-P3/S0-S3 plus 0.0-1.0 confidence.
5. **Evidence**: source/tool/research/test proof; include degraded-mode limits when tools are unavailable.
6. **Recommendation**: smallest safe next step.

Use `references/finding-contract.md` for full schema and scoring.

## Lens Contracts

Load references only when the selected mode needs them.

| Need | Read |
| --- | --- |
| finding schema and scoring | `references/finding-contract.md` |
| triage/scaling | `references/triage-protocol.md` |
| review checklists | `references/checklists.md` |
| reviewer team prompts | `references/team-templates.md` |
| creative review lenses | `references/review-lenses.md` |
| research validation | `references/research-validation.md` |
| judge reconciliation | `references/judge-protocol.md` |
| self-verification | `references/self-verification.md` |
| output variants | `references/output-formats.md` |
| SARIF output | `references/sarif-output.md` |
| Conventional Comments output | `references/conventional-comments.md` |
| CI annotations and automation | `references/ci-integration.md` |
| dependency graph and blast radius | `references/dependency-context.md` |
| supply-chain security | `references/supply-chain-security.md` |
| specialist lens map | `references/specialist-lenses.md` |
| skill asset and skill-creator paradigms | `references/skill-asset-review.md` |
| simplification lens | `references/simplification-lens.md` |
| simplification taxonomy | `references/simplification-taxonomy.md` |
| source/provenance lens | `references/source-provenance-lens.md` |
| approval-gated fixes | `references/auto-fix-protocol.md` |
| review state, history, delta, learnings | `references/review-state.md` |

## Simplification Lens

`/review simplify` is behavior-preserving. It may identify or apply clarity improvements only when the target, unchanged invariants, validation basis, and scope boundaries are explicit.

- `analyze`: read-only report.
- `explain`: teaching/explanation only.
- `apply`: edit only a concrete file/symbol/snippet or tightly bounded diff after the eligibility gate passes.

Reject semantic changes, bug fixes, API changes, validation changes, security-policy changes, performance-only work, or broad refactors under simplification mode.

## Source/Provenance Lens

`/review source` is the trust gate for external skills and sources. Use source-list and read-only inspection before any install or promotion decision. Inspect hooks, scripts, command substitutions, allowed tools, package scripts, network calls, credential behavior, filesystem writes, provenance, license, owner, commit/hash, and dedupe against repo-owned skills.

Never run candidate scripts during audit except static/syntax checks in a staged local path. Do not install or sync external skills unless the user explicitly requests that live action.

## Browser-Grounded Review

For frontend, a11y, web-quality, docs UI, and other browser-dependent review, prefer Chrome DevTools MCP through the repo-managed `chrome-devtools` MCPHub attached-browser configuration. Use browser snapshots, console/network evidence, and screenshots from Chrome DevTools MCP when available. If Chrome DevTools MCP is unavailable, state degraded mode before falling back to existing smoke tests or Playwright-oriented project checks.

## Skill-Asset Review

When the scope is a skill asset, load `references/skill-asset-review.md` and apply skill-creator paradigms as review evidence. Use deterministic `skill-creator` scripts when available, but do not treat a high audit score as the whole review. Check whether the skill's structure, dispatch behavior, evals, references, scripts, package portability, public docs, and generated catalog surfaces match the intended behavior.

Skill-asset review is read-only unless the user invokes a valid fix pass or a separately approved implementation request. Do not run live installs, live behavioral evals, or sync apply while reviewing skill assets.

## Harness Portability

This `SKILL.md` is portable and prompt-first. It deliberately omits a root model override and skill-scoped hooks.

| Harness | Behavior |
| --- | --- |
| Claude Code | Uses portable skill metadata and argument hints. Skill hooks require separate `validate_hooks.py` and package proof before being added. |
| Codex | Skill discovery and any hook behavior are projected through repo/plugin config such as `config/hook-registry.json`, not assumed from this file. |
| OpenCode | Skill discovery comes from repo `opencode.json` and skill paths; models/plugins/overlays stay in OpenCode config. |
| Grok Build CLI | Uses Claude-compatible skill mirroring and `.grok/skills` discovery where available. |
| Generic Skills CLI targets | Core prompt must install cleanly through `npx skills add` and repo sync dry-runs. |

## State Management

Review history, deltas, and false-positive learnings **persist** in the active harness home directory, not in the repository.

- **Base path:** `~/.{gemini|copilot|codex|claude}/reviews/` (harness-dependent; Claude Code defaults to `.claude`).
- **State file naming:** `{YYYY-MM-DD}-{project-slug}-{mode}[-{run_id}].json` under the reviews directory.
- **Learnings:** `{reviews}/learnings/{project-slug}.json` for false-positive dismissals.
- **Slug rule:** lowercase project names with non-alphanumeric runs replaced by hyphens; empty slugs become `unnamed`.
- **Collision:** same-day reruns use distinct `run_id` suffixes; saves do not silently overwrite prior review state files.
- **Operations:** use `scripts/review-store.py` for save/load/list/diff and `scripts/learnings-store.py` for add/check/list/clear.
- **Read-only modes:** `history`, `delta`, and `learnings list` never edit reviewed source files.
- **Cleanup:** user-owned; no automatic pruning. Do not commit review JSON into the repo.
- **Details:** load `references/review-state.md` for envelope fields, diff semantics, and harness path table.

## Script Index

| Script | Purpose |
| --- | --- |
| `scripts/check.py` | Run review skill validation, eval validation, package dry-run, and audit |
| `scripts/project-scanner.py` | Triage project/file risk and review triggers |
| `scripts/finding-formatter.py` | Normalize findings and output variants |
| `scripts/review-store.py` | Store/load/list/diff review state |
| `scripts/learnings-store.py` | Manage false-positive learnings |
| `scripts/sarif-uploader.py` | Help emit/upload SARIF where supported |
| `scripts/source-audit.py` | Static audit of local external skill/source directories |

## Critical Rules

1. Never start a full audit from empty args unless the user says `audit`.
2. Never edit files during read-only review, source/provenance review, history, delta, or simplify analyze/explain.
3. Never apply fixes without explicit approval of selected findings.
4. Never vendor third-party skill files into `skills/` during source/provenance review.
5. Always verify citation anchors before reporting findings.
6. Always state degraded-mode limits when validation tools are unavailable.
7. Always separate evidence from inference.
8. Always preserve unrelated dirty work.
9. Do not present `honest-review`, `simplify`, or `external-skill-auditor` as installable or invocable skills. Rewrite active references to `/review`, `/review simplify`, or `/review source`; leave only clearly historical or research evidence mentions.
10. For skill assets, apply skill-creator paradigms before reporting a no-finding result: run or cite audit/package/eval evidence when available, inspect references and eval coverage, and classify generated docs/catalog drift separately from source defects.

## Validation Contract

Before considering changes complete, run the focused checks relevant to this skill:

```bash
uv run python scripts/check.py
```

Completion criteria:

1. `scripts/check.py` exits 0.
2. Bundled `validate_skill` and `validate_evals` pass when evals are present.
3. Bundled `package.py --dry-run` reports portable.
4. Repo-only `audit.py` grade remains at or above the prior baseline when run from the monorepo (optional for portable installs; degraded mode is acceptable elsewhere).
5. Regenerate docs/catalog surfaces when `SKILL.md`, references, or evals change.
6. Any remaining legacy-name references are classified as wrappers, migration notes, generated evidence, or historical research.

Download from GitHub

Resources

Skill CatalogBrowse custom and external skills.

CLI ReferenceInstall and manage skills.

agentskills.ioThe open ecosystem for cross-agent skills.

---

View source on GitHub