| name | review-prototype |
| description | A method for organizing a prototype that illustrates an agentic, spec-driven PR review—the type a person employs to determine if a merge is acceptable without scrutinizing each alteration. Applicable when a user intends to create, outline, or develop a review interface, a review dashboard, a PR-review process, or a "verdict screen" for an agent-generated modification set, particularly one generated by a specification-driven development (SDD) workflow. Triggers encompass: "review flow", "PR review prototype", "review UI", "how should I present this review", "verdict-first review", "visualize the PR", or asking how a developer should review an agent's output. This is a METHOD skill — it tells you how to think about and lay out the prototype; it does not lock you to a single output format. Do NOT use for performing the code review itself (finding bugs, judging the author) — that is a different skill. |
Review Prototype Method
A prototype here is a thing a developer opens to decide whether an agent-generated change set can ship, without being forced to read every diff. The deliverable is a decision surface, not a diff viewer with extra steps.
This skill encodes how to structure that surface. It is format-agnostic: the same method drives a self-contained HTML page, a React artifact, a Figma-style mock, or a static diagram. Pick the format from the request; keep the structure constant.
The one principle everything else follows from
The reviewer's scarcest resource is attention, and they do not want to read diffs. They want the review to tell them whether they need to. So the prototype is a funnel of trust, top to bottom:
Summary → Design-vs-requirements → Code-vs-design → Verdict + ranked risks
│
(only if they choose to look)
▼
Drill-down: blast-radius-ordered files,
diffs, traceability, findings
Build top-down (start from the verdict), even though it is tempting to build bottom-up (start from the files). A prototype that opens on a file list has already failed the principle.
Step 0 — Inventory what you actually have
Do this before designing anything. The prototype's strength comes from grounding every claim in a real artifact; invented content is the main failure mode. Look for, in rough priority:
- A summary source — a spec's feature-summary section, a PR description, a ticket.
- A requirements layer — proposal / spec / acceptance-criteria files (behaviors, ACs).
- A design layer — implementation rules/plan, and crucially a spec review verdict if one exists (this is the design-vs-requirements gate, pre-made).
- A findings source — static-analyzer or LLM code-review output (this is the code-vs-design gate).
- The change set — the diff/patch, with per-file status (A/M/D) and +/− counts.
Whatever is missing, degrade gracefully: a missing gate becomes a "not available" state (distinct from PASS), missing traceability drops the chips, a missing summary falls back to the PR description or a two-line synthesis. Never fabricate a verdict, a risk, or a rule to fill a slot — say the input wasn't present. Read the real files; quote/paraphrase faithfully; do not paraphrase a spec into something it doesn't say.
Step 1 — Write the verdict screen first
This is the landing view and the part the reviewer reads in 30–90 seconds. Five blocks, in order:
-
Summary — feature name, 2–4 sentences of what the change does, and scale chips (file count, +/− totals, behavior/criteria counts). Pull prose from the real summary source.
-
Decision banner — one prominent verdict and a one-line rationale. States: cleared to merge / merge with caution / human in the loop / blocked. Derive it, don't author it (see Step 2).
-
Two conformance gates, side by side — the heart of the screen:
- Design ↔ requirements — "does the design satisfy what was asked?" Status + one-line evidence + counts + source attribution.
- Code ↔ design — "does the implementation match the design?" Status + evidence + counts + source.
- Each gate needs three states: pass / fail / not run (the third is not the same as pass).
-
Risks, ranked — each row: a status tag, a title, a description, an inspect → action that jumps into the drill-down at the relevant file. Tags: materialized (predicted by the design review and confirmed by a finding — render first, render loud), open (predicted, unconfirmed), mitigated (covered by a done-check/test).
-
One explicit entry into the drill-down — a single CTA. The drill-down is opt-in, not the default.
Step 2 — Derive the verdict; never hand-wave it
The decision must be a transparent function of the inputs, and the UI should be able to explain it:
- Design gate ← the spec-review verdict (PASS/FAIL + blocker/major/minor counts).
- Code gate ← findings severity (any critical/major → FAIL; only minor/refactor/info → PASS-with-notes; no findings file → not-run).
- Overall ← the worse of the two gates, escalated if any risk is
materialized.
The most valuable single signal is risk materialization: a risk the design review predicted that a finding confirms. Match by shared rule/criterion tags first, shared file path second, fuzzy keyword last (and downgrade confidence when only fuzzy). When it lands, it tells the reviewer in one glance "the thing we worried about actually broke" — that is the strongest possible case for human-in-the-loop, so make it unmissable.
Step 3 — Order the drill-down by blast radius, never alphabetically
Default diff tooling sorts files A→Z, which scatters one decision across unrelated files. Instead group files into review nodes ordered by consequence, each lower node depending on the one above being correct. The grouping is the judgment; a typical shape:
- Tier I (read closely): persistence/constraints → core domain/state machine → the hardest computation (time, money, concurrency — wherever boundary bugs hide).
- Tier II (triage): peripheral services → web/UI layer → migration/cleanup → tests.
- A final verify node: "boot + run the suite" — the step that catches what a diff read cannot (cross-DB behavior, boundary correctness).
Each node carries a Check directive (what to do) and, where relevant, a Watch callout (where it breaks). If the pipeline emits an explicit ordering, use it; otherwise infer from package/layer and label the tiers.
Step 4 — Make each file traceable and each finding locatable
In the drill-down:
- Traceability — every file links back to the rule/criterion that justifies it. New files get a file-level "why this exists"; edited files get the rule annotation anchored to the specific changed hunk. This is intent, not proof (see Honest limits).
- Findings — render on the file row (severity badge), the node (a critical flag, auto-expanded), and in the diff panel (the finding text + a line locator that scrolls to and highlights the exact line). Treat static-analyzer and LLM findings as visual equals — source is a tag, not a layout.
- Optional map view — a treemap sized by lines-changed, colored by tier, with severity overlays, is a strong "shape of the PR" companion to the list. Size encodes where the work is; color encodes where the risk is — and they are not the same, so lean on color for priority.
Choosing a format
- Self-contained HTML (single file, embedded data, no build) — best default for a shareable, offline, demo-able prototype. Embed the diffs/findings as JSON; keep it dependency-free.
- React artifact — when the prototype needs richer interaction or will feed a real component later.
- Diagram / static mock — when the user wants to communicate the flow rather than operate it (talks, PRDs, alignment).
Decide from the request. The structure (Steps 1–4) does not change with the format.
Honest limits — bake these into the prototype, don't hide them
The verdict reads as more total than it is. Reflect the truth in the UI:
- The code gate is a floor, not a ceiling: "FAIL, 3 criticals" means at least these exist; "PASS / no findings" does not prove correctness — it reflects the tool's coverage.
- Traceability is intent, not verification: a chip says a file is meant to satisfy a criterion; it does not prove it does. Link intent; let the human or a test run verify.
- The verify node stays first-class, because the highest-consequence risks (concurrency, cross-database, time boundaries) are exactly the ones invisible to a diff read.
A prototype that quietly overstates its own authority is worse than one that shows its seams.
Anti-patterns
- Opening on the file list or the diff (bottom-up). The verdict comes first.
- Grouping files by type ("all deleted files", "all schema files") instead of by consequence. That is a taxonomy of artifacts, not a ranking of decisions.
- Inventing a verdict, risk, or rule when the input is absent. Mark it not-available instead.
- Treating LLM findings and static findings as different UI citizens.
- Burying the merge decision below the diffs, or omitting it entirely.
- Sizing a treemap by risk (you can't) instead of by change, then relying on size for priority instead of color.
