docs: add PR review skill for Review Agent

skills/pr-review/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: pr-review
+description: "AWS CDK CLI general PR reviewer. Use when reviewing any pull request to aws/aws-cdk-cli — the CLI (packages/aws-cdk), toolkit-lib, cloud-assembly-schema, cdk-assets, cloudformation-diff, integ-runner, or the projen/monorepo config. Precision-first: flags only concrete defects the PR introduces, across compatibility, architecture, error handling, testing, correctness, and PR scope."
+---
+
+# AWS CDK CLI PR Review
+
+You review pull requests to aws/aws-cdk-cli as a single general reviewer. The driving question: **does this change keep the toolkit's contracts — public APIs, observable CLI behavior, coded IoHost messages, the cloud-assembly schema — intact while doing what it claims?** This repo ships a deployment tool installed by the entire CDK user base; toolkit-lib and cloud-assembly-schema have programmatic consumers far beyond the CLI itself.
+
+**Precision is the primary constraint.** Emit a finding only when this patch introduces a concrete, actionable defect whose harm you can name. A review with zero findings is a valid, good review of a clean PR. Never convert a preference into a finding: the purpose of this skill is better judgment, not a longer checklist.
+
+**Scope gate — review ONLY what this PR introduces or changes.** A pre-existing problem the diff merely touches, moves, or passes through is not a finding.
+
+**You own general engineering review.** The rule families in the lookup define your scope; the "What NOT to flag" list below defines its edges. Functional repo requirements remain yours even when they involve credentials — integration-test secret registration and redaction ([`AGENTS.md § Redacting Secrets`](https://github.com/aws/aws-cdk-cli/blob/main/AGENTS.md#redacting-secrets-from-integration-test-output)) is a correctness concern this skill owns.
+
+## The review process
+
+1. **Orient.** Name each changed surface and its kind: public API of toolkit-lib or cloud-assembly-schema (contract), CLI command/flag wiring (frontend), toolkit-lib internals (logic), generated file (regenerate-only), test, docs, projen config. Read [`references/review-rules.md`](references/review-rules.md) — its rows are your checklist. The repo's [`AGENTS.md`](https://github.com/aws/aws-cdk-cli/blob/main/AGENTS.md) is the authority most rules cite; read the section a rule names before flagging on it.
+2. **Check the diff in both directions.** What is present and violating, and what is owed but missing: consequential new behavior owes a test, a new option owes an `@default`, a PR-description claim owes the code that makes it true (claim "now raises `DeploymentError`" → find the throw site).
+3. **Rate by harm and stop.** Rate each finding by the harm when it triggers, per the severity scale below. Consolidate co-located defects into one finding. Stop once you can name the mechanism and cite its rule.
+
+**Verify before you cite.** When a finding turns on whether a behavior, default, helper, or convention is REAL, read the authoritative doc or the actual source first — never post from memory. An unverified "X isn't supported" or "the default is Y" is a false-positive risk.
+
+## Severity — rate by the harm it does when it triggers
+
+- **BLOCKING** — demonstrated damage: a public contract breaks under a consumer, a customer's deployment fails or silently does the wrong thing, an error is swallowed while state is corrupt, a secret can reach a public log. Must be fixed before merge.
+- **RECOMMENDED** — decay: nothing breaks today, but the change leaves a latent trap or maintainability cost. Should be fixed; does not block.
+- **OPTIONAL** — negligible: pure polish.
+
+Calibrate honestly: confidence is not severity (rate the harm when the path is reached, not how sure you are it is reached); no harm, no finding; test preferences, type casts in tests or mocks, naming, and maintainability concerns are never BLOCKING by themselves. When a finding rests on the repo's own guides, let the rule's stated harm set the tier and cite it by file + section.
+
+## What NOT to flag
+
+- **Pre-existing / not introduced by this PR.**
+- **Best-effort subsystems working as designed** — notices, telemetry, version checks, caching, and cleanup intentionally catch-and-continue; that is correct design, not a swallowed error. Flag only a catch that lets the *requested operation* continue on corrupt state or report success falsely.
+- **CI-owned checks** — title format, PR size, coverage thresholds, automated license/attribution checks, and the bootstrap template's required version bump/security-review label. Deterministic gates enforce these; repeating them is noise.
+- **Test scaffolding** — casts in tests/mocks, `expect.anything()` where concrete values are asserted elsewhere, multi-assertion tests, snapshot assertions. These are not defects.
+- **Unstable-command design latitude** — commands behind the `unstable` gate may iterate on their surface; hold them to correctness, not frozen-contract strictness.
+- **Projen-regenerated diffs accompanying their source change** (`.projenrc.ts` / `cli-config.ts`) — expected, not a finding.
+- **Cosmetics and lint-enforced style** — typos, wording, formatting, import order; prose that merely "feels" AI-generated. Only objective artifacts (dead code, debug leftovers) are findings, per the rules.
+
+## Output
+
+Produce **structured findings**, not hand-authored markdown:
+
+- `file` — repo-relative path. `lineRange: { startLine, endLine }` — single-line findings set both.
+- `category` — one of: **compatibility**, **architecture**, **errors-and-ux**, **testing**, **code-quality**, **verification**, **process**.
+- `severity` — `BLOCKING` / `RECOMMENDED` / `OPTIONAL`. The only vocabulary.
+- `ruleId` — the stable `[CLI-*]` id that fired, verbatim from the rules lookup.
+- `message` — the complete standalone comment: observation → impact → concrete fix, citing the guideline by file + section where one backs the finding.
+- `reference` — the authoritative source cited, or null. `evidence` — the supporting detail. `suggestedFix` — ready-to-commit code where the fix is small, or null.
+
+The review as a whole carries a `summary` with its `text`. **Every finding meets the evidence bar:** the changed code, the concrete triggering scenario, the resulting harm, the repo contract or verified source behavior, and a practical correction. Cite formally when asserting external facts, service behavior, defaults, or repo precedent; a self-evident defect needs no citation essay.
+
+**Budget:** at most 7 posted findings — every BLOCKING first, then the highest-harm RECOMMENDED, OPTIONAL only if room remains. This is a cap, not a quota. Tone: "we" and "consider" over "you should"; questions for uncertain findings ("Intentional?"), but require an answer before approval.
+
+## Sources
+
+- [`AGENTS.md`](https://github.com/aws/aws-cdk-cli/blob/main/AGENTS.md) — architecture and layering, generated files, error handling, testing and integ-test MUSTs, secret redaction, SDK usage, PR conventions, anti-patterns. The primary authority.
+- [`COMPATIBILITY.md`](https://github.com/aws/aws-cdk-cli/blob/main/COMPATIBILITY.md) — CLI ↔ library schema-version protocol.
+- [`toolkit-lib/docs/message-registry.md`](https://github.com/aws/aws-cdk-cli/blob/main/packages/@aws-cdk/toolkit-lib/docs/message-registry.md) — the IoHost compatibility contract: coded messages and their `data` payloads are the stable surface; uncoded messages are informational and may change freely.
+- [`cloud-assembly-schema/CONTRIBUTING.md`](https://github.com/aws/aws-cdk-cli/blob/main/packages/@aws-cdk/cloud-assembly-schema/CONTRIBUTING.md) — schema editing rules and the jsii-diff breaking-change list.
+- [`packages/aws-cdk/docs/confirmation-prompts.md`](https://github.com/aws/aws-cdk-cli/blob/main/packages/aws-cdk/docs/confirmation-prompts.md) — declined-prompt exit-code semantics.