reviewing-complex-work

Files (5)

• SKILL.md
• openai.yaml · agents/
• claude-code.md · references/
• codex-cli.md · references/
• cursor-agent.md · references/

SKILL.md (first lines)

# Reviewing Complex Work

Self-request at most one independent peer review per agent session. Run it after
self-review and primary validation, while there is still time to correct the
work. Reviews explicitly requested by the user are user-directed and do not
count as the agent's self-requested review. Keep final judgment with the primary
agent.

A peer review has four parts, and most failures come from the last two rather
than the first two: decide whether to review, write the brief, invoke the peer,
and collect its result.

## Decide When to Review

Treat automatic review as an exception. Run it only when all of these are true:

1. The completed change introduces or materially changes a high-consequence
   boundary, rather than merely touching code in a high-risk domain.
2. A realistic failure could cause severe harm, broad impact, or a recovery that
   is difficult to execute safely. A reversible change with a tested rollback
   does not meet this gate by consequence alone.
3. Primary validation leaves a specific correctness risk that tests, plans,
   linters, type checks, or a safe rollout cannot adequately cover.
4. A read-only peer can inspect relevant evidence and bring a meaningfully
   independent line of reasoning before the work is finalized.

Qualifying boundaries include authorization enforcement where a bypass could
grant access, destructive or difficult-to-reverse data migrations, distributed
concurrency and idempotency, production release or promotion machinery with a
broad blast radius, and compatibility changes to a widely consumed public API or
schema. These labels are not triggers by themselves. The current change must
materially alter the risky behavior and pass every gate above.

Do not treat elapsed time, token or tool volume, diff size, component count,
unfamiliarity, a broad refactor, or nuanced analysis as independent reasons to
review. Skip automatic review for:

- reports, plans, research, summaries, visualizations, and other analytical or
  editorial artifacts;
- ordinary code reviews, architecture reviews, and requests to inspect a pull
  request or answer questions about it;
- documentation, tests, mechanical refactors, and routine feature, bug,
  Terraform, infrastructure, schema, or configuration changes that have strong
  deterministic checks or a safe rollback;
- addressing review comments, fixing CI, preparing commits or pull requests,
  publishing a draft for human review, merging an already reviewed change, or
  performing bounded follow-up work.

A request to "review" work directs the primary agent to review it. It is an
explicit request for this skill only when the user asks for an independent peer,
second opinion, adversarial pass, another model, or a named agent CLI.
Authorization to finish, push, publish, apply, or merge does not imply a peer
review request.

Honor any request to skip, stop, or avoid peer review for the rest of the agent
session. Resume only if the user later explicitly requests an independent peer.

## Choose the Peer

Start a fresh, non-resumed session in another installed and authenticated agent
CLI. Prefer a different provider:

- Claude Code host: prefer Codex CLI or Cursor Agent.
- Codex host: prefer Claude Code or Cursor Agent.
- Cursor host: prefer the direct CLI from another provider.
- Other hosts: choose the strongest available independent alternative.

For Claude-family reviewers, default to Opus 5.5 with `high` effort. Prefer this
combination over Fable, including when selecting a Claude model through Cursor.
Honor an explicit user choice of model or effort.

Discover the CLI's exact identifier for the chosen model. For other model
families, use the newest permitted flagship or coding model and the highest
supported single-agent thinking level, commonly `max` or `xhigh`. Pin the exact
model identifier the CLI reports; don't pass a short alias that may resolve to a
different tier later. If Opus 5.5 or `high` effort isn't available, report that
limitation before choosing an available alternative. Don't use a mode that adds
delegation unless the user asked for a panel.

Never lower the model or thinking level to make a review fit a waiting window.
If reviews are not finishing, fix the waiting mechanism described below. A
faster tier is a last resort after the persistent-session pattern has been
tried, and it must be reported.

Read the matching reference for exact flags, tool grants, and collection
commands:

- `references/claude-code.md`
- `references/codex-cli.md`
- `references/cursor-agent.md`

## Write the Review Brief

Give the peer the task, review scope, repository instructions, raw diff or
artifact, validation output, and relevant surrounding code. Do not include the
primary agent's conclusions or suspected findings.

A brief has three parts. The environment and output sections are fixed
boilerplate; only the review content changes between runs.

### Environment

State the harness, because the peer cannot discover it and will otherwise waste
its budget rediscovering the same walls:

```text
ENVIRONMENT
- Non-interactive session. No human can approve anything, so a blocked action
  stays blocked. Do not retry a blocked command in another form, and do not
  investigate why it was blocked.
- Tools available: <exact list>.
- Readable roots: this worktree and <granted scratch paths>. Do not read
  anything else.
- Budget: about N minutes. At 80% of budget, stop investigating and report what
  you have, marking any area you did not reach as "not reviewed".
- Prefer one shell command per call. Chained commands are harder to admit.
```

Name every readable root, and make sure each one is actually granted. A brief

From chadxz/prompts, MIT.

More from chadxz/prompts