super-review
Convenes an independent specialist panel for a first pass, a bounded second look at an accepted fix, or the readiness gate. The agent doing the work starts the first pass or the readiness gate when a change needs judgment against requirements, the project's declared standards and its tests. No slash command and no human act is required. Reviewers cannot edit source, and the author of the change does not sit a seat or close a finding. Not for writing the fix, not for running acceptance checks, and not for repairing a red pipeline.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 3
01 前言 Front Matter
- name
- super-review
- license
- MIT
- metadata
- { "ak": { "mode": "manual", "autonomy_unenforceable": [ "suppression of model invocation. This package does not request it (docs/decisions/0003-model-invocation.md). An agent starts full and readiness (ADR-0013).", "seat isolation is not attested by the host. This package assembles one evidence packet per seat and records what it withheld; it cannot prove the host kept two contexts apart.", "grant validation is the runner's. A controller that cannot validate a grant for the delegated operation stops. An agent start of the model entrypoint does not need that grant (ADR-0013).", "artifact-write is storage only: the host does not compute or check the artifact hash, so binding a finding to the snapshot hash is this package's own work." ] }, "ak_catalog_id": "super-review" }
- description
- Convenes an independent specialist panel for a first pass, a bounded second look at an accepted fix, or the readiness gate. The agent doing the work starts the first pass or the readiness gate when a change needs judgment against requirements, the project's declared standards and its tests. No slash command and no human act is required. Reviewers cannot edit source, and the author of the change does not sit a seat or close a finding. Not for writing the fix, not for running acceptance checks, and not for repairing a red pipeline.
02 资源文件 2
- 参考文档references/delta.md5.4 KB
- 参考文档references/panel.md11.9 KB
03 SKILL.md 正文
When to use
Use full when a change is ready for judgment and nothing has reviewed it yet: a panel of seats
reads one immutable snapshot against requirements, the project's declared standards, and the tests.
The agent that produced the change starts this itself, as part of the work.
Use delta when a finding was accepted, a fix landed, and the fix needs a bounded second look inside
the review run that is already open. After the first full, every later review of the change is a
delta over the commits since the last reviewed head, past the fix-cycle cap included.
Use readiness when a change is otherwise ready to ship and the question is whether the evidence
behind it holds up — not what is wrong with the diff, but whether anything required is missing.
Use it when a caller asks whether a change is safe to merge and the honest answer depends on evidence a reviewer has not yet read.
Not for
Not for producing the fix. Reviewers do not edit the source they review (policies/review.yaml);
accepted findings leave this skill and enter the apply-findings protocol, which is where an
implementer with write authority acts on them.
Not for establishing that the code works. A review reads a change; it does not run the project's
acceptance checks and does not produce receipts. Closure needs independent verification evidence
plus a policy rule saying that evidence suffices for that finding, and reviewer confidence stays
advisory (ruling closure-requires-independent-verification).
Not for repairing a red pipeline. A failing required check is CI repair's bounded operation, whose
rule restricts the purpose and scope of the repair and never the standard the change has to meet
(ruling ci-repair-restricts-purpose-not-permission). A product-code change discovered there
re-enters diagnosis, a bounded patch, new verification and affected delta review — this skill's
delta mode over the affected behavior, never a second full panel.
Not for failing a change on its size or its test-ratio shape. A roughly-hundred-line target and a
test pyramid are configurable starting points carried in engineering-principles, not
grounds for a finding on their own (ruling numeric-heuristics-are-guidance).
Not for reviewing a requirements document, a plan or an ADR. Those have their own persona catalog and
their own failure modes, and they enter through doc-review.
Authority
full and readiness: authority model, invocation M. The agent doing the work starts either
when a change needs that judgment. No slash command and no human act is required (ADR-0013). A
delegated controller may also start the same protocol through review.full and review.readiness
under a runner-validated grant covering finding-adjudication. A bypass grant (ADR-0008) remains a
valid start and is not required. delta: authority active-review-run, invocation M, through
review.delta.
Starting the review is not approval. The author of the change does not sit a seat and does not
supply the verdict (ruling missing-supervisor-never-implementer). The author does not close a
finding (ruling closure-requires-independent-verification).
There is one protocol. Where the host cannot validate a grant, a controller stops rather than
inventing a second pipeline (ruling entrypoint-phase-operation-split). An agent start does not
need that grant.
Under a Firstmate binding, cite .cursor/bin/ak firstmate grant --binding <path> --operation review.full (or
review.readiness) when it exits 0. A refusal means the binding does not cover the delegated
operation. It does not stop the model start.
Under a bypass grant, node <this skill's directory>/../../bin/ak-gate.mjs bypass check --grant <path> --task <id> --phase super-review:full (or super-review:readiness) exits 0 as one valid
start. Record the gate with --bypass <path> --task <id> so it carries the attribution. Under the unattended policy (ADR-0014), record each review gate with its evidence command after --, as the unattended-lifecycle reference says; a blocking finding still stops.
review.delta does not open a review run. Invoked where none is open, it stops with needs-input
naming super-review full as the next permitted action.
Inputs
The comparison base and the reviewed head, both named. Absent, stop with needs-input: a review with
no comparison base is an opinion about a file tree.
The requirements the change claims to satisfy, by id, for the spec axis. Where none can be resolved,
the spec lane returns unavailable rather than inventing an intent to review against.
The project's declared standards, discovered from the project's own record. Where a project declares
none, the standards seat returns an empty result; absent standards never become invented preferences
(policies/review.yaml).
The test evidence that exists for the change, and the packs the change earned. Packs are the artifact evidence that selects conditional seats; they are read, never guessed at from file names alone.
For delta only: the open review run, its persisted finding list with fingerprints and dispositions,
its input hashes, and the fix diff (schemas/review.schema.json packet).
Workflow
- Name the comparison base and the reviewed head before any other work. Absent either, stop with
needs-inputand do not convene a panel. Fordelta, confirm a review run is open; if not, stop withneeds-inputnamingfullas the next action. Do not stop because a person did not type a command, and do not send the caller away to type one. - Build the snapshot and freeze it: its hash, the comparison base, the reviewed head, the source revision and the input hashes. Every seat reads this one object and no seat may edit it.
- Select the panel from declared risk rather than from a fixed roster. Correctness is the only
unconditional seat; the standards gate runs when the project declares standards or when discovery
was uncertain; testing, maintainability, agent-native and learnings fire when the diff earns them;
security, adversarial and the remaining conditional and stack seats are selected from artifact
evidence, in practice from the attached packs. A substantive feature lands at the six-ish panel;
a documentation typo does not; and security, API and data facts are never dropped because a
classifier was uncertain (ruling
panel-composition-by-declared-risk). A change within the project's size guidance seats the lean panel. The catalog of seats, their selection signals and the lean panel are in./references/panel.md. - Assemble one context packet per seat: the frozen snapshot plus that seat's own requirements,
standards and test context. No packet carries the implementer's narrative, rationale or
self-assessment, another reviewer's findings or dispositions, or any approval context produced by
the author lane. Every packet carries the shell rule in
./references/panel.md. Two seats sharing a scratchpad are one seat. - Check the exclusions before dispatch. A seat that cannot be filled independently of the author is
unavailable, and the security seat is filled by neither the implementer of the change nor whoever approved its spec (rulingmissing-supervisor-never-implementer). - Dispatch the selected seats concurrently within the turn, each in its own isolated review context. Every finding quotes the line it is about.
- Record each lane's state as
covered,skippedorunavailable(schemas/review.schema.json); the mapping from a seat's own result is in./references/panel.md. A lane that could not run, could not be given its required context, or failed, isunavailablewith the reason named — a result, not an absence (rulingrequired-lane-failure-is-unavailable). Store each covered seat's output exactly as it returned, as a run artifact referenced by hash, before synthesis reads it. - Synthesize without merging: deduplicate by fingerprint, keep each seat's evidence attached to its finding, and never rewrite a severity to reconcile two seats. Suppression is by the catalogued reasons only, and a suppressed finding stays readable with its reason.
- For
delta: first test whether architecture, requirements, the comparison base or the affected surface changed materially. Where any did, invalidate the affected approvals and establish a new baseline — a new scope with its own pass 1 — instead of continuing this loop (rulingdelta-baseline-reset-not-third-loop). Fix commits, a reached cap, a replan and a rebase that leaves the patch unchanged are not material. Otherwise build the packet, run the spec and standards lanes over the fix, and bound the scope by affected behavior rather than by changed lines (rulingdelta-scope-affected-behavior). A continuing seat keeps its earlier finding context, or a replacement receives the durable prior-finding packet; independence from the author is mandatory and amnesia is not (rulingreviewer-continuity-not-amnesia). The mechanics are in./references/delta.md. - For
readiness: run the two independent lanes as a gate over the panel's synthesized verdict, not as a substitute for it. A missing lane isunavailable, and a blocking lane result vetoes approval no matter what the panel concluded. Load verification evidence, then, where the build gate records an implementer seat, require each criterion's current receipt to name a runner-attested verifier seat distinct from it (without that record, only recipe-bound checks need one, and ahost-unattestedseat counts, disclosed as worker-attested, only in a run that never held a grant; under the unattended policy (ADR-0014) a distincthost-unattestedseat counts as a recorded note, whose boundary is the live merge-gate read, an exception to rulingclosure-requires-independent-verification). Eachfrontendorbackendcriterion needs a supporting check that declaresevidence_required, and receipts carrying every declared kind. A missing required attestation, a missing declaration or a missing kind makes the verification laneunavailable; name the gap. - Set the verdict from the lane results:
approved,changes-requested,blockedorunavailable. Emit the review and its findings, and report what is still open. - On
approved, record the gate for this mode:node <this skill's directory>/../../bin/ak-gate.mjs record --gate review-full,review-deltaorreview-readiness(the bundle'sbin/). Afullthat returnedchanges-requestedrecordsreview-full --verdict changes-requested; no other verdict is recorded. A full record on an earlier head, or one that requested changes, counts once an approved delta recorded after it covers the head. Run it from the project checkout; the run defaults to the branch's opened-run pointer (or the branch-named v1 run) and records to the git directory. A binding's brief supplies--dir. A record on a run thatship-preflighthas closed is refused; the task needs a newopen.
Hard gates
Gate: reviewers cannot edit source (policies/review.yaml reviewers_may_edit_source: false), and
the snapshot is immutable for the length of the run. A reviewer that changed what it was reviewing
has reviewed nothing.
Gate: a required lane that returns unavailable blocks approval. It is never downgraded to an empty
result, never backfilled by the author, the implementer, another seat or the synthesis step, and
never replaced by self-review. The review names the lane and why, and stays resumable (ruling
required-lane-failure-is-unavailable).
Gate: a seat that cannot be filled independently of the author is unavailable, and unavailability
blocks the checkpoint rather than falling to whoever is still there (ruling
missing-supervisor-never-implementer).
Gate: an author may never close their own finding, and a finding closes only on independent
verification evidence plus a policy rule saying that evidence is sufficient for it. A receipt is the
unit of that evidence: it carries the command or probe, its exit status, the output digest, the
revision and the environment identity (schemas/verification.schema.json). An agent's description of
a green run is not a receipt. A classifier's output and a reviewer's confidence are recorded as
advisory, and a changed patch does not inherit stale receipts (ruling
closure-requires-independent-verification). A receipt or a verdict is stale once the revision or
the working-tree diff hash it names differs from the snapshot being judged; either one moving is
enough.
Gate: at most two fix-and-verify cycles after the first pass. The third request stops with the cap
decision and the open findings attached; repeated failure is a signal about the plan, not an
invitation to a third loop (ruling two-fix-cycles-then-stop). With only P3 findings open it is
merge-with-follow-ups, listing them in fix_cycles.follow_ups, and the verdict may be approved.
When two consecutive cycles reopened the same finding theme it is design-decision, naming it. A
cycle a human authorizes after the decision is recorded in fix_cycles.extensions (authorized_by: human, operator-attested, and when) and reviewed as a delta that may approve, never as a new
full; without that entry it is refused.
Gate: where architecture, requirements, the comparison base or the affected surface changes
materially, the affected approvals are invalidated and a new baseline is deliberately established —
a new review scope with its own pass 1, never an unbounded third delta loop. The run records its
comparison base, its reviewed head and the last head verified in the delta loop so the three are
never conflated (ruling delta-baseline-reset-not-third-loop).
Gate: a finding whose solution space is still open is never handed to an automatic fixer. A smell
carries a null difficulty, because inventing a difficulty before the solution class is known is the
error the axis exists to prevent; its action class is never automatic; and its dispatch is to
sharpen, to diagnose or to escalate, never a fixer ticket (schemas/finding.schema.json, ruling
safe-auto-restricted-per-seat). Pressure to hand it over anyway is not a reason it became
specified.
Gate: a standards finding cites the project rule it rests on, rule by rule, with the file and the
rule identifier. Where the project declares no standards the seat returns an empty result: absent
standards never become invented preferences, and a seat that cannot cite a rule returns empty
(policies/review.yaml).
| The thought | Why it is wrong | Do this instead |
|---|---|---|
| "The security seat could not be seated, but the implementer knows this code best and can look at it." | Backfilling a seat from the author lane produces an approval no independent evidence supports, which is the one thing an unavailable lane must never become (ruling missing-supervisor-never-implementer). |
Record the lane as unavailable with the reason, block approval, and leave the run resumable for when the seat can be filled. |
| "Autopilot needs two independent judgments; I will start two reviewers myself, or reuse the standards seat I already started." | A helper this run started is not independent of this run, whoever it is told to be (ruling missing-supervisor-never-implementer), and the supervisor judgments are not seats of this panel (ruling firstmate-outer-loop-agent-kit-inner). |
Finish the panel's own lanes, and return the request for the two judgments to the supervisor that owns the task (Firstmate, where one supervises), which dispatches them as separate agents. |
| "Only one lane is missing and everything else came back clean, so the verdict is approved with a note." | A required lane's absence is a result, not a footnote; an approval with a note reads downstream as an approval (ruling required-lane-failure-is-unavailable). |
Set the verdict to unavailable or blocked, name the lane, and say what would make it runnable. |
| "It is a one-line change, so spawn the standard panel anyway — it is cheaper than deciding." | A fixed roster is the position this package refused; it spends seats on a typo and teaches readers that panel size means nothing (ruling panel-composition-by-declared-risk). |
Select from declared risk and attached packs, and record which seats were selected and which signals selected them. |
| "The fix only touched three lines, so the delta reviews those three lines." | The impact of a fix reaches callers the fix never touched, and a line-based boundary suppresses exactly the class of issue the delta exists to catch (ruling delta-scope-affected-behavior). |
Bound the delta by affected behavior, and report a serious issue in an untouched affected caller with its novelty evidence. |
| "Give the reviewer the implementer's summary so it knows what the change was trying to do." | The narrative is the author's account of their own work, and a seat that reads it is judging the account rather than the change (policies/review.yaml). |
Hand the seat the frozen snapshot and its own requirements, standards and test context, and nothing produced by the author lane. |
| "The finding is vague, but the fixer is good at this — hand it over and let it work out the details." | A smell is a problem whose solution space is still open, and handing it to an automatic fixer buys a change nobody specified against a difficulty nobody could yet know (ruling safe-auto-restricted-per-seat). |
Keep the difficulty null, sharpen the finding into a bounded one, diagnose it, or escalate it — and record which of the three the dispatch was. |
| "The reviewer rated the fix high-confidence, so the finding can be marked resolved." | Confidence is a property of the judge; closure is a property of the evidence (ruling closure-requires-independent-verification). |
Record the confidence as advisory, and close only on independent verification evidence for the revision the fix is at. |
| "The base moved and the requirements were rewritten, but the delta loop still has a cycle left." | Continuing a loop whose comparison base no longer means what it meant spends a cycle comparing against a baseline nobody approved, and the approvals it carries forward were given for a different change (ruling delta-baseline-reset-not-third-loop). |
Invalidate the affected approvals, record what changed materially, and open a new scope at pass 1 rather than spending the remaining cycle. |
| "The cap is reached, so replan and open a new full scope over the whole change." | A full pass over a change already reviewed re-litigates settled code and finds new nits each round, so the loop never ends (ruling two-fix-cycles-then-stop). |
Review the new commits as a delta against the last reviewed head. |
| "The third cycle is nearly there — one more round and it is clean." | Two cycles that did not converge are evidence about the plan, and a third loop spends the budget that the cap decision exists to protect (ruling two-fix-cycles-then-stop). |
Stop, emit the cap decision, attach every open finding, and report what is unresolved. |
| "The diff is 400 lines, which the engineering principles call too large, so that is a finding." | Size targets and test ratios are configurable starting points, and a finding written from one is a finding about a number nobody agreed to (ruling numeric-heuristics-are-guidance). |
Review what the change does. Raise size only where it names a concrete review or maintenance consequence in this change. |
Outputs
The review (schemas/review.schema.json): mode, comparison base, reviewed head, the snapshot with
its hash and exclusions, the authorship record, one entry per lane with its state and verdict, the
fix-cycle count, the verdict, and — where a baseline was reset — what changed materially, which
approvals it invalidated and the new comparison base.
The findings (schemas/finding.schema.json), each with its evidence quoting the line it is about,
its fingerprint — rule-or-cause plus location-or-symbol plus evidence, never the line number — and
its action class. No code-review seat emits safe_auto: at review time a code edit has no single
mechanically correct answer, so classification is a proposal and applying it is the caller's decision
under its own authorization. A safe_auto arriving from a peer lane is remapped to gated_auto and
never dropped (ruling safe-auto-restricted-per-seat). A finding's dispatch is single-valued and a
smell is dispatched only to sharpening, diagnosis or escalation, so the review records which of the
three it took and never a fixer ticket.
A lesson candidate marked on any finding that teaches a durable rule. This skill marks it and publishes nothing: the knowledgebase write is not inside the envelope the review operations declare.
All of it is emitted as run artifacts under artifact-write. This skill names no repository path for
project-derived content.
Side effects
artifact-write.
No workspace-write, no local-commit, no remote-push: the review operations declare one effect,
and a seat that edits, commits or pushes has left the envelope the runner validated.
No pr-comment: posting a review onto a pull request is a separate granted action and belongs to the
skill that holds it.
Stop conditions
complete: every selected lane has a state, every required lane is covered, the
verdict is set, and the review and findings are emitted. A run whose verdict is blocked is
complete; the block is the result. A delta that ends by establishing a new baseline is complete too:
the reset closes this scope and the new scope opens at pass 1, which is not a third loop (ruling
delta-baseline-reset-not-third-loop).
needs-input: no comparison base or reviewed head was named, or delta was invoked with no open
review run. Returns what it would need, and no partial verdict. A missing typed command is not
this stop.
cap-reached: a third fix cycle was requested. Stops with the cap decision (blocked, replan,
merge-with-follow-ups or design-decision) and every open finding attached.
failed: a required lane returned unavailable and the run cannot proceed, or the snapshot could
not be frozen. The lane and the reason are named, and the run stays resumable. A knowledgebase coverage limit — .cursor/bin/ak kb check exit 3 (kb.unbound, kb.unregistered), a publish exit 3 (kb.read-only), kb.in-repo-missing, or a missing or unknown .cursor/bin/ak kb command — never stops this phase under any policy: reads are unavailable, each skipped publish is named in the result as not published, and only exit 1 stops. A seat that reads the knowledgebase runs against what it can read and names the limit, so a lane whose only gap is that limit is covered, not unavailable; the learnings lane, which activates only on a readable corpus with hits, is recorded skipped with the limit as its reason.
cancelled: the caller withdrew mid-run. Lane results already collected are kept and emitted as
what they are.
Limits
Fix cycles: 2 (gate). policies/limits.yaml fix_cycles. The third stops with the cap decision
rather than another pass.
Review rounds: 3 (gate). policies/limits.yaml review_rounds, counted across the run.
Panel size: no cap (guidance); the count follows declared risk. Small pass-1 diffs seat the lean panel; a delta seats its two core lanes plus only the specialist seats a prior finding or its diff triggers.
Change size and test ratios: not gates (guidance). Carried in engineering-principles,
set per project, and never grounds for a finding on their own.
Runner budgets: a cap the runner did not supply is not enforced and not guessed
(policies/limits.yaml).
04 同仓库更多 Skills
alpha
Human-started command: it runs only when the human's message begins with `/ak:alpha`. On any other request do not load or follow it; tell the human to type that command. Runs the alpha workflow when a human asks for it.
alpha
Human-started command: it runs only when the human's message begins with `/ak:alpha`. On any other request do not load or follow it; tell the human to type that command. Runs the alpha workflow when a human asks for it.
alpha
Human-started command: it runs only when the human's message begins with `/ak:alpha`. On any other request do not load or follow it; tell the human to type that command. Runs the alpha workflow when a human asks for it.
alpha
Human-started command: it runs only when the human's message begins with `/ak:alpha`. On any other request do not load or follow it; tell the human to type that command. Runs the alpha workflow when a human asks for it.
alpha
Human-started command: it runs only when the human's message begins with `/ak:alpha`. On any other request do not load or follow it; tell the human to type that command. Runs the alpha workflow when a human asks for it.
alpha
Human-started command: it runs only when the human's message begins with `/ak:alpha`. On any other request do not load or follow it; tell the human to type that command. Runs the alpha workflow when a human asks for it.