Design and review
How much design a change deserves, and the tools for each rung: architect, arena, swarm, interrogate, and a second model on your work.
One attempt at a hard design locks in the first shape the model thought of. These tools spend more effort where a wrong shape costs more. Most changes need none of them.
How much design a change deserves
| The change | Reach for |
|---|---|
| Small and finished, but you're unsure | a blast-radius check |
| A branch about to become a PR | simplify, then interrogate |
| Crosses function boundaries or moves ownership | architect, which runs an arena of sketches |
| A standalone decision where independent attempts help (a name, a format, an algorithm) | an arena directly |
| A coverage matrix, parallel checks, or a race | a swarm |
| A contested design that's expensive to reverse | architect, then interrogate or a second model before shipping |
Architect
you > architect the import pipeline before writing code. i care most about how callers use it.
you > architect with checkpoint. show me before implementing.The caller's usage comes first: the quickstart a consumer reads and two or three real call sites, with the types derived from them. At least two structurally different shapes get sketched, each screened for four red flags: a shallow module, information leakage, temporal decomposition, and pass-through methods. The deepest interface wins. A one-page rationale ships with the sketch, covering the usage, the shape, the tradeoffs accepted, and the alternative that lost. When implementation keeps fighting the sketch, the sketch is scrapped and redesigned smaller rather than patched.
Arena
N attempts at the same brief run in parallel, each in its own worktree or folder. A read-only judge scores them against a rubric the candidates never saw. Your agent reads every candidate, picks the one a maintainer can extend most easily as the base, grafts the best idea or two from the others, and verifies the result. When every candidate converges, that's the answer. When they wildly diverge, the brief was underspecified and gets reframed.
Swarm
N workers cover separate slices ("one worker per package") or race the same brief under a rule declared up front. Each reports PASS, ISSUES, or BLOCKED with evidence, and you get one table back instead of N transcripts. A missing result is a gap, never a pass.
Interrogate
you > interrogate this branch
you > simplify and interrogate this branch, i want it ready for a PRInterrogate is the PR review run on your own branch before there is a PR, so the one you open is already clean. It reviews <base>...HEAD plus your uncommitted changes, in the checkout you're on. The steps are the review's own: prior context, the change understood before it's judged, the repo's checks run locally, the review lanes and the case against in parallel, and every candidate checked by an independent verifier. The agent then judges as the lead, not an aggregator, and sorts what survives:
- Act on: verified defects this branch introduced. They are fixed in your working tree and left uncommitted for you to read.
- Consider: open questions, nits worth acting on, and any architecture recommendation. These are held for your call.
- Noted: real problems that were already there before this branch.
- Dismissed: one line each, with the reason, so you can overrule it.
The reply stays in chat; no report page is written. It opens with a readiness line (ready for a PR, ready once you decide one thing, or not ready and why) and ends with commit messages for the fixes and a draft PR title and description. Opening the PR is a separate ask. Asking for "simplify and interrogate" runs simplify on the branch first, so the review judges the cleaned code, and the checks run only once.
A second model on your work
Reviewers inside one session share a model's blind spots. For model diversity, adversarial-review briefs a different model or host on your branch, working tree, or plan, then verifies each of its findings against the code and fixes the real ones, all on one dossier. See Second-model review.
The comment pass
Before any diff reaches you, a reviewer that didn't write the code strips comments that narrate what the next line does. It keeps license headers, public API contracts, and constraints forced by something outside your control. A comment explaining a surprise in your own code comes back as a flag to fix the code instead, and a lint suppression that protects correctness gets flagged for removal.
Principles
Twenty-three engineering principles, each a short rule with a test the agent runs on its own work. Name one to steer.
Second-model review
Put a different model on anything you made, a proposal, a plan, a document, or code. It documents what it finds on one dossier; your agent verifies every finding, fixes the real ones, and hands back the next round.