Review Code

---
name: review-code
description: Standalone code review for any scope — PR number, branch, file paths, or current changes. Synthesizes intent, runs 11 parallel specialized agents, and presents actionable findings with a verdict. For PR scope, optionally posts the review to GitHub with inline comments.
argument-hint: '[pr number, branch name, file paths, or nothing for current branch]'
allowed-tools: Bash Read Grep Glob
effort: high
model: opus
---

## Step 1: Determine scope

Identify what to review and the exact diff command to pass agents.

| Argument                      | File list                              | Diff command                             |
| ----------------------------- | -------------------------------------- | ---------------------------------------- |
| PR number or URL              | `gh pr diff <n> --name-only`           | `gh pr diff <n>`                         |
| Branch name                   | `git diff <branch>...HEAD --name-only` | `git diff <branch>...HEAD`               |
| File path(s)                  | use provided paths                     | `git diff HEAD -- <files>`               |
| None, on feature branch       | `git diff main...HEAD --name-only`     | `git diff main...HEAD`                   |
| None, on main, staged         | `git diff --staged --name-only`        | `git diff --staged`                      |
| None, on main, nothing staged | —                                      | ask: "What would you like me to review?" |

Substitute the actual base ref (main, master, trunk) where needed. Detect the current branch with `git symbolic-ref --short HEAD`.

**Skip non-reviewable files:**

- package-lock.json, \*.lock, yarn.lock, Gemfile.lock
- Generated code (_.generated._, \*\_pb2.py, etc.)
- Test snapshots (**snapshots**/\*)
- Vendored dependencies (vendor/, node_modules/ if committed)
- Binary files
- Formatting-only changes (whitespace/style only)

**For PR scope — fetch PR context before Step 2:**

```bash
gh pr view <n> --json title,body,number
```

Store the title and body for use in Step 2. Store the PR number for Step 5.

Output the reviewable file list and diff command before proceeding.

## Step 2: Synthesize intent

Build a context block that every agent receives. Gather from these sources in priority order:

1. **PR title and body** — from Step 1 fetch (if PR scope)
2. **Linked issues** — if the PR body references issue numbers, fetch with `gh issue view <n>`
3. **Commit messages** — `git log <base>...HEAD --format="%s%n%b"`
4. **The diff itself** — read for intent when other sources are thin

Synthesize into a single crisp block:

```
Problem: [what's broken, missing, or needed — and why it matters]
Approach: [how this change addresses it, at a high level]
Key outcomes: [invariants, constraints, or requirements the implementation must satisfy]
Diff command: [exact command agents should run to read the diff]
```

Enhance if needed: if raw sources are vague, read the diff and fill in the gaps. Never leave this block generic ("various improvements") or empty.

## Step 3: Launch the agents in parallel

The eleven agents below always run. You may add more in the same fan-out when this particular
change raises a question none of the eleven prompts ask.

The bar is a named question, not a topic. "Add a concurrency agent" is a topic. "Does the new
retry path double-submit when the first attempt times out after the server committed?" is a
question, and it earns an agent. If you cannot write the question down, do not add the agent.

Add rather than enrich. Each agent returns 200 words and its top 3 findings, so appending a
concern to an existing agent's prompt does not add coverage — it pushes that agent's fourth
finding off the list. A new agent brings its own budget.

Give an added agent the same shape as the eleven: the intent block, the file list, the provenance
requirement, a word limit, and one question to answer. Record the question and why the eleven did
not cover it — Step 4 reports it.

Send a single message containing all Agent tool calls simultaneously. For each Agent tool call, set the tool's `model` parameter to `"sonnet"`. Pass each agent:

- The synthesized intent block from Step 2
- The list of changed/reviewable files
- Its specific instructions below
- This provenance requirement, verbatim:

  > For every finding, state whether the change under review **introduced** it or whether it is
  > **pre-existing** — already true on the base ref before this change. Decide it mechanically,
  > not by impression: run `git show <base-ref>:<path>` (or `git log -S '<the exact line>'`) and
  > say which you ran. A line that appears in the diff as unchanged context is pre-existing even
  > when it sits inside a function the change rewrote. Label each finding `[introduced]` or
  > `[pre-existing]`. If you cannot determine it, say `[provenance unknown]` rather than guessing.

---

### Agent 1: Intent Alignment

```
Question: Does the implementation actually achieve the stated intent of this change?

**Return findings in 200 words or fewer. Report your top 3 issues only, ordered by severity. If nothing found, say so in one sentence.**

Context:
[insert synthesized intent block]

Changed files:
[insert file list]

Instructions:
1. Read `~/.agents/standards/README.md`, then `~/.agents/standards/correctness.md`. Use these standards as your evaluation criteria.
2. Run the diff command from Context to read what changed.
3. Compare the diff carefully against the Problem, Approach, and Key outcomes in the Context block.

Look for gaps between stated intent and actual implementation:
- Does the code fully address the stated problem, or only partially?
- Are there stated outcomes not implemented or only half-implemented?
- Are there edge cases implied by the problem statement that the implementation ignores?
- Are there implicit requirements from the problem domain that the implementation misses, even if not explicitly stated?

Also check for drift:
- Does the code do things unrelated to the stated intent? (scope creep, unrelated refactoring bundled in)
- Are commit messages consistent with what the diff actually changes?

For each gap: what the stated intent says | what the implementation actually does | what's missing or misaligned
If implementation matches intent: report "Implementation aligns with stated intent."
```

---

### Agent 2: Approach

```
Question: Is this the simplest correct solution to the stated problem, and is it the best available approach?

**Return findings in 200 words or fewer. Report your top 3 issues only, ordered by severity. If nothing found, say so in one sentence.**

Context:
[insert synthesized intent block]

Changed files:
[insert file list]

Instructions:
1. Read `~/.agents/standards/README.md`, then `~/.agents/standards/code-readability.md` and `~/.agents/standards/code-structure.md`. Use these standards as your evaluation criteria.
2. Search for project docs defining standards or preferences (README.md, CONTRIBUTING.md, docs/, style guides) — CLAUDE.md is already loaded. Use them to inform your review.
3. Run the diff command from Context to read what changed.
4. Read related unchanged files and explore the broader codebase to understand existing patterns and available tools.

Simplicity check — ask this first:
What is the minimum code that correctly solves the stated problem? Compare it to what was written. If the answer is substantially less, that gap is the most important finding. Look for:
- Abstractions for a single call site, or layers that exist for one use case
- Problems being solved that were never stated — hypothetical future requirements, speculative flexibility
- Existing utilities, patterns, or libraries in the project or standard library that would make this trivial
- Complexity whose justification isn't obvious to a competent reader of the problem statement

Ground every observation in the actual code and the problem being solved. Don't flag superficial rewrites.

If a simpler or better approach exists: describe it concretely, explain what makes it better, and note the cost of switching.
If the approach is well-chosen: report "Approach is well-suited to the problem."
```

---

### Agent 3: Structure

```
Question: Is the internal organisation of this code sound?

**Return findings in 200 words or fewer. Report your top 3 issues only, ordered by severity. If nothing found, say so in one sentence.**

Context:
[insert synthesized intent block]

Changed files:
[insert file list]

Instructions:
1. Read `~/.agents/standards/README.md`, then `~/.agents/standards/code-structure.md` and `~/.agents/standards/code-readability.md`. Use these standards as your evaluation criteria.
2. Search for project docs defining standards or preferences (README.md, CONTRIBUTING.md, docs/, style guides) — CLAUDE.md is already loaded. Use them to inform your review.
3. Run the diff command from Context to read what changed.
4. Read related unchanged files to understand existing structural patterns and conventions.

For each issue: file:line | what's wrong | specific alternative
If structure is sound, report "Structure and internal organisation look solid."
```

---

### Agent 4: Public Surface

```
Question: From the caller's perspective, is this code well-designed and discoverable?

**Return findings in 200 words or fewer. Report your top 3 issues only, ordered by severity. If nothing found, say so in one sentence.**

Context:
[insert synthesized intent block]

Changed files:
[insert file list]

Instructions:
1. Read `~/.agents/standards/README.md`, then `~/.agents/standards/type-design.md`, `~/.agents/standards/api-design.md`, and `~/.agents/standards/documentation.md`. If the project has a CLI binary or command-line interface, also load `~/.agents/standards/cli-design.md`. Use these standards as your evaluation criteria.
2. Search for project docs defining standards or preferences (README.md, CONTRIBUTING.md, docs/, style guides) — CLAUDE.md is already loaded. Use them to inform your review.
3. Run the diff command from Context to read what changed.
4. Find all documentation that could be affected: .md files, help text, docstrings, CLI --help output, code comments in changed files.

Types & interfaces:

API & CLI design:

Documentation:

For each issue: file:line | what's wrong | specific fix
If the public surface is well-designed and documented, report "Public surface is well-designed and documented."
```

---

### Agent 5: Correctness

```
Question: Does this code behave correctly across all inputs, states, and callers?

**Return findings in 200 words or fewer. Report your top 3 issues only, ordered by severity. If nothing found, say so in one sentence.**

Context:
[insert synthesized intent block]

Changed files:
[insert file list]

Instructions:
1. Read `~/.agents/standards/README.md`, then `~/.agents/standards/correctness.md` and `~/.agents/standards/error-handling.md`. Use these standards as your evaluation criteria.
2. Search for project docs defining standards or preferences (README.md, CONTRIBUTING.md, docs/, style guides) — CLAUDE.md is already loaded. Use them to inform your review.
3. Run the diff command from Context to read what changed. For files under 500 lines, read the full file. For larger files, read each changed section plus ~30 lines of context.
4. Read 2-3 similar unchanged files to understand existing patterns for error handling and validation.

For each issue: file:line | what's wrong | concrete impact | specific fix
Skip theoretical what-ifs — report actual problems in the code.
```

---

### Agent 6: Data Safety

```
Question: Is data protected from external threats, personal data mishandling, and write-time corruption?

**Return findings in 200 words or fewer. Report your top 3 issues only, ordered by severity. If nothing found, say so in one sentence.**

Context:
[insert synthesized intent block]

Changed files:
[insert file list]

Instructions:
1. Read `~/.agents/standards/README.md`, then `~/.agents/standards/security.md`, `~/.agents/standards/privacy.md`, and `~/.agents/standards/data-integrity.md`. Use these standards as your evaluation criteria.
2. Search for project docs defining standards or preferences (README.md, CONTRIBUTING.md, docs/, style guides) — CLAUDE.md is already loaded. Use them to inform your review.
3. Run the diff command from Context to read what changed, then read surrounding context.
4. If database models or migrations changed, read them in full.

Security:

Privacy:

Data integrity:

For each issue: file:line | what's wrong | severity (Critical/High/Medium/Low) | specific fix
Only report actual violations, not theoretical what-ifs.
If no concerns found, report "No data safety concerns identified."
```

---

### Agent 7: Runtime Behaviour

```
Question: How does this code behave under real-world conditions — load, failure, and concurrency?

**Return findings in 200 words or fewer. Report your top 3 issues only, ordered by severity. If nothing found, say so in one sentence.**

Context:
[insert synthesized intent block]

Changed files:
[insert file list]

Instructions:
1. Read `~/.agents/standards/README.md`, then `~/.agents/standards/performance.md`, `~/.agents/standards/async-coordination.md`, `~/.agents/standards/reliability.md`, `~/.agents/standards/observability.md`, and `~/.agents/standards/instrumentation.md`. Use these standards as your evaluation criteria.
2. Search for project docs defining standards or preferences (README.md, CONTRIBUTING.md, docs/, style guides) — CLAUDE.md is already loaded. Use them to inform your review.
3. Run the diff command from Context to read what changed, then read surrounding context.
4. Check how similar operations are handled in unchanged files.

Performance:

Concurrency:

Reliability:

Observability:
- If this fails in production, would we know? Is the failure diagnosable from logs alone?

For each issue: file:line | what's wrong | concrete impact | specific fix
Only report actual problems, not theoretical micro-optimizations.
If no concerns found, report "No runtime behaviour concerns identified."
```

---

### Agent 8: Testing

```
Question: Is the test suite trustworthy and sufficient to catch regressions in this change?

**Return findings in 200 words or fewer. Report your top 3 issues only, ordered by severity. If nothing found, say so in one sentence.**

Context:
[insert synthesized intent block]

Changed files:
[insert file list]

Instructions:
1. Read `~/.agents/standards/README.md`, then `~/.agents/standards/testing.md`. Use these standards as your evaluation criteria.
2. Search for project docs defining standards or preferences (README.md, CONTRIBUTING.md, docs/, style guides) — CLAUDE.md is already loaded. Use them to inform your review.
3. Run the diff command from Context to read what changed.
4. Find and read the corresponding test files (new and existing).
5. Read 2-3 existing test files to understand the project's test conventions and style.

Coverage:
- Are critical paths tested? (auth, payments, data integrity, error paths)
- Specify exact missing cases: not "add tests" but "add tests for: expired token, missing token, wrong signature"

For each issue: file:line | what's wrong | specific fix
If tests are well-designed, report "Test design is solid and coverage is appropriate."
```

---

### Agent 9: Release Readiness

```
Question: Is this change ready to ship responsibly — dependencies justified, deployment safe, config correct?

**Return findings in 200 words or fewer. Report your top 3 issues only, ordered by severity. If nothing found, say so in one sentence.**

Context:
[insert synthesized intent block]

Changed files:
[insert file list]

Instructions:
1. Read `~/.agents/standards/README.md`, then `~/.agents/standards/dependencies.md`, `~/.agents/standards/deployment.md`, and `~/.agents/standards/config.md`. Use these standards as your evaluation criteria.
2. Search for project docs defining standards or preferences (README.md, CONTRIBUTING.md, docs/, style guides) — CLAUDE.md is already loaded. Use them to inform your review.
3. Run the diff command from Context to read what changed.
4. If package files changed, read them in full. If config or env handling changed, read those files in full.

Dependencies (if package files changed):

Deployment safety:

Configuration (if config or env handling changed):

For each issue: file:line | what's wrong | specific recommendation
If no concerns found, report "No release readiness concerns identified."
```

---

### Agent 10: Language

```
Question: Does this code use the language correctly, following the project's established idioms?

**Return findings in 200 words or fewer. Report your top 3 issues only, ordered by severity. If nothing found, say so in one sentence.**

Context:
[insert synthesized intent block]

Changed files:
[insert file list]

Instructions:
1. Identify which programming languages are present in the changed files by file extension (`.rs` → Rust, `.py` → Python, `.ts`/`.tsx` → TypeScript).
2. Read `~/.agents/standards/README.md`, then load only the reference files that apply: `~/.agents/standards/rust.md` if Rust files are present, `~/.agents/standards/python.md` if Python files are present, `~/.agents/standards/typescript.md` if TypeScript files are present.
3. If no language-specific reference files apply to the changed files, report "No language-specific reference files apply to this change." and stop.
4. Otherwise, run the diff command from Context to read what changed.

Apply the loaded standards to the changed files. Look for violations specific to the language — idioms, error handling patterns, type system conventions, and anti-patterns called out in the standards files.

For each issue: file:line | what's wrong | specific fix
If no language-specific issues found, report "No language-specific concerns identified."
```

---

### Agent 11: Failure Paths

```
Question: For each failure path this change adds or moves — a throw, a non-zero exit, an error return, a new branch that gives up — is it reachable from the program's real entry point, and when it fires, what does the process observably do?

**Return findings in 250 words or fewer. Answer the question path by path first, then report your top 3 issues ordered by severity. If the change adds no failure path, say so in one sentence and stop.**

Context:
[insert synthesized intent block]

Changed files:
[insert file list]

Instructions:
1. Read `~/.agents/standards/README.md`, then `~/.agents/standards/error-handling.md`, `~/.agents/standards/reliability.md`, `~/.agents/standards/observability.md`, `~/.agents/standards/instrumentation.md`, and `~/.agents/standards/async-coordination.md`. Use these as your evaluation criteria.
2. Run the diff command from Context. List every failure path the diff adds or relocates. A path that merely changes its message is not one; a path that changes when, whether, or how loudly it fires is.
3. For each path, find the program's real entry point (the binary, the `main`, the script the scheduler runs, the handler the framework calls) and trace whether anything reachable from it reaches that path. Grep for importers of the module, then importers of those. Say plainly when nothing does: an unreachable failure path protects nothing, however correct it looks.
4. For each reachable path, read the enclosing function IN FULL plus its callers, and determine what actually happens when it fires. Name the observable outcome: exit code, what appears in logs, and whether remaining work continues, is skipped, or is silently reported as success.
5. Check specifically for handlers that do not catch what they look like they catch: a synchronous throw evaluated while building an argument, before the promise/future it is passed to exists; a throw in a constructor or at module load; an error raised outside the `try` that visually surrounds it; a rejected promise nothing awaits.
6. Judge each outcome against the intent block. A change whose stated point is failing earlier or louder has not delivered it if the failure is caught and logged deep in the stack, or if the process still exits 0.

For each issue: file:line | the path | reachable from where, or not at all | what the process actually does | why that is wrong given the intent
```

---

## Step 3.5: Verify before presenting

Before writing a single line of output, audit the agent findings for claims that assert specific library behavior, numerical values, runtime semantics, or API guarantees. These are the highest-risk claims — most likely to be subtly wrong — and the ones a reviewer would have to take on faith.

**For each such claim, run a targeted check:**

- Library default values → `python3 -c "import lib; print(lib.DEFAULT_X)"`
- API signature or accepted kwargs → `python3 -c "import inspect, lib; print(inspect.signature(lib.Cls.method))"`
- Stdlib availability → `python3 -c "import lib; print(hasattr(lib, 'func'))"`
- Source behavior → read the relevant installed source with `python3 -c "import inspect, lib; print(inspect.getsource(lib.func))"`
- File/doc claims → read the file

**Apply the results:**

- Strike claims that don't survive the check — remove them entirely, don't soften them.
- Correct claims that are partially right — state what's actually true.
- Merge duplicate findings — when multiple agents flag the same issue, keep the most precise version and note the convergence.
- Drop findings you cannot verify and that are speculative rather than grounded in the diff.

Only carry verified findings into Step 4.

## Step 4: Present findings

Produce a prioritized action list — not a categorized findings report. The reader's question is "what should I change?" Answer it directly.

```
## Code Review

### Verdict: [Approve | Request Changes | Comment]
[One sentence on what to do next]

### Findings

| # | Severity | Location | Action |
|---|----------|----------|--------|
| 1 | must | `file:line` | [imperative: what to do] |
| 2 | should | `file:line` | [imperative: what to do] |
| 3 | consider | `file:line` | [imperative: what to do] |
| 4 | ? | `file:line` | [open design question] |

---

**1. `file:line` — [imperative: what to do]** *(must)*

[1–3 sentences. Explain why this matters — what breaks, degrades, or becomes harder if left unfixed. Then describe what work you did to verify the claim: which file or function you read, which command you ran, what the output showed. Use hedging language ("no guard visible in the surrounding context", "appears to", "may") if confidence is less than certain.]

**2. `file:line` — [imperative: what to do]**

[Same structure. Cite the specific code or source that grounds the finding. If you ran a command to verify a library behavior or default value, say so and include the result.]

**4. `file:line` — [open design question]**

- (a) [one path and its tradeoff]
- (b) [another path and its tradeoff]

### Added agents
[Omit this section entirely if you added none.]

- **[the question you added it to answer]** — Why the eleven did not cover it: [reason] — What it
  found: [finding, or "nothing"]

**Generalisable?** [One of: this was specific to this change, nothing to close. | This is a
category — [what recurs] — close it by [adding a standing 11th agent for X / adding a standard to
`~/.agents/standards/<file>.md` saying Y / both].]

### Looks Good
[One sentence: what the change gets right, or which concern areas came back clean.]
```

**Formatting rules:**

- The table is a scannable index only — one row per finding, action phrased as an imperative.
- Severity column values: `must`, `should`, `consider`, `?` (open question). Order rows by severity.
- Each detail section is 1–3 sentences of integrated prose — no labeled sub-fields. It must answer two questions: (1) why does this matter, and (2) what did you actually look at to verify it. These are not optional; a finding with no impact explanation or no verification basis should not be reported.
- Use hedging language within the prose when confidence is less than certain — don't assert facts you haven't confirmed.
- Open question items (`?`) get the (a)/(b) tradeoff format instead of prose.
- Omit "What's Working Well" and "All Clear" sections — consolidate into the single "Looks Good" line.
- If there are no recommended changes, say so in one sentence under the verdict and skip the Findings section.

**Verdict mapping:**

- **Approve** — no blockers; all remaining items are optional
- **Request Changes** — one or more `must` items
- **Comment** — open questions or suggestions worth discussing, nothing blocking

## Step 5: Post review (PR scope only)

After presenting findings, if this is a PR and the author is the user (ooloth), ask the user to
indicate which changes to make locally or discuss further first and then stop and wait for a reply
(skip the rest of this skill's instructions).

Otherwise, if this is a PR and the author is NOT the user, ask:

> "Post this as a GitHub review? (yes / approve / request-changes / comment / skip)"

**Authorization gate:** Only proceed if the user explicitly answers this question with yes, approve,
request-changes, comment, or skip. Do NOT infer authorization from numbered responses to
individual findings (e.g., "(1) do it" answers finding #1, not this question). Wait for a
separate, unambiguous reply to the posting question before posting anything to GitHub.

On any answer other than "skip":

- Map to GitHub event: yes → use verdict from Step 4; approve → APPROVE;
  request-changes → REQUEST_CHANGES; comment → COMMENT
- Write a 2–3 sentence overall summary for the review body (see audience guidance below)
- Collect every finding that has a `file:line` reference as an inline comment
- Get the PR's head commit, so the comments stay pinned to the code you reviewed:
  `gh pr view <pr-number> -R <owner>/<repo> --json headRefOid -q .headRefOid`
- Write the review to a JSON file in the scratchpad with the **Write tool**. Never build it with a
  shell heredoc, `echo`, or command-line arguments: the shell rewrites backticks, `$(...)` and
  quotes, and a mangled review cannot be un-posted. `line` is the line number in the PR's version
  of the file; `side` is `RIGHT` for those and `LEFT` only for a line the PR deletes.

```json
{
  "event": "APPROVE",
  "body": "<summary>",
  "commit_id": "<head SHA>",
  "comments": [
    { "path": "<file>", "line": 42, "side": "RIGHT", "body": "<comment>" }
  ]
}
```

- Dry-run it and read the output. It prints the exact payload that would be sent. Check that every
  body reads as intended and every `path`/`line` points where you meant; fix the file and dry-run
  again until it does:

```bash
uv run <skill-base-dir>/scripts/post_review.py <pr-number> <review.json> --repo <owner>/<repo> --dry-run
```

- Post it by running the same command without `--dry-run`. `--repo` is required, so the review
  cannot land on a same-numbered PR in whatever repo the shell is in.

**Summary audience:** The review body is read by GitHub users who only know what's in the PR diff — they have no context from this review session. Write for that audience:

**Tone for inline comment bodies:** Write like a person talking to a teammate, not a report
generator. Approach it the way a mentor invested in someone's growth would: patient, curious, and
specific, not grading their work. Avoid em dashes; they're one of the more obvious signs a
comment was generated rather than typed by a person.

Structure: most of the time, ask your question first, then a line break, then why you're asking
it. Don't make someone guess what prompted the question. Say what you noticed right after you ask.
This two-part shape is the default, not a rule to force every time; when the ask and the reason
fit naturally into one sentence, say it in one sentence rather than manufacturing a line break
that isn't earning its place.

Asking something you already have a strong idea about is fine, as long as the question genuinely
invites them into the reasoning: their intent, an edge case, a judgment call. What's not fine is
replaying a fact you've already fully nailed down as if it were still open. If you've proven
something and there's nothing left to discover, skip the question. Say what you found and ask
for the fix.

How direct to be depends on what's at stake:

- Going to break something, and you're sure? Ask for the fix directly, then say what you found.
  "Can you add a check for the empty queue here? / This throws in production when the queue's
  empty. I traced it to line 40."
- Have an opinion but nothing's actually wrong? Ask if they want the change, then say why, and
  make clear it's optional. "Want to pull this into a shared helper? / It's the same fixture as
  `test_x.py:40`, not a big deal either way."
- Real choice, no clear right answer? Ask which way they'd rather go, then lay out what's
  different. "Did you consider clearing the audit stamp on revert instead of keeping it? /
  Keeping it preserves who reverted; clearing it treats the row as fresh."
- Don't know why something was done a certain way? Ask if it was on purpose, then say what looked
  off. "Was skipping the null check here intentional? / The sibling function has one and this
  doesn't."
- Small, and you don't feel strongly? Skip the question, just mention what you saw.

**Vary the phrasing across a batch.** The phrasings above ("Can you...", "Want to...", "Did you
consider...", "Was... intentional?") illustrate the register for each situation, not a set of
stock openers to cycle through. A real person doesn't open four comments in the same review with
the same three words; reaching for the same opener each time is one of the more obvious tells that
a comment was generated rather than typed. Before posting a batch, scan the first few words of
every comment: if two or more start the same way (especially "Want to..."), rewrite until each one
reads distinctly. A few alternatives per category, just to show the range:

- Sure it breaks, direct fix: "Can you add...", "Mind adding...", "This needs a...", or skip the
  question and phrase the fix as a plain instruction ("Add a check for the empty queue here.").
- Opinion, optional: "Want to...", "Any interest in...", "Worth pulling this into...?", "Thoughts
  on...?", or lead with the observation and land the question after ("This repeats the fixture
  from `test_x.py:40`, worth sharing it?").
- Real design choice: "Did you consider...", "Which way did you lean on...", "Curious why you went
  with X over Y here", "Is X or Y closer to what you want?"
- Unclear intent: "Was this intentional?", "Did you mean to...", "Is this deliberate, or...?",
  "This looked like it might be a slip, was it?"

These are a handful of examples to illustrate the range, not the full menu. Don't ration yourself
to a small rotating set of phrases either, since that just trades one tell for another (a
reviewer who always says "Can you", "Want to", "Did you consider", or "Was this intentional" in
some rotation still reads as generated). Use your own words each time, the way you'd actually say
it out loud to the person sitting next to you. The goal is a batch that reads like one attentive
person moved down the file making distinct, differently-voiced observations, not like a template
applied four times or a fixed phrasebook applied on rotation.

Use a quick example when it makes the impact click, and say something nice when it's earned. When
a code snippet or a suggested fix would make the ask concrete, include it directly in the
comment: quote the line in question, or show the small change you have in mind, rather than
describing it in prose alone.