# Review items

<!-- squads:managed — regenerated by `sq sync`; do not edit by hand. -->
<!-- squads:version:0.5.0 -->

A code review: scope, findings (each with severity + status), and a verdict.

**Lifecycle:** Requested → InReview → ChangesRequested → Approved (+ Rejected)

## Commands

```bash
sq create review "…" --author reviewer
sq review <n> add-finding "…" --severity high
sq review <n> finding <k> update --status Fixed   # transition a finding
sq review <n> status InReview
sq task <n> ref add REV-… --kind addresses
```

## For Paul Reviewer (`reviewer`)

**Enter** — before you act:
- Read the full item dossier: `sq review <n> show --full --comments` (decisions and
  refinements often live in discussion comments, not the body — skipping this is how context
  gets missed).
- read the task/changes under review + the feature's acceptance criteria

**Do:**
- `sq review <n> status InReview`
- log each issue as a finding (`add-finding "…" --severity …`) — the title is a short handle; the full description goes in the finding body (`sq review <n> finding <k> body -m …`)
- drive to a verdict: Approved or ChangesRequested
- use `sq review <n> finding <k> comment` for finding-scoped notes (rationale, verification notes, 'agreed — closing this one') — cross-cutting notes and the final verdict go on the review (see the `squads` skill's comment-scoping convention)

**Hand off:**
- on ChangesRequested, `@<tech>-dev` with the findings
- on Approved, comment the verdict

**Watch for:**
- severity-tag findings honestly; don't approve with open high findings

## For developers

**Enter** — before you act:
- Read the full item dossier: `sq review <n> show --full --comments` (decisions and
  refinements often live in discussion comments, not the body — skipping this is how context
  gets missed).
- read every finding and its severity (`sq review <n> findings`)

**Do:**
- fix each one, then `sq review <n> finding <k> update --status Fixed`
- link the fix task (`sq task <n> ref add REV-… --kind addresses`)
- use `sq review <n> finding <k> comment` when closing a finding with fix rationale — keep the review's main discussion for handoff @mentions (see the `squads` skill's comment-scoping convention)

**Hand off:**
- `@reviewer` once all findings are Fixed, for re-review

**Watch for:**
- don't close findings you didn't actually address

---
The `.md` files are sq-managed — never edit them by hand. Items are addressed as
`sq review <n> <verb>`. Set this item's body with `sq review <n> body
-m "…"` (or `--file`); `--desc` sets only the short summary. Its user stories / subtasks / findings
get their bodies from `sq review <n> <kind> <k> body -m "…"`. Read anything back with
`sq review <n> show --full --comments` (full dossier, including discussion) /
`sq review <n> <kind> <k> show`.
