aid-review
Review an existing artifact against criteria and return findings and recommendations in one pass -- code, a diff, a design, a pull request, a ticket, a document, a UI, whatever you name. Use this skil
SKILL.md.claude/skills/aid-review/SKILL.md
GitHubReview (run now, produce findings)
/aid-review performs a review now and returns grade + findings +
recommendations. It is the adversarial sibling of /aid-ask: both are single-shot,
grounded, cited, and never plan-and-halt -- review evaluates an existing artifact against
criteria, where /aid-ask answers a free-form question.
- Not a numbered pipeline phase. It runs on demand; it does not enter the
Discover->Execute flow and never routes to
/aid-execute. - Read-only except: the findings ledger (a
.tempartifact) and, only after your approval, a publish to the reviewed target (a PR/ticket comment, doc notes). It never edits the reviewed code/design itself and never fixes -- fixing is/aid-fix's job.
State machine: INTAKE -> REVIEW -> VERIFY (loop) -> PRESENT-FINDINGS [human] ->
PUBLISH (on approval) -> DONE. Print the state-entry line on entry to each state
([State: NAME] -- {one-line purpose}), the convention every AID skill uses.
State: INTAKE
Purpose: resolve the target + criteria, pick the path, allocate the work folder.
Step 1 -- require a target
If the argument is empty, ask exactly one bootstrapping question and wait:
What do you want to review? Point me at a file/dir, a PR, a ticket id, a
work-NNN, "my changes", or describe the target.
Step 2 -- pick the path (fast vs guided)
Fast path -- the prompt carries an explicit, resolvable target whose review method is unambiguous. Record the target, method, and tentative delivery; go straight to REVIEW.
| Signal | Method | Tentative delivery |
|---|---|---|
PR link / #123 |
diff review | PR comment(s) via gh |
ticket id (PROJ-45) |
assess ticket content | ticket comment via /aid-update-ticket |
| file / dir path | static review vs KB + coding-standards | findings report |
| "my changes" / working tree / staged | working-diff review | findings report |
| commit SHA / range / branch | diff review | findings report or PR comment |
work-NNN or an AID artifact (REQUIREMENTS/SPEC/PLAN/DETAIL) |
review vs its acceptance criteria + KB | findings in the work folder |
a KB doc (.aid/knowledge/*.md) |
review vs the KB-authoring rubric | findings report |
Guided path -- target open-ended (a UI, a BDD-scenario set, "is my auth sound?"), or a fast trigger that does not resolve (file absent, ticket id but no catalogued connector, PR # with no repo context). Interpret the request and form a plan -- what you will review, how (method + any tool/MCP needed to gather evidence), and where findings will be delivered -- present the plan and wait for the user to confirm or correct before spending review effort.
Step 3 -- criteria
Derive the review criteria from the KB (coding-standards.md, architecture.md, and
the artifact's own acceptance criteria if it is AID work) plus anything the user named.
Fast path: implicit. Guided path: part of the plan the user confirms.
Step 4 -- classify complexity (sets model + effort)
- Simple (one small file, a short doc, a tiny diff) -> dispatch
aid-reviewerat modelsonnet, effortlow/medium; single light VERIFY pass. - Standard/complex (a full PR, a design, security/perf, multi-file) -> model
opus, efforthigh; full VERIFY loop. Verifier tier is always >= reviewer tier.
Step 5 -- allocate the work folder + STATE
Consult the Work Initiation Gate first
(.aid/runtime/templates/work-initiation-gate.md): run
bash .aid/runtime/scripts/works/enumerate-works.sh (main tree + every git worktree).
Empty output -> proceed with the allocation below, no prompt. Works exist -> ask the
gate's single new-vs-continuation question with the enumerated list; on continuation
the gate routes to the chosen work's resume door and this skill STOPs (allocates
nothing); on new work, allocate below.
Resolve <work-id> as work-{NNN+1}, where NNN is the maximum work-NNN numeric
prefix across every record the enumeration above already returned (cross-worktree by
construction -- never re-scan a local .aid/works/ glob for this number; gate § 3a step
1; work-001 if none). Derive a short kebab-case slug from the target.
Create and enter the worktree, before authoring anything (gate § 3a step 2):
bash .aid/runtime/scripts/works/worktree-lifecycle.sh create <work-id> <name> --
idempotent; prints the worktree's absolute path on success/no-op; on a non-zero exit or an
empty path, surface the error and STOP (do not allocate on the current, possibly
master, tree); on success, enter the resolved path (host-native EnterWorktree where
available, else cwd + surface -- worktree-lifecycle.md § Step 2).
Only now, inside the entered worktree, create .aid/works/work-NNN-<slug>/ (reusing
the <work-id> resolved above). Copy .aid/runtime/templates/work-state-template.yml to
.aid/works/work-NNN-<slug>/STATE.yml and write the opening frontmatter (direct edit):
pipeline.path: lite, initiator: aid-review, lifecycle: Running, active_skill: aid-review, started/updated timestamps. Leave the 7-phase phase scalar at its
template value -- a standalone review is not a pipeline run and does not drive it
(specs/aid-review.md 10). The work-level git worktree is created and entered above by the
gate's § 3a step -- mandatory per FR1, no longer optional.
Advance: REVIEW.
State: REVIEW
Purpose: gather evidence and produce the grounded findings ledger.
- Gather evidence the confirmed method needs, using whatever tools/MCP the plan
calls for --
git difffor a PR/commit/working-tree,Read/Grepfor a file/dir, the browser MCP to capture a UI, or -- for a ticket target -- fetch it by invoking/aid-read-ticket [<connector>:]<ticket-id>(the connector resolution and host-MCP fetch live there, feature-001; no direct-fetch recipe is re-implemented here; skip silently if no matching connector is catalogued). - Dispatch
aid-revieweronce, in a clean context (model+effort from INTAKE Step 4), with the standard one-off five-section brief per.aid/runtime/templates/reviewer-dispatch.mdOne-off reviews:ARTIFACTS UNDER REVIEW/CONTEXT/RUBRIC/OUT OF SCOPE/OUT-OF-SCOPE FINDINGS POLICY. The RUBRIC MUST mandate reading.aid/knowledge/+ the relevant source and citing a KB doc or afile:linein every finding's Evidence cell. The reviewer writes the global 7-column ledger (.aid/runtime/templates/reviewer-ledger-schema.md:# | Severity | Status | Doc | Line | Description | Evidence) to.aid/.temp/review-pending/<work>-review.md.
Advance: VERIFY.
State: VERIFY (who reviews the reviewer)
Purpose: ensure the review is grounded, correct, and complete before the human sees it.
- Mechanical grounding check (no dispatch): reject any finding row whose
Evidencecell is empty -- an ungrounded finding never reaches the human. - Adversarial verification -- dispatch a second
aid-reviewerin a clean context (never sees the first reviewer's reasoning) to independently check each finding against KB + source: flag ungrounded / hallucinated / mis-severity findings, and any material gap (a real issue the first pass missed). It writes a review-quality ledger to.aid/.temp/review-pending/<work>-verify.md. - Grade the review:
bash .aid/runtime/scripts/grade.sh --explain <verify-ledger>. If it is not clean, loop back to REVIEW so the first reviewer revises (drop ungrounded findings, add missed ones). Circuit-breaker: 3 cycles -> write.aid/works/{work}/IMPEDIMENT-review.md, set STATElifecycle: Blockedwith a block reason, and surface it instead of looping.
Note: the target's grade (grade.sh --explain on the review ledger) is computed for
the presentation as information only -- it does NOT drive a fix loop here.
Advance: PRESENT-FINDINGS.
State: PRESENT-FINDINGS (always a hard stop -- human final say)
Set STATE lifecycle: Paused-Awaiting-Input. Present:
- the target grade (from
grade.shon the review ledger) -- informational; - the verified findings, severity-ranked, each with its
file:line/ KB evidence; - recommendations, and a printed suggestion to act: "N issues found -- run
/aid-fix(or/aid-update) to address them" (review never starts the fix itself); - the proposed delivery action + the exact comment/notes text that would be posted.
Then STOP and await the human's decision (approve / edit the text / choose a different delivery / do not publish). Nothing is posted to any external target until they approve.
Advance: PUBLISH on approval; otherwise DONE.
State: PUBLISH (only on approval)
Deliver by the method appropriate to the target, chosen by judgment (not a hardcoded
enum): a PR comment via gh; a ticket comment via /aid-update-ticket comment [<connector>:]<ticket-id> <text> (still user-authorized -- the approval just given at
PRESENT-FINDINGS is what authorizes this call, and the skill previews the exact payload again
at its own CONFIRM before posting); a findings report in the work folder (+ optional
inline-comment suggestions) for code; inline notes for a document. Graceful fallback: no PR /
no catalogued connector / unknown target -> present the exact text for the human to paste.
Publishing is optional and never blocks DONE.
Advance: DONE.
State: DONE
Set STATE lifecycle: Completed, updated now, append a ## Lifecycle History row.
Leave the findings ledger on disk (.aid/.temp/review-pending/<work>-review.md) so a
follow-up /aid-fix can consume it. Keep the work folder as the audit record.
Constraints
- KB + source grounding is enforced (VERIFY step 1 + the reviewer RUBRIC): no finding without a KB/source cite.
- Clean context: the REVIEW and VERIFY dispatches never share context; the verifier never sees the reviewer's reasoning.
- Reviews are always a sub-agent dispatch (
aid-reviewer), never inline. - Human final say before any external commit (PRESENT-FINDINGS).
- Read-only on the reviewed artifact; never fixes (hand off to
/aid-fix). - Tracking: write STATE
lifecycleat every transition (Runningat INTAKE, the gate pauses, terminalCompleted/Blockedat the end).