Review

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.

Dispatch

Classify $ARGUMENTS before reading widely.

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

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.

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.

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

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:

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.