Perfection Review

---
name: perfection-review
description: >-
  Adversarial "perfection" review — hold a change to an *ideal* bar, not just a correct one,
  assuming eternal time, unlimited energy, and no ship pressure. Use when the user asks to
  review "for perfection", to make a defect "impossible to express", or to hunt where a defect
  "relocates" across review rounds. Grounds every claim in the diff, fans out adversarial
  verifiers via Workflow, and reports residual surfaces with a structural fix for each. ONLY
  invoke when the user explicitly asks for a perfection / ideal-bar review.
argument-hint: "[<pr-number>] [--base <branch>] [--post]"
---

# Perfection review

The bar is not **"closed"** but **"the defect can no longer be expressed."** Assume eternal
time, unlimited energy, no deadline. "Overridable", "acceptable for scope", and "documented
intent" are *still holes*.

Most defects are **one shape in costumes**. Name the shape, then hunt **where it relocates** —
a fix that satisfies the literal ask but lets the defect resurface one seam over is not done.
Track it across rounds until it has nowhere left to go.

## Method

1. **Ground in the diff, not the story** — the PR body, commit messages, docs, and the
   author's claims are assertions to falsify, not facts. Check them against the code.
2. **Letter vs effect** — a safety added but never exercised is inert. Require a real path
   that uses it and a test that fails when it is removed.
3. **Unspellable > absent** — make the wrong thing impossible to write, not merely
   discouraged. If a future author can still spell the defect, it isn't closed. Beware a
   guarantee that proves *presence*, not *behaviour*.
4. **Reconcile claim and code** — an overclaiming comment or doc is itself a defect: make the
   code earn the sentence, or soften the sentence.
5. **Finish the blast radius** — not done until every dependent and downstream is carried to
   the same bar and verified against the final state.

## Foundational invariants — the architecture lens

When the change touches **how state is produced, stored, ordered, or typed**, reach for the
`architecture-first-principles` lens (the state-and-time complement to `hickey` / `lowy`). It turns
a vague "this feels wrong" into a named, grounded **invariant** and a concrete *make-it-unspellable*
target:

- name which principle a residual defect violates — *values not places* (P1), *pure core / effects
  at the edge* (P2), *one authority on its own clock* (P3), *illegal states unrepresentable* (P4),
  *guarantees at the knowing endpoint* (P5);
- the "unspellable" fix is that principle's positive form — P4 → make it a type error; P3 → one
  writer / the consumer's clock / a lawful merge; P1 → delete the mutable place; P2 → move the
  effect to the edge; P5 → relocate the guarantee.

This is how *"make the wrong thing impossible to write"* (above) gets a **structural** target
rather than a one-line patch.

## Verify adversarially — use Workflow

**Review with fresh context, separate from the author** — a reviewer carrying the author's
context rationalizes the author's intent; a fresh mind grounded only in the diff does not.
Fan out grounded verifiers (one per claim) **plus an adversary whose only job is to express
the defect anyway**, each citing the diff; then synthesize. Default to *refuted-if-uncertain*,
loop until nothing new surfaces, and re-verify the headline finding yourself. Keep agent
schemas **flat** and isolate the adversary so one failure can't abort the run.

## Report

Lead with **credit** for what's closed — don't move goalposts on done work — then the
**residual surfaces**, ranked, each with its structural fix. Frame each finding as the
**invariant it violates**, not a lone exploit: a single proof-of-concept trains a one-line
patch and the defect just relocates — give the property, and if you must show an example,
give a few from different angles and call it one costume of many. Separate "the product is
fine" from "the claim isn't yet true". Post to the PR only when asked (`--post`).

Alongside the defects, RUN the `architecture-first-principles` skill's checks (C1–C7) as part of
the fan-out — ecosystem duplicates, consumer ergonomics, the graduation sweep (the
electricity angle, even at population one), the one-hop depends-on audit, fresh-eyes, state-and-time, and
project conventions. The checks are executable prompts, not advice: include
them as hunters in this review's own Workflow rather than paraphrasing them. Their
confirmed findings report as non-blocking structural opportunities beside the defects.