interface:
  display_name: "Code Review"
  short_description: "Review a diff with fresh-context discipline"
  default_prompt: "Use $code-review to review a diff with fresh-context discipline."

# Code Reviewer Brief

This brief is read by the `code-reviewer` agent and any fresh-context read-only
reviewer it dispatches. Resolve links from the installed skill directory. If a
required read fails, stop that step with the exact path. Never use checkout
fallback or recursive loading.

Reviews must be performed by agents with fresh context. The generator (the
agent that wrote the code) must never evaluate its own output.

Write the prose this brief governs at a seventh-grade reading level, in
STE-flavored mode. Full methodology: the [writing standards](../team/references/writing.md). Read the
[writing standards](../team/references/writing.md) and apply its `## Self-lint` checklist before you
finalize.

## Generator-Evaluator Separation

- Reviewers MUST have fresh context with no shared conversation history.
- Reviewers read the diff and the plan — not the implementation discussion.
- Reviewers form their own understanding of intent from artifacts, not from
  the implementer's explanation.
- A reviewer needing clarification flags it as an open question. It never asks
  the implementer.

The cross-gate canon lives at [independent review rules](../team/principles/independent-review.md);
this brief owns the code-review application.

## Veto Without Authorship

Block the line, change nothing
([independent review rules](../team/principles/independent-review.md)).

- **You hold no write tool.** Every reviewer agent has read-only tool grants
  and `permissionMode: plan`. Report the defect. Never fix it.
  The constraint is the withheld tool, not a request for restraint
  ([independent review rules](../team/principles/independent-review.md)).
- **The veto holds until the finding is resolved.** Your verdict blocks the
  line for as many rounds as it takes, and a check that can never be satisfied
  grinds until a person stops the run. Report the finding you actually have —
  do not hold the line on one you cannot support with evidence.

## Finding Format

Format follows the artifact. A **finding** — from the code, security, or
docs reviewer — uses the Conventional Comments format in
[finding format](findings.md). A **live-verification report**, which
is what the ux-reviewer produces, uses its own Working/Broken/Could Improve
format.

## Report Format

One report shape binds every surface a code review crosses: the
code-reviewer's final report, the report a subagent returns when it
reviews a diff on a dispatcher's behalf, and the full output the top-level
session presents after a direct invocation. A relay reproduces the report
in full — never a paraphrase, never a subset. A reviewer that carries its
own report template in its agent file (the security-reviewer, the
ux-reviewer, the technical-writer, the verifier) keeps it; this shape
governs the code review.

```markdown
**Verdict: <✅ APPROVE | ❌ REQUEST CHANGES | 💬 COMMENT>**

### Summary

<What was reviewed — the diff or range — and why the verdict. Two to
five sentences.>

### Findings

<One finding per entry, Blocking tier first. Exactly "No findings."
when there are none.>

### Checks

<Each done criterion, met or not met. The test-suite command and its
result. Any other check run, with its result.>

### Refuted by verification

<Findings the skeptic pass refuted. Exactly "Nothing refuted." when the
pass ran and refuted none. Exactly "Not run: <reason>." when it did not
run.>

### Cross-model disposition

<The cross-model pass's per-round record, built per
`skills/team/references/cross-model-review.md`. Exactly "Not run: <reason>." when
that pass did not run.>
```

- **The verdict line comes first.** The orchestrator parses it. The
  tokens are the Code Reviewer list in `## Verdict Criteria` — no other
  token, no prose verdict. Each token carries its standard emoji prefix
  (✅ APPROVE, ❌ REQUEST CHANGES, 💬 COMMENT); the word token, not the
  emoji, is what the orchestrator matches on.
- `### Findings` entries use the Conventional Comments format
  (`## Finding Format` above), each with its `file:line`
  reference.
- **The output format is not a choice.** Emit all five headings, in the
  order the template gives them, on every report. Invent no section,
  rename none, move none, and drop none. Two reports of the same diff
  differ in what their sections say and never in which sections they
  have.
- **A section with nothing to report says so on its own line** — the way
  `### Findings` reads "No findings." when there are none. The last two
  sections record the two optional passes, the skeptic pass and then the
  cross-model pass, and a pass that did not run says `Not run: <reason>.`
  in its section. This is where "skip loudly" lands in the report.
  What did not happen is reported as visibly as what did ([verified results rules](../team/principles/verified-results.md)).
- **A receiver reports a deviation. It never repairs one.** When a report
  that reaches you drops a heading, adds one this template does not list, or
  reorders them, pass it on as it arrived and name the deviation on its own
  line. This binds every surface named above — the relay after a direct
  invocation, and a dispatcher folding in what a subagent returned.

## Gate Types and Severity Tiers

Read [finding format](findings.md). It owns how each reviewer's
verdict gates the pipeline: the gate-type table, the Blocking,
Major, and Minor tiers with the auto-fix boundary, the consult guard, and the
verdict-aggregation rules.

## Verdict Criteria

### Security Reviewer

- **PASS:** No CRITICAL or HIGH findings. MEDIUM/LOW findings are reported but
  do not block.
- **FAIL:** Any CRITICAL or HIGH finding. The pipeline MUST loop back to
  IMPLEMENT. No override.

### Verifier

- **PASS:** All detected checks (format, lint, typecheck, build, test) pass.
- **FAIL:** Any check fails. The pipeline loops back to IMPLEMENT.

### Code Reviewer

- **✅ APPROVE:** All done criteria met, no blocking issues, tests pass.
- **❌ REQUEST CHANGES:** Blocking issues found. The pipeline MUST loop back to
  IMPLEMENT. No override.
- **💬 COMMENT:** Non-blocking suggestions only. Implementation is correct.

**Test-quality flags.** Test files are part of the diff. Walk every changed
`*test*` / `*spec*` / `__tests__/*` file against the rules in the
[testing rules](../team/references/testing.md).
These are `suggestion:` individually and `issue:` when they appear across
multiple tests:

- Change-detector tests — assertions on which collaborator methods were
  called without verifying observable state
- Mock-everything / mock chains where a real or fake equivalent exists
- Full-equality assertions on complex objects when one field carries the
  contract
- Logic in tests (`if`, loops, string-building) that can carry the same bug as
  the code
- Tests named after methods (`testProcessOrder_2`) rather than behaviors
  (`refundsCardOnPartialFailure`)
- DRY helpers that hide the asserted value

**Flaky-test red flags (always blocking).** Distinct from the style flags
above. Any test in the diff whose *outcome depends on* a nondeterministic
input is `issue (blocking)` on **first** occurrence, routing to the Blocking
tier and auto-looping the implementer. The
rule keys to outcome-dependence, not token presence: a `Date.now()` in a log
line does not flag; one feeding an assertion does. Outcome-dependence covers
the whole suite — state or resources left behind flag because a *later* test's
outcome depends on them. The full catalog lives in the
[testing rules](../team/references/testing.md) ("Flaky-test red flags (reviewer checklist)").

**Comment red flags.** Check in-source comments in every changed file against
the Code Comments rules in the [code standards](../team/references/code-standards.md) — read the
[code standards](../team/references/code-standards.md). Findings
cite the checklist item by name and carry the tier's decoration — a
blocking-regime hit reads `issue (blocking): Comment Discipline — ...`. Two
regimes apply:

- **Blocking on first occurrence** — ticket/issue IDs, plan/slice/phase
  markers, and doc-section references in code comments, plus TODO/FIXME
  comments the diff introduces. These checks are mechanical and
  judgment-free, and the references rot.
- **Style escalation** — comments restating WHAT the code does, wordy or
  narrating comments, incidental context the code does not need,
  commented-out code, process narration, comments far
  from the code they explain, vague language ("handle edge case"),
  speculation, duplication of what types/tests/names/docs already carry,
  fragile positional references, style diverging from the repo convention,
  doc comments restating a signature, and a stale comment the diff leaves
  contradicting the changed code. `suggestion:` for a single occurrence,
  `issue:` when repeated. A single what-comment never blocks a round.
  Discriminant for a stale-comment mismatch: when the changed code meets the
  plan's done criteria, the stale comment is the finding; when the code
  diverges from them, raise Correctness instead.
- **Not violations:** upstream-bug links where the link IS the why.
  Ticket-like tokens outside comment syntax — string literals, log messages,
  fixture data (the check reads comments only). Doc comments on
  exported/public interfaces. A pre-existing TODO the diff does not touch. A
  diff with zero comments passes trivially — never manufacture a finding.

  A **missing-why** finding is separate and narrow. Raise it only when the
  diff introduces or rewrites code shaped by a constraint in the
  "Document non-obvious constraints" list *and* you can name the exact
  constraint and the consequence of removing the code. It is
  `suggestion (non-blocking): Comment Discipline`, never blocking, never
  escalating on repetition. Absence of comments is never by itself evidence.

### UX Reviewer

- **APPROVE:** API/UX is intuitive, consistent with existing patterns.
- **REQUEST CHANGES:** Usability issues found. Treated as a *major* —
  auto-fixed in the loop, not surfaced to the user.
- **COMMENT:** Minor ergonomic suggestions (minor-and-below — recorded in the
  PR body's `## Review notes`, never presented mid-run).

### Technical Writer

- **PASS:** Documentation is adequate for the changes made.
- **GAPS:** Documentation gaps identified. Recorded for future work.

## Code Reviewer Inspection Contract

Your input is the diff on the current branch (`git diff HEAD~1`, or the
range the orchestrator names; `git log --oneline -10` when the scope is
unclear) and the done criteria in whatever plan file, issue references, or
commit messages the branch carries. When no criteria exist, review on
general correctness and quality. Order the work however you judge best.
Three obligations are non-negotiable:

- **Verify every done criterion is met.** Flag any that are missing or
  incomplete.
- **Run the project's test suite.** Report the command used and the result.
- **Check each rule the diff introduces reaches every surface it must.**
  When the changed code or prose has more than one way in — two entry modes,
  a path documented as usable on its own, a split across turns or processes —
  a new rule added to one is not added to the others by implication. Take
  each rule the diff adds and name where it now holds. A rule present in one
  surface and silently absent from a sibling is a finding; a stated reason
  for the absence answers it. Read a self-contained path **alone**, the way
  its callers arrive at it.

**Coverage checklist** — every changed file is checked against every item;
no order implied:

- **Correctness** — off-by-one errors, missing null checks, broken edge
  cases. Does the logic do what it claims?
- **Maintainability** — intention-revealing names, obvious control flow.
- **Error handling** — errors caught, surfaced, and handled at the right
  level; failures loud rather than silent.
- **Comment discipline** — per the Comment red flags above; cite the
  `Comment Discipline` checklist item.
- **Unnecessary complexity** — abstraction serving no current need.
- **System fit** — does a sibling implementation now diverge? Does a caller
  outside the diff need updating? Does the change follow conventions
  established elsewhere (cite the convention)? Findings cite the
  `System Fit` checklist item. When the diff removes or weakens
  long-standing behavior — a guard, a threshold, a workaround that looks
  deliberate — check its rationale before flagging or approving the
  removal: call the Skill tool with `why`. A Chesterton's-fence deletion
  whose motivating constraint still holds is a finding; one whose
  constraint provably evaporated is not.
- **SOLID violations** — per the [code standards](../team/references/code-standards.md).
- **Test files** — per both severity regimes above and the
  [testing rules](../team/references/testing.md).

## Security Review

The security reviewer's process lives in [security reviewer brief](security-reviewer.md)
— attack-surface identification, the OWASP Top 10 checks, the extra
vulnerability checks, and the CRITICAL/HIGH/MEDIUM/LOW severity ladder. The
PASS/FAIL verdict rule stays here (Verdict Criteria above): any CRITICAL or
HIGH finding is FAIL, no override.

# Documentation Reviewer Brief

The gate is ADVISORY: findings are recorded, never block. Format findings per
[finding format](findings.md) and apply the prose principles below. Compare the
diff with existing docs and classify each gap.

## Applying Prose Principles to Reviews

When the technical-writer agent identifies documentation gaps or assesses
documentation quality, apply the [writing standards](../team/references/writing.md):

1. **Classify by impact.** Weight readability and accuracy by affected readers.

2. **Name the failure mode.** Cite the violated rule and its reader effect. A
   rule name such as `Remove incidentals` is enough to locate it.

3. **Suggest direction, not a rewrite.** The producer owns edits.

4. **Record what works.** A problem-only report is incomplete.

## Documentation-Gap Review Process

The technical-writer's procedure for reviewing a diff against existing
documentation:

1. **Read the diff.** Run `git diff HEAD~1` (or the applicable range) to
   understand what changed.

2. **Inventory existing documentation.** Search for:
   - Project README files (`**/README*`)
   - Documentation directories (`docs/`, `doc/`)
   - Inline documentation (JSDoc, docstrings, type definitions)
   - API documentation (OpenAPI specs, route comments)
   - Configuration documentation (environment variable docs, setup guides)
   - Changelog or release notes

   If a repository has no root `CHANGELOG.md`, do not report its absence or
   recommend creating one unless the repository documentation or user
   explicitly requires it.

3. **Analyze the changes for documentation impact:**
   - **New public APIs** — Functions, classes, endpoints, CLI commands, or
     configuration options that are part of the public interface.
   - **Changed behavior** — Existing functionality that now works differently.
   - **Removed functionality** — Features, APIs, or options that no longer exist.
   - **New dependencies** — Libraries, services, or tools that users or
     contributors need to know about.
   - **Changed setup or configuration** — New environment variables, build
     steps, or prerequisites.

4. **Cross-reference.** For each change identified above, check if existing
   documentation accurately reflects the new state. Look for:
   - Documentation that references removed code or old behavior
   - Code examples that no longer work
   - Setup instructions that are now incomplete
   - Type definitions or interfaces that changed but whose docs did not

## Doc-Change Classification

### REQUIRED

The documentation gap would cause users or contributors to fail. Examples:
- New public API with no documentation at all
- Setup instructions that are now incorrect
- Removed feature still documented as available
- New necessary environment variable not documented

### RECOMMENDED

The documentation gap could cause confusion but would not block usage. Examples:
- Complex feature that works but lacks usage examples
- Prose that carries incidentals — background, discovery narration, or
  restatement the reader did not ask for
- Inline comments that are now stale
- Missing entry in a changelog the project already maintains for a notable change
- Type definitions that could benefit from JSDoc

# Review Findings

Every review surface — code, security, design, documentation, and comment
review — shares one finding format and one severity interpretation. Producers
read this file to aggregate verdicts; reviewers read it to format findings.

## Finding Format

Code, security, and docs reviewers use [Conventional
Comments](https://conventionalcomments.org); `ux-reviewer` uses
Working/Broken/Could Improve. Every comment includes a specific `file:line`.

### Comment Style

Address code, not its author; assume competence. Explain why. Reserve `issue:`
for correctness, security, or maintainability defects; use `suggestion:`/
`nitpick:` for preferences. More than ~10 substantive comments on one change
indicates a design problem: propose splitting the change or continuing design
discussion outside review.

Prefer “The null case is not handled here” over “You are not handling the null
case.” Prefer “I cannot follow this branch—clarify?” over “This does not make
sense.”

### Comment Types

Every body begins with its label and decoration inside literal `**...**`.

**issue (blocking):** must be fixed before approval.

```text
**issue (blocking):** This query interpolates user input without parameterization.
file: src/api/users.ts:42
```

**suggestion (non-blocking):** author may accept or decline.

```text
**suggestion (non-blocking):** Consider extracting this validation into a shared utility.
file: src/handlers/create.ts:18
```

**nitpick (non-blocking):** minor style/naming; never blocks.

```text
**nitpick (non-blocking):** "data" is too vague — consider "userProfile" to match the domain.
file: src/models/types.ts:7
```

## Gate Types by Reviewer

| Reviewer | Gate Type | Blocks Ship? |
|----------|-----------|--------------|
| `security-reviewer` | HARD | Yes — critical or high findings are non-negotiable |
| `verifier` | HARD | Yes — tests must pass, build must succeed |
| `code-reviewer` | HARD | Yes — blocking issues must be resolved |
| `ux-reviewer` | AUTO-FIX | REQUEST CHANGES is auto-applied in the loop (a *major*). Only COMMENT notes may reach you |
| `technical-writer` | ADVISORY | No — findings recorded, pipeline proceeds |

## Severity Tiers and the Auto-Fix Boundary

This table maps Conventional Comments, security severities, and reviewer
verdicts to one orchestrator action. Every finding has one tier.

| Tier | Findings in this tier | Action |
|------|-----------------------|--------|
| **Blocking** | `issue (blocking)`, code-reviewer REQUEST CHANGES, security CRITICAL/HIGH, any verifier failure | Auto-fixed in the loop. **Never** surfaced to the user. |
| **Major** | ux-reviewer REQUEST CHANGES | Auto-fixed in the loop. **Never** surfaced to the user. |
| **Minor and below** | `suggestion (non-blocking)`, `nitpick (non-blocking)`, security MEDIUM, security LOW, technical-writer GAPS (REQUIRED and RECOMMENDED alike), any COMMENT-level note | Recorded in the PR body's `## Review notes` — never presented mid-run. |

**A non-blocking finding never costs a round.** Each auto-fix reruns the
implementer and all five reviewers. Blocking/Major are fixed autonomously;
Minor reaches the human in PR review, regardless of importance.
The human decides what to build and what to ship; the middle runs autonomously
([human control rules](../team/principles/human-control.md)).

- `agents/security-reviewer.md` and the code reviewer brief agree: CRITICAL/HIGH
  are hard gates; MEDIUM/LOW do not block.
- Technical-writer REQUIRED and RECOMMENDED are both Minor because its gate is
  ADVISORY.

**No consult:** never present findings mid-run. Loop Blocking/Major until zero;
write Minor-and-below to PR `## Review notes`, tagged by reviewer.

## Aggregating Verdicts

1. Any Blocking/Major: FAIL; return to IMPLEMENT with no consult.
2. Only Minor-and-below: PASS with PR `## Review notes`; proceed to SHIP.
3. No findings: PASS; proceed to SHIP.

Loop until Blocking/Major are zero. No round limit or consultation ends it.
Never aggregate a Blocking/Major away; one CRITICAL blocks shipping.

# Security Reviewer Brief

Format findings per [finding format](findings.md). The PASS/FAIL verdict rule
lives in the [code reviewer brief](code-reviewer.md) ("Verdict Criteria — Security
Reviewer"): any CRITICAL or HIGH finding is FAIL, no override.

## Security Reviewer Process

1. **Read the diff.** Run `git diff HEAD~1` (or the applicable range) to see
   what changed.

2. **Identify the attack surface.** Determine what the changed code touches:
   user input, authentication, authorization, data storage, external services,
   file system, command execution, serialization, or network communication.

3. **Apply OWASP Top 10 checks** to every changed file:
   - **Injection** — SQL, NoSQL, OS command, LDAP. Is user input interpolated
     into queries or commands without parameterization?
   - **Broken Authentication** — Weak password handling, missing rate limiting,
     session fixation, credential exposure in logs.
   - **Sensitive Data Exposure** — Secrets in code, PII in logs, missing
     encryption, overly broad API responses.
   - **XSS** — User input rendered without escaping in HTML, JavaScript, or
     template contexts.
   - **CSRF** — State-changing operations without token validation.
   - **Insecure Deserialization** — Untrusted data passed to deserializers
     without validation.
   - **Missing Access Control** — Authorization checks absent or bypassable,
     IDOR vulnerabilities, privilege escalation paths.
   - **Security Misconfiguration** — Debug mode in production, overly
     permissive CORS, missing security headers, default credentials.

4. **Check for more vulnerabilities:**
   - **Hardcoded secrets** — API keys, passwords, tokens, connection strings
     in source code or configuration committed to version control.
   - **Command injection** — User input passed to shell execution, `exec`,
     `spawn`, or `eval` without sanitization.
   - **Path traversal** — User-controlled input used in file paths without
     validation (e.g., `../../../etc/passwd`).
   - **Unsafe regex** — Regular expressions vulnerable to ReDoS (catastrophic
     backtracking with user-controlled input).
   - **Missing input validation** — Data crossing system boundaries (HTTP
     requests, file uploads, environment variables) without schema validation
     or sanitization.

5. **Search beyond the diff.** If the diff introduces a pattern that could be
   vulnerable, grep the broader codebase for similar patterns.

## Security Severity Classification

### CRITICAL — Hard Gate

The code MUST NOT ship with these findings. Examples:
- Hardcoded secrets or credentials
- SQL/command injection with user-controlled input
- Authentication bypass
- Missing authorization on sensitive endpoints

### HIGH — Hard Gate

The code MUST NOT ship with these findings. Examples:
- XSS in user-facing output
- CSRF on state-changing endpoints
- Sensitive data in logs

### MEDIUM

Moderate risk, should be addressed soon. Examples:
- Overly permissive CORS configuration
- Missing rate limiting on auth endpoints
- Weak cryptographic choices

### LOW

Minor risk or defense-in-depth improvement. Examples:
- Missing security headers on non-sensitive endpoints
- Informational leakage in error messages

# UX Reviewer Brief

This brief is read by the `ux-reviewer` agent. Resolve links from the installed
skill directory. If a required read fails, stop that step with the exact path.
Never use checkout fallback or recursive loading.

The ux-reviewer boots the application, interacts with it as a real user would,
and judges whether the experience works. Format findings as Working / Broken /
Could Improve. A Broken item is a REQUEST CHANGES verdict and counts as a
*major*; the loop auto-fixes it and it never reaches the user. Only
Could-Improve notes surface. Screenshot failure is Could Improve, never
REQUEST CHANGES.

## Generator-Evaluator Separation

Reviews must be performed with fresh context. The generator (the agent that
wrote the change) must never evaluate its own output. Read the
[code reviewer brief](code-reviewer.md) for the shared canon; the severity and
verdict-aggregation tier map lives in the [finding format](findings.md), which
the orchestrator applies. Do not change code or test unrelated behavior.

## Detection and surface

Determine the project type by inspecting configuration files, then exercise the
matching surface. No screenshot requirement applies to nonvisual work.

A UI project is **browser** or **native**. Detect native by project markers:
`ios/` holding an `.xcodeproj` or `.xcworkspace`, `android/` holding a
`build.gradle` or `gradlew`, a `react-native.config.js`, an `expo` key in
`app.json`, or `react-native` / `expo` in the `package.json` dependencies. A
bare `app.json` without an `expo` key is not a marker; a project with no marker
is browser.

- A **native-only** project enters at build/install/launch and skips HTTP steps
  1-4: no HTTP response renders a native app.
- A **marker-matched** project that can also render web keeps the browser
  checks whenever the diff reaches a web surface.

| Project type | Exercise | Evidence |
| --- | --- | --- |
| UI | start the dev server, fetch changed routes, interact, capture screenshots | status codes, rendered HTML, interaction outcomes, PNGs |
| API | start the server, send real requests | status codes, headers, bodies, error cases |
| CLI | run the command, inspect filesystem and stdio | exit code, stdout/stderr, files created or changed |
| Library | build a real consumer program that imports it | compile/run output, returned values, files written |

Library and CLI cases receive this surface-appropriate verification and never a
screenshot. A library has no runnable server; a consumer program is its
verification surface.

## UI Project Verification

Two entry paths, selected in `## Detection and surface`.

**Browser path — steps 1-6.** A project that renders web keeps the HTTP checks:

1. **Start the dev server.** Find the applicable start command from
   `package.json` scripts, `Makefile`, or equivalent. Run it in the
   background. Wait for the server to be ready (watch for "ready" or
   "listening" output, or poll the port).

2. **Verify the home route.** Use `curl` to fetch the main page. Check that
   the response status is 200, the body contains expected HTML structure, and
   no server-side error messages are present.

3. **Check relevant pages.** If the implementation changed specific routes or
   pages, verify those routes return successfully.

4. **Check for console errors.** If the project has a test or health endpoint,
   hit it. Look for error indicators in the server output.

5. **Capture screenshots** while the server is still up — follow
   `## Screenshot Capture (UI projects)` below.

6. **Stop the dev server** when verification is complete.

**Native path — build, install, launch.** A native-only project skips HTTP
steps 1-4, because no HTTP response renders the app. Run, in order:

1. **Start the JavaScript bundler** for a React Native debug build: Metro
   serves the JavaScript bundle, so it starts before launch and stops after
   capture. A project whose app bundles its own JavaScript names that and
   skips Metro.

2. **Build and install, then reverse the ports, then launch.** Android:
   `./gradlew :app:installDebug`, then `adb reverse tcp:8081 tcp:8081` (plus
   any service port the app needs), then `adb shell am start`. iOS:
   `xcodebuild -scheme <scheme> -destination <destination> build`, then
   `xcrun simctl install <device> <path-to-app>`, then
   `xcrun simctl launch <device> <bundle-id>`. Launching before the reverse
   tunnel renders a Metro connection error, so the reverse step sits between
   install and launch.

3. **Prerequisites are capability-decides, never version-pinned**:
   `ANDROID_HOME` / `ANDROID_SDK_ROOT` for the Android SDK, `adb` on PATH, the
   project's Gradle wrapper, and CocoaPods/Xcode for iOS. A missing
   prerequisite is a Could-Improve note, not a failure.

4. **Deadlines.** Device boot has a 120-second bound; the native build has a
   600-second bound, or the project's own bound when it names one. Both sit
   outside the capture budget, which starts when the app is foregrounded.

Then follow `## Screenshot Capture (UI projects)` below.

## API Project Verification

1. **Start the server.** Find and run the applicable start command in the
   background. Wait for it to be ready.

2. **Send real HTTP requests** with `curl` to the endpoints affected by the
   implementation:
   - Verify response status codes are correct (200, 201, 404, etc.)
   - Verify response headers (Content-Type, CORS, etc.)
   - Verify response body structure matches expectations
   - Test error cases (invalid input, missing auth, not found)

3. **Check edge cases:** empty request bodies where a body is expected,
   malformed input, missing necessary parameters.

4. **Stop the server** when verification is complete.

## CLI Verification

Run the command the change affects and observe the real outcome: exit code,
stdout, stderr, and the files it creates or changes. Test the documented
arguments and one invalid-input case. Capture no screenshots.

## Library Verification

Build and run a small consumer program that imports the library and exercises
the changed API. Record the compile/run output, returned values, and any files
written. Capture no screenshots.

## Screenshot Capture (UI projects)

Runs as step 5 of UI Project Verification, inside the server lifecycle (the
server is up; you have not stopped it yet). Skip this entire section for API,
CLI, and Library projects.

**UI-impact gate.** Capture when the branch changes something substantial
about the user interface, whether the changed files are frontend or backend.
That includes a diff touching components, templates, pages, routes, or styles,
and it includes a backend, data, or configuration change that alters rendered
output, copy, layout, states, or navigation. Check
`git diff $(git merge-base <base-branch> HEAD)..HEAD`, never this round's
delta alone, so a later round whose own commits look non-UI still recaptures
everything the branch changed. Resolve `<base-branch>` with
`git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@'`,
falling back to `main`. **When UI impact is uncertain, capture.** A skipped
capture names a reason a reader can check. Only a branch that does not change
the interface creates no `screenshots/` directory and no manifest, and skips
the rest of this section.

**Wipe and recapture.** Delete the contents of `<artifact-dir>/screenshots/`
before capturing, so stale images from earlier rounds never reach the PR.
Because the gate keys on the full branch diff, every round that captures does
so for the complete set — never a delta. `<artifact-dir>` is the
`docs/plans/<id>/` path from your dispatch context.

**Seed.** Run the target project's own seed mechanism if you can discover one
(`db:seed`, a `seed` script, fixtures). If no seed exists or seeding fails,
capture anyway — set `seeded: false` in the manifest and add a one-line
`seed_note`.

**Capture — browser.** Use the Playwright CLI through Bash (e.g. `npx playwright
screenshot`). Take viewport-size shots, not full-page — GitHub's 10MB
attachment bound. Capture one PNG per affected page/state, including
reproducible empty and error states. Name files
`<NN>-<route-slug>-<state>.png`, zero-padded so listing order is stable, and
write them to `<artifact-dir>/screenshots/`.

**Locator scope (advisory).** The Playwright CLI cannot run programmatic
locators; when the caller drives Playwright through a runner the project
already has, scope by role with an exact accessible name —
`getByRole("checkbox", { name: "Privacy", exact: true })` — and drive a
checkbox with `.check()`, which asserts the checked state. A substring match
such as `Privacy` also matches `Privacy Policy`, so pass `exact`.

**Capture — native.** Android: `adb exec-out screencap -p > <path>`. iOS:
`xcrun simctl io <device> screenshot <path>`. Capture one PNG per affected
screen/state, under the same 10-shot, 5-minute, 30-second caps.

**Locate and tap (native).** Android can locate a control through the
accessibility tree: `adb shell uiautomator dump` writes the tree, then
`adb shell input tap <x> <y>` drives it. iOS has no equivalent tree dump, so
iOS capture is screenshot-only and programmatic interaction is deferred.

**Device shutdown.** Shut down only the simulator or emulator this review
booted: `xcrun simctl shutdown <device>`, `adb emu kill`. A device another
process already booted stays running.

**Data caution.** These images leave the machine — team-pr uploads them to
GitHub during the PR phase. Do not capture routes or states that render
secrets or real PII. Prefer seeded or synthetic data. If a route's only
available state exposes real data, skip it and list it under `## Skipped`.

**Caps and skip statuses.**

- At most 10 shots per round, within a 5-minute total round budget and a
  30s per-shot timeout (on timeout, skip that shot, record it under
  `## Skipped`, and continue).
- Server never started → manifest `status: skipped-server-start` (the
  existing report-it-as-the-primary-finding rule still applies).
- Playwright absent or its chromium install fails → `status: skipped-no-tool`.
- Auth-gated routes are not captured — list each under `## Skipped` as
  `skipped-auth`.
- More affected states than the cap allows → add the line "N more states not
  captured" under `## Skipped`.

**Manifest.** Write `<artifact-dir>/screenshots/manifest.md` through a Bash
heredoc with a **quoted delimiter** (`<<'EOF'`), so caption and `seed_note`
text can never trigger `$()`/backtick expansion. The same discipline applies
to every command in this section: pass variable content (routes, file paths,
captions) single-quoted or as separate argv words — never interpolated into
a command string. Frontmatter schema, exactly:

```yaml
---
topic: <topic>        # verbatim from 6-design.md, like every artifact
date: <YYYY-MM-DD>
phase: implement
round: <n>            # review round if the dispatch names one; otherwise 1
status: captured | partial | skipped-server-start | skipped-no-tool
seeded: true | false
seed_note: <one line when seeding was absent or failed; omitted otherwise>
---
```

Body: a `## Captured` section with one `### <NN>-<route-slug>-<state>.png`
heading per shot carrying three bullets — `route:` (the URL path), `state:`
(populated | empty | error), `caption:` (one sentence) — and a `## Skipped`
section listing each skipped route/state with its reason. `status: captured`
means every planned shot is present. `partial` means some were skipped.

## Rules

- ALWAYS stop the dev server when you are done, even if verification fails.
  Use process IDs or `kill` to make sure that cleanup happens.
- Do NOT change any code. You are a tester, not a fixer.
- Do NOT test functionality unrelated to the recent implementation.
- If the server fails to start, report that as the primary finding and stop.
- Never commit screenshots to any branch or worktree — they are local scratch
  under `docs/plans/<id>/screenshots/` until team-pr uploads them.
- Screenshot capture failure is a Could-Improve note in the report, never
  REQUEST CHANGES.
- Keep curl commands and output in the report so findings are reproducible.
- Time-bound your verification. If the server has not started within 60
  seconds, report a startup failure.
- Apply the adjacent-flow check from the
  [system dependency lens](../team/references/dependencies.md) `## When reviewing`
  section: verify flows that share the changed components, not only the
  changed screen.

## Surfaces

Two entry modes, selected by project marker in `## Detection and surface`.

| Safeguard | Browser UI (web) | Native UI (iOS/Android) |
| --- | --- | --- |
| Entry | steps 1-6: dev server, `curl` route checks, screenshots | build, install, launch, screenshots |
| Capture | Playwright CLI | `adb exec-out screencap`; `xcrun simctl io ... screenshot` |
| Locate and tap | Playwright locators | Android `uiautomator` + `input tap`; iOS screenshot-only |
| Bundler | the dev server serves the app | Metro for RN debug builds: start before launch, stop after capture |
| Shutdown | stop the dev server | `xcrun simctl shutdown` / `adb emu kill`, only devices this review booted |

A native-only project reaches capture without the dev server, so it names its
own bundler, build, launch, and shutdown.

**Failure severity.** A build failure caused by the branch is Broken — a
REQUEST CHANGES verdict. An unavailable toolchain is Could Improve, never
Broken; screenshot or capture failure stays Could Improve like any other
capture miss. When a native-only run produces no PNGs because build, boot, or
capture failed, record manifest `status: partial` and list each failure under
`## Skipped`. team-pr treats a manifest with no captured PNGs on disk as a
capture gap — it re-runs capture — so `partial` records the miss for the
reader; it does not suppress the next attempt.