Workflow · Plan & code reviewDraft
Two reviews. One before any code exists, one before it ships.
Both use the same reviewer table and the same rules. Reviewers are chosen by what the work touches, they challenge each other when their domains overlap, and no blocking finding is passed on without a citation.
On this page: review-plan · review-code
review-plan
/review-planReviews the plan most recently presented in the session.Open source, free: skills/review-plan/SKILL.md. The step numbers below match the file.
Step by step
- 1
Context prep
Before any reviewer spends a token, four lanes run together: a search of your docs and past plans for prior decisions, git history, and a check of every claim the plan makes about existing code.
- 2
High-blast-radius callout
The plan text is scanned for operations you have marked as protected. A hit is flagged for your explicit approval. This is a reading of prose; the enforceable gate is in code review and ship, where there is a diff.
- 3
Pick the reviewers
The plan’s topics, components and paths are matched against your reviewer table. It prints who matched and why. If nobody matches, one general reviewer runs.
- 4
The lead’s structural audits
While reviewers work, the lead audits the plan as a document. These are properties no domain reviewer checks.
- Deferred work: every phrase that pushes work out of the plan
- Scope: how many pull requests this really is
- Test plan
- Requirement traceability: each requirement maps to a step
- 5
Reviewers run
All reviewers launch in one batch. With two or more domain reviewers they collaborate; with one, it runs alone. A zero-context reader always runs. It reads the whole plan as a document, with no domain to defend.
- 6
Convergence
The lead reads every findings file and the cross-talk, removes duplicates, and checks that every blocking finding carries a citation. No citation, and the finding is downgraded.
- 7
Your reviewYou decide
Findings are presented by severity. Anything questioning whether a phase is needed at all is shown as an option for you to decide, never as a verdict. Then the plan is edited.
- 8
Round two and the second opinion
Only reviewers that had findings, or whose domain the edits touched, run again. Then a different model reviews the updated plan. It runs after the group so it is not paid to rediscover what the group already found.
- 9
Final plan
What changed, the round-two findings, the second-opinion verdict, anything still open, and a plan the implementer can start from in a fresh context.
Why it is shaped this way
Verify assumptions first
A plan that is wrong about what the existing code does is the largest source of plan defects. Every "X currently does Y" is checked before reviewers read the logic.
Collaboration beats isolation
A reviewer who hears another’s finding checks its own domain against it. Cross-domain blockers live in that gap.
Necessity is your call
A phase that serves no stated requirement is a scope question. It is capped at a warning, collected in one visible block, and decided by you.
Fail-safe at every gate
A reviewer that returns nothing is reported and you decide. It is never silently dropped.
review-code
/review-codeReviews an open pull request, or the branch’s committed and uncommitted changes.Open source, free: skills/review-code/SKILL.md. The step numbers below match the file.
Step by step
- 0
Scope and protected filesBlocking gate
The changed set is everything from the merge base to your working tree. Changes to files you have marked protected stop the review until you approve them. Typecheck, lint and build start in the background.
- 1
Did it build the right thing?Blocking gate
Requirement fidelity runs first. The requirements are found from the ticket, the plan or the pull request, and the diff is judged against them for coverage, scope and intent. A different model answers the same question. A misaligned verdict stops everything else.
- 2
Pick the reviewers
Changed paths are matched against the reviewer table. A file matching several rows launches several reviewers, on purpose: each row is a lens.
- 4
Never review a red treeBlocking gate
The background checks are collected. Any failure stops the review. Reviewer tokens are not spent on a tree that does not typecheck, lint or build.
- 5
Reviewers run
All reviewers launch in one batch with a list of what the tools and the fidelity check already flagged, so they do not rediscover it. Two or more domain reviewers collaborate. A zero-context reviewer always runs.
- 6–7
Audits and convergence
The lead runs its own file audits while reviewers work, then merges every source, removes duplicates and checks citations.
- 8
Findings and the fix pass
Findings are presented by severity, attributed to every source that raised them. The default is fix now. Deferring needs one of four named reasons, such as a missing credential or a contract change beyond this diff. Nothing is committed.
- 9
Second opinion on the fixed code
A different model reviews the code after the fixes land, when it can find what the group missed and not what the group already found.
- 10
End-to-end gateBlocking gate
Files on your critical paths need a real end-to-end run. Docs-only and type-only changes are exempt, with the reason stated.
- 11
Focused second pass
The reviewer that found the most issues re-reviews with the list of what was fixed, looking only for new or unresolved problems.
- 12–13
Findings log and loose ends
One log file per branch. Anything still deferred is either fixed now or, with a verified reason, proposed to you as a tracking ticket.
- 14
Sentinels
Always last. The review and end-to-end results are recorded against a fingerprint of the exact code reviewed. Ship reads them. If the code changes afterwards, the record no longer matches and ship will not accept it.
Why it is shaped this way
Intent before quality
A clean diff that solves the wrong problem is wasted review. Fidelity runs first.
Trust but verify, from every source
Every blocking finding, whether from a reviewer, the lead or an external model, needs a file and line or script output behind it.
Fix now is the default
A finding is fixed in the same pass unless there is a named reason it cannot be.
Expensive greens are reusable
A passed review is tied to the exact code. Ship can rely on it without re-running it, and cannot rely on it once the code moves.
What it will not do
- Review code that fails typecheck, lint or build.
- Commit. It reports what changed and you decide when to commit or ship.
- Drop a reviewer that returned nothing without telling you.
Questions
Who are the reviewers?
Yours. A bootstrap skill surveys your repo and proposes the specialist agents and the table that maps paths to reviewers. You approve the roster before anything is written.
What is the second opinion?
A model or provider different from the one running the session. It is optional. When it is not configured the review says so and continues.
Do the reviewers really talk to each other?
Where the agent harness supports it, yes. Elsewhere the skill runs two rounds and hands each reviewer the others’ blocking findings in the second.