ai-review
$
npx mdskill add arcasilesgroup/ai-engineering/ai-review``` /ai-review # normal: 3 macro-agents, validator stage /ai-review --full # one agent per specialist (6 post-W3) /ai-review 42 # review PR #42 /ai-review src/auth/ # review specific paths ```
SKILL.md
.github/skills/ai-reviewView on GitHub ↗
--- name: ai-review description: "Reviews code changes with human-quality judgment: PR reviews, file reviews, diff analysis, architecture feedback. Default mode runs the full specialist roster through 3 macro-agents; pass `--full` for one agent per specialist. Trigger for 'review this', 'give me feedback', 'look over my PR', 'any issues with this', 'is this merge-ready'. Not for evidence-backed gates; use /ai-verify instead. Not for narrative writing; use /ai-prose instead." effort: mid argument-hint: "[--full] [PR number or file paths]" mode: agent model_tier: sonnet mirror_family: copilot-skills generated_by: ai-eng sync canonical_source: .claude/skills/ai-review/SKILL.md edit_policy: generated-do-not-edit --- # Review ## Quick start ``` /ai-review # normal: 3 macro-agents, validator stage /ai-review --full # one agent per specialist (6 post-W3) /ai-review 42 # review PR #42 /ai-review src/auth/ # review specific paths ``` ## Workflow High-signal code review with full specialist coverage and aggressive false-positive control. `review` is review-only. This SKILL.md owns the user-facing contract; reviewer agent files provide specialist lenses and validation stages, not a competing surface. 1. **Step 0** — load stack contexts: read `.ai-engineering/manifest.yml` `providers.stacks` and apply `.ai-engineering/overrides/<stack>/conventions.md` for each stack. 2. **Detect target** — PR number, file paths, or current diff. 3. **Dependency preflight** — verify `review-context.md`, `review-validator.md`, plus required `.github/agents/reviewer-*.md` files for the selected mode and detected diff scope (`frontend` conditional on UI work — covers React, hooks, animation, typography, forms, a11y). STOP and report exact missing path(s) — never paraphrase missing reviewer instructions inline. 4. **Pre-review** — dispatch `review-context.md` via Agent tool; serialize output for every specialist. 5. **Specialists** — `normal` = 3 macro-agents; `--full` = one agent per specialist. Both run the full roster — grouping controls cost only. 6. **Validate** — dispatch `review-validator.md` with YAML finding blocks only (no reasoning chain). Code is read fresh; verdict CONFIRMED or DISMISSED per finding. 7. **Emit** — Findings / Risks / Recommendations / Self-Challenge, attributed by original specialist lens. ## Dispatch threshold Dispatch the `ai-review` agent for any narrative review (PR, branch, diff, or path scope). Each specialist runs in its own context window via the Agent tool. The agent file (`.github/agents/review.agent.md`) is the orchestrator handle; profiles, roster, output contract, and validator stage live here. ## When to Use - Before merging a PR - After completing a feature - When reviewing someone else's code - When you need architecture-aware feedback instead of deterministic gates (use `/ai-verify` for evidence gates). ## Specialist Roster Spec-140 W3 collapsed the roster from 11 specialists to 6. `reviewer-architecture` (DRY/reuse/proportionality) and `reviewer-maintainability` (readability/naming) heuristics are absorbed into `reviewer-correctness`. `reviewer-backend` was deleted outright (categorically mismatched: this repo is a Python CLI, no separate backend tier). | Specialist | Agent File | Focus | | --- | --- | --- | | `correctness` | `reviewer-correctness.md` | logic bugs, null handling, races, edge cases + absorbed architecture (DRY/reuse/proportionality) + maintainability (readability/naming) lenses | | `security` | `reviewer-security.md` | vulnerabilities, auth, data exposure, dependency risk | | `testing` | `reviewer-testing.md` | coverage, quality, edge cases, mocking patterns | | `performance` | `reviewer-performance.md` | query shape, complexity, hot paths, memory | | `frontend` | `reviewer-frontend.md` | React, hooks, a11y, TypeScript, animation, typography, forms (conditional; absorbs the legacy `design` lens per D-127-10) | | `compatibility` | `reviewer-compatibility.md` | breaking changes, backwards compat, migrations | `normal` macro-agent grouping: (1) correctness + testing + compatibility, (2) security + performance, (3) frontend (conditional on UI diff; merges with macro-agent-2 when not dispatched). ## Output Contract Group findings by severity first, then specialist lens. Keep attribution by original specialist even in `normal`. Include `not_applicable` / `low_signal` outcomes when a specialist had little to contribute. Show which findings survived adversarial validation. ## Stack-specific review guidance spec-133 D-133-10 consolidates stack-specific review guidance into the `.ai-engineering/overrides/<stack>/review.md` files. For each stack detected in the diff, load `overrides/<stack>/review.md`. Greenfield mode (stacks=[]): use generic review criteria + hint "add a project file and run `ai-eng doctor --fix`". ## Common Mistakes - Treating the 3 macro-agents in `normal` as reduced coverage — they are not. - Reporting by macro-agent instead of original specialist lens. - Skipping context exploration before review, or skipping the validator stage. - Treating style preferences as blocking findings. - Reading specialist agent files inline instead of dispatching via Agent tool. ## Examples ### Example 1 — review a PR before approval User: "review PR #42" ``` /ai-review 42 ``` Dispatches the 3 macro-agents (correctness, frontend, security/perf) over the diff, aggregates findings with corroboration, emits the Findings table with severity + remediation. ### Example 2 — full-coverage review on a complex diff User: "do the full reviewer roster on this branch" ``` /ai-review --full ``` Dispatches one agent per specialist (correctness, security, testing, performance, frontend, compatibility — 6 post-W3), runs the validator stage, deduplicates and ranks findings. ## Integration Called by: user directly, `/ai-pr`, `/ai-build`, `/ai-autopilot` (Phase 5). Dispatches: `review-context`, `reviewer-*`, `review-validator` agents. Read-only: never modifies code. See also: `/ai-verify` (evidence-backed gates), `/ai-learn` (extract review patterns post-merge). $ARGUMENTS
More from arcasilesgroup/ai-engineering
- ai-adviseProactive governance advisor — checks standards, decisions, and quality trends during development. Always advisory, NEVER blocks. Three modes: `advise` (post-edit), `gate` (pre-dispatch), `drift` (on-demand decision audit). Trigger for 'governance check', 'advise on this change', 'check for drift', 'is this aligned with active decisions', 'shift-left advisory'. Not for blocking gates — use /ai-verify. Not for narrative code review — use /ai-review.
- ai-analyze-permissionsUse when Claude Code keeps asking to approve commands you have already approved, when settings.local.json has grown large, or when you want to consolidate permission grants into wildcard patterns. Trigger for 'too many permission prompts', 'clean up permissions', 'audit my settings', 'consolidate allow rules'. Claude Code only — not available in GitHub Copilot, Antigravity, or Codex.
- ai-animationDesigns motion, transitions, and micro-interactions for UI components: spring animations, gestures, easing, staggers — taste-driven detail compounding. Trigger for 'animate this', 'add transitions', 'micro-interactions for', 'gesture design', 'swipe to dismiss', 'easing for this', 'stagger the'. Not for design systems; use /ai-design instead. Not for visual art; use /ai-visual instead. Not for testing animation code; use /ai-test instead.
- ai-autopilotDelivers large multi-concern specs and backlog runs autonomously: decomposes specs into sub-specs (or normalizes work items into a backlog DAG), deep-plans with parallel agents, builds a dependency DAG, implements in waves, runs a single final quality loop with one bounded quality-remediation pass (verify+guard+review on full changeset), delivers via PR. Trigger for 'implement spec-NNN end to end', 'autopilot this', 'autonomous delivery', 'decompose and ship', 'run the backlog', 'execute these GitHub issues', 'process the sprint backlog'. Invocation is the approval gate. Not for small or single-concern tasks; use /ai-build instead. Not for ambiguous requirements; use /ai-brainstorm first.
- ai-boardOperates the project board (GitHub Projects v2 or Azure DevOps): discovers configuration after install (fields, state mappings, process templates) and syncs work-item state at lifecycle transitions. Trigger for 'set up the board', 'configure our ADO board', 'discover board fields', 'move this issue to in-review', 'update the board', 'mark as in progress', 'sync the work item state'. Two subcommands: `discover` (post-install configuration write) and `sync` (lifecycle state transitions). Auto-invoked via `sync` by /ai-brainstorm, /ai-build, and /ai-pr; fail-open. Not for backlog execution; use /ai-autopilot --backlog instead.
- ai-brainstormForces rigorous design interrogation BEFORE any code: explores approaches, surfaces ambiguity, gathers evidence, produces an approved spec that becomes the contract for /ai-plan. Trigger for 'lets add X', 'how should we handle Y', 'whats the best approach', 'I am thinking about', 'what should we build for'. Not for existing approved specs; use /ai-plan instead. Not for execution; use /ai-build instead.
- ai-branch-cleanupCleans branches safely: switches to the default branch, prunes merged and squash-merged branches, syncs to remote, sweeps stale specs, rotates `.ai-engineering/runtime/` per retention policy. Trigger for 'tidy up', 'tidy branches', 'sync to main', 'delete old branches', 'start fresh', 'rotate runtime'. Auto-invoked by /ai-pr after merge. Not for committing changes; use /ai-commit instead. Not for code-level dead-code removal; use /ai-simplify instead.
- ai-buildCanonical implementation gateway: reads approved plan.md, resolves stack from manifest, deterministic-routes each task to its adapter, dispatches the build agent in an isolated worktree, runs TDD self-validation per task, then a single final quality loop with one bounded quality-remediation pass on the full changeset before /ai-pr. Trigger for 'go', 'start building', 'execute the plan', 'implement it', 'lets do this', 'build the plan', 'resume', 'continue'. Not without an approved plan; run /ai-plan first. Not for multi-concern specs needing decomposition; use /ai-autopilot instead. Not for a single function or subcomponent; use /ai-code.
- ai-codeWrites production code that satisfies stack-context standards on the first pass: interface-first design, backward-compatibility checks, lightweight self-review. Trigger for 'implement this', 'write the code for', 'add X to Y', 'build this function', 'make this work'. Not for tests; use /ai-test instead. Not for debugging; use /ai-debug instead. Not for refactoring; use /ai-simplify instead. Not for executing an approved plan end-to-end; use /ai-build (the gateway).
- ai-commitRuns the governed commit pipeline: auto-branches from protected, stages selectively, formats and lints, scans for secrets, gates docs, composes a conventional message, pushes. Trigger for 'commit my changes', 'save my work', 'push this to remote', 'stage these files', 'ship it'. Not for opening a PR; use /ai-pr instead. Not for branch hygiene; use /ai-branch-cleanup instead.