/nai-review — evidence-checked review preparation

You drop the material under review into 09 Review Packs/inputs/<slug>/subject/ — “solution designs, ADRs, landscape excerpts, model exports, in whatever shape the client produced” — optionally a criteria catalog as criteria.md and EA-repository exports under ea/ beside it, and type /nai-review <slug>. Three waves run in order: review-scoper inventories the drop and establishes which criteria are in force, finding-drafter writes findings each anchored to a verbatim quote from a dropped file, and finding-checker re-opens every cited file and verdicts each citation CONFIRMED or UNSUPPORTED. The orchestrator then synthesizes the pack itself, and cockpit-writer renders it as one self-contained HTML page. The command states the boundary in its own opening line: “You prepare and check; you NEVER deliver — the review verdict, the trade-off calls, and all stakeholder communication belong to the human.”

What makes this one different from /nai-option-study is the shape of the middle. The command file names the contrast directly: “Where /nai-option-study is the repo's worked example of an iterating loop, this system is its deliberate contrast: one adversarial verify pass, no loop. A finding whose evidence does not hold is flagged for the human, never sent back for redrafting — iterating would let the drafter rewrite findings until they slip past the checker.” The waves are also kept apart in time, not just in context: each dispatch happens “Only after Wave 1 returns — never in the same message”, and the same again for Wave 3.

%%{init: {'theme':'neutral', 'flowchart':{'htmlLabels':false,'nodeSpacing':45,'rankSpacing':55}}}%%
flowchart TD
    H["Human types /nai-review <slug>"] --> C

    subgraph L1 ["1 - Orchestrator (.claude/commands)"]
        C["/nai-review<br/>three waves, one pass each<br/>then synthesizes the pack itself"]
    end

    C -->|"Wave 1"| S["review-scoper<br/>inventory, criteria in force, gaps"]
    S -.->|"review-brief.md"| C

    subgraph L2 ["2 - One pass, no loop"]
        D["finding-drafter<br/>no quote, no finding"]
        V["finding-checker<br/>tries to break each citation"]
    end

    C -->|"Wave 2"| D
    D -.->|"working/findings.md"| V
    V -.->|"working/verification.md<br/>CONFIRMED / UNSUPPORTED"| C

    C ==> PACK["review-pack.md<br/>synthesized by the orchestrator"]
    PACK --> W["cockpit-writer (profile: review)<br/>a view, never a calculator"]
    W ==> OUT["review-pack.html<br/>you deliver the review"]

    S --> T1
    D --> T1
    W --> T1
    V --> T2
    subgraph L3 ["3 - Tools (the only route out)"]
        T1["Read / Write / Glob<br/>dropped files only — no web, anywhere"]
        T2["Read / Write / Grep<br/>only the files findings cite"]
    end

    classDef orch fill:#dcefe9,stroke:#0f6f63,stroke-width:2px
    classDef tool fill:#f4f1ea,stroke:#8a7a5a
    classDef human fill:#fdf3e0,stroke:#8a5a00,stroke-width:2px
    class C orch
    class T1,T2 tool
    class H,PACK,OUT human

The subagents and what they may touch

The checker's grant is the one that differs, and the difference is deliberate: it has Grep where the others have Glob, because its input list is fixed by the findings themselves — “You read only cited files — you never go looking for substitute evidence in files a finding does not cite.” The orchestrator writes review-pack.md itself, in a step the command file labels “Synthesis (you do this yourself)”.

The guardrails, and where each one lives

Each of the four agent files also carries the repo's standard boundary paragraph verbatim: “Read-only against every remote system. You write files inside this repo only, and only the files named in ## Output. You NEVER create, change, delete, or send anything in a remote system — you have no such tools and must not attempt it.” Neither the scoper nor the drafter nor the checker is granted a web tool, and the drafter says why: “a review is grounded in what the client dropped, not in what the web says about it.”

What a run leaves behind

Four markdown files and one HTML page, all under 09 Review Packs/packs/<slug>/: review-brief.md, working/findings.md, working/verification.md, the synthesized review-pack.md, and review-pack.html. The pack's own sections are fixed by the command file: a header, an executive summary, a findings table (ID | Title | Severity | Criterion | Verdict), a per-finding block pairing the drafter's statement and quote with the checker's verdict, then three sections written for the human to act on — “Unsupported findings — evidence did not hold”, “Open questions — needs your judgment”, and “Material gaps: the brief's gaps list, carried forward”. The first two are never dropped when empty: “If there are none, say so plainly; never omit the section.”

The cockpit is the reading surface for the same content, and its extraction rules decide what lands in its ⚠ Needs you block: “every finding in the ‘Findings’ table whose severity is HIGH (severity high) or MEDIUM (severity medium); every entry under ‘Unsupported findings — evidence did not hold’ (severity high); every numbered item under ‘Open questions — needs your judgment’ (severity high). LOW findings are detail, not decision items.” Verdicts and severities are “rendered verbatim — never recomputed, never re-tallied”, and where the pack and a working file disagree the cockpit “render[s] both and say[s] so; do not reconcile them.” Ticking a checkbox is convenience only: “It is never read back into the markdown, and the markdown stays the record.”