review-fix

Review fix

Run Review Rounds until clean from a resolved Review Policy:

/review-fix [target] [free-form review brief]

Examples:

/review-fix
/review-fix #123
/review-fix over-engineering
/review-fix #123 specification compliance and authorization boundaries
/review-fix ponytail-review and ask-exemplar

An explicit brief chooses the Review Policy; no brief uses the Default Review Policy. This skill owns reviewer orchestration, evidence verification, repairs, and checks.

Resolve the request

Treat the leading argument as the target only when it unambiguously resolves as an existing Git ref, a PR or MR number in the current repository, or a PR or MR URL. Otherwise use the current branch and working tree as the target and treat the whole argument as the Review Brief.

Resolve an explicit target into an editable local checkout without disturbing uncommitted work. A target that cannot be checked out safely makes the outcome incomplete. Determine the target's base from forge metadata, its upstream, or the repository's default branch, in that order.

When the request contains no brief, use the Default Review Policy below. This includes a target-only request such as /review-fix #123.

Resolve the review policy

A Review Request runs as report-only review roles. A Leaf Review Skill has one role; a Composite Review Skill includes its required angles and synthesis. The orchestrator schedules every role directly and performs composite synthesis. These scheduling rules override nested delegation and fresh-agent requirements in invoked skills; their review criteria and required reports remain unchanged.

• Each explicitly named review skill creates one Review Request.
• Explicitly named skills replace the Default Review Policy rather than adding to it.
• Read each named skill during preflight. Accept leaf and composite Review Skills that can complete the request without writes or external mutations. Reject cycles and skills whose required descendants cannot be resolved or kept report-only.
• When no skill is named, match the brief against installed Review Skills. One unambiguous match uses that skill; no match creates one ad-hoc Reviewer from the brief; several plausible matches require native structured input to select one. Start no Reviewer and leave the target unchanged until selection. Offer a multi-skill panel only when the caller explicitly asks for multiple Review Requests.
• Several concerns in one skill-free brief remain one ad-hoc Review Request. Never split prose into an implicit panel.
• Text around explicit skill names refines those requests. If it clearly adds a separate, unassigned concern, ask whether it belongs to a named Reviewer or a separate ad-hoc Reviewer.

Preflight all review roles before starting any Reviewer. Resolve named skills and their required review skills to absolute directories so every agent can read its skill directly even when model invocation is disabled. The runtime chooses models and reasoning effort; this skill carries no model matrix.

Schedule reviewers

Require a separate report for each review role, not a separate agent thread. Inspect available capacity and lifecycle tools, then schedule roles within a bounded pool. Reviewers inspect and report; only the orchestrator delegates.

• Prefer fresh reviewers when completed threads can be closed. Collect their final reports and close them with an available lifecycle tool before replacing them. Completion or interruption alone is not evidence of a released slot.
• When closing is unavailable, reuse idle reviewers sequentially through follow-up tasks. Each assignment names its role, current snapshot, criteria, and report-only boundary. Require a new source inspection and report; earlier conclusions are evidence to challenge, not authority. Disclose retained context and reduced independence rather than calling a reused reviewer fresh.
• On a capacity rejection, collect outstanding reports and reuse an idle reviewer. Retry spawning only after capacity or lifecycle state changes. If no reviewer can execute a required role, return incomplete; capacity never removes a role.

Record the role-to-agent assignments, peak pool size, and fresh or reused status. Preserve the round barrier across sequential assignments and composite synthesis.

Default Review Policy

Use one Review Request per row when the caller supplies no Review Brief. The mode narrows write-capable skills to report-only evaluation.

Review skill	Mode
code-review	Standards and Spec review
simplify	Report-only Composite Review Skill with Reuse, Simplification, Efficiency, and Altitude Reviewers
improve-codebase-architecture	Diff-bounded Deepening analysis using codebase-design vocabulary and one report-only exploration role; return findings without creating HTML, opening a browser, starting the grilling loop, or writing files
ask-exemplar	Embedded Evaluation

Establish the scope contract

Before the first round, derive a compact Scope Contract from the user's brief, the target's issue or PR, repository terminology, repository instructions, and relevant durable docs. Record the intended behavior, canonical terms, owned dependency or module boundary, explicit non-goals, and required verification.

A defect claim must protect a Scope Contract clause or a concrete repository standard and name a consequence in the reviewed change. Record unsupported observations as suggestions, not Verified Findings or repair work.

Run until clean

Keep the resolved Review Policy authoritative across rounds. A Full Review Round dispatches every Review Request; a Delta Review Round dispatches only the Impacted Review Requests. The first round is Full. After a repair, a clean Delta round may finish the run only when the Impacted set is demonstrably complete, every accepted claim is verified-closed, the Repair Gate passes, and the repair does not change a public interface, cross-module behavior, dependency boundary, security boundary, or contract term. Ambiguity requires a later Full round.

Maintain two compact ledgers in orchestration state, never in the target:

• The Run Ledger records each round's scope, HEAD, status, diff hash, Reviewer role-to-agent assignments and pool size, reports, target-mutation result, repairs, checks, and CI classification.
• The Claim Ledger keys each claim by location and meaning, and records its Scope Contract or repository-standard basis, provenance, evidence, required validation, and one finding state: accepted-pending, accepted-repaired, rejected with reason, unverified with evidence gap, or verified-closed. Record each proposed remedy separately with its provenance and disposition: accepted, rejected with reason, or superseded with replacement. Merge repeated claims without erasing remedy decisions. Reconsider a rejected or superseded remedy only when new evidence answers its recorded reason.

After a repair, derive the Impacted Review Requests from the repair diff. Include every request that reported an accepted claim and every request whose criteria cover the changed files, interfaces, sibling paths, or behavior. Ambiguity widens the set. When that set is the complete Review Policy, the next round is Full.

Round barrier

One Review Round owns one immutable target snapshot. Queue early Reviewer reports without acting on them. The barrier closes only after every required role reports and the target still matches the round's recorded HEAD, status, and diff hash. Direct checks, synthesis, verification, and edits start only after the barrier closes. A failed or timed-out review, or a changed target, makes the outcome incomplete; a partial round never authorizes a repair.

1. Record the target's HEAD, status, and complete diff. This opens the round barrier.
2. Select a Full or Delta round and record why each request is included. Assign every included role under Schedule reviewers. Give each reviewer the same target, base, diff scope, Scope Contract, Claim Ledger, and repository instructions. Mark ledger conclusions as prior evidence, not authority: every assigned Reviewer independently inspects the current target and may challenge them. A named-skill Reviewer reads and follows that skill and its required references; an ad-hoc Reviewer uses the Review Brief as its review criteria.
3. Require every Reviewer to inspect and report only on its assigned role, without delegation. Preserve separate angle reports for composite skills; the orchestrator applies their aggregation rules after the round barrier closes. No Reviewer may modify files, commit, comment on a forge, or push. Each finding includes its location, claim, evidence, and proposed remedy; a clean Reviewer says so.
4. Close the round barrier before continuing.
5. Route an observable claim that source inspection cannot decide to the smallest in-scope direct check. When that check is unavailable, retain one automation gap instead of redispatching the same claim as new. Claims that remain unverified are not findings and never receive fixes.
6. Pass the Synthesis Gate before editing. Merge claims by root cause while retaining every Reviewer's provenance; independently verify each hypothesis against the exact source, Scope Contract, repository standards, or observable behavior; and resolve conflicting remedies. Test each proposed remedy against the contract, likely regression paths, and sibling callers. Reject speculative hardening and scope expansion, then batch compatible smallest root-cause repairs. An unresolved remedy conflict makes the outcome incomplete.
7. Apply the synthesized repair batch as tight edits. Do not expand the target's scope or edit adjacent code without a Verified Finding.
8. Pass the Verification Gate before recording any outcome by running the Scope Contract's required verification and the smallest relevant tests, lint, and type checks. Exercise a changed output surface directly when existing tests do not observe it. After a repair, this is the Repair Gate: also independently confirm each repaired claim is absent and inspect sibling paths sharing its root cause. A code or test failure, unmet required verification, or unsafe repair makes the outcome incomplete. Treat remote CI as evidence for the reviewed snapshot only when the target has no uncommitted changes and the run's head SHA equals the round's recorded HEAD. Otherwise the run is prior context, not Verification Gate evidence. Observe matching CI when it already exists; do not wait for, trigger, or rerun it. Classify each non-successful remote CI result as a code or test failure, infrastructure or account failure, cancelled or superseded run, or unavailable evidence by inspecting executed steps and annotations. When no steps ran for an infrastructure reason, run the closest safe local equivalents and report remote CI as unavailable, never passed. Infrastructure-only CI does not block clean when those local equivalents satisfy the required verification.
9. Record the round's Review Outcome. A Full round with no Verified Findings is clean. A repaired round is fixed and starts the round selected from the Impacted Review Requests: Full when the set is the complete Review Policy, Delta otherwise. A Delta round with no Verified Findings is clean when it meets the narrow-repair closure conditions above; otherwise it is ready-for-full-review and starts a Full round. incomplete ends the run without further edits.

Continue only while each fixed round changes the target and passes the Repair Gate. A repeated Verified Finding without new evidence, or any round that cannot make a supported repair, makes the outcome incomplete instead of cycling.

Return the outcome

Include each request's selected mode and report-only preflight result in either output form, so the handoff shows which criteria and boundaries were accepted.

Choose one output form:

• For a one-round clean run, return only the compact downstream handoff. Include the policy source, exact Review Request count, Scope Contract, round scope, reviewer assignments and pool size, target and base refs, final HEAD and diff hash, checks and CI classifications, and terminal outcome once. Do not narrate the workflow separately or include empty categories; omission means the category is absent, not rendered as None.
• Otherwise, report the policy source, resolved Review Requests, Scope Contract, each round's scope and reviewer assignments, non-empty Claim Ledger states, Verified Findings, rejected claims and remedies, unverified claims and evidence gaps, superseded remedies, automation gaps, repairs, Verification and Repair Gates, checks and CI classifications, and Review Outcome. Use compact tables or lists, omit empty categories, and state repeated clean provenance once. End with a compact downstream handoff containing the target and base refs, final HEAD and diff hash, terminal outcome, non-empty repair and claim summaries, checks and CI classifications, automation gaps, and reviewer assignments.

For each repaired round, explicitly name the Synthesis Gate, Repair Gate, and fixed outcome. Give each repaired claim one ledger row containing its Reviewer provenance and complete state progression. A preflight incomplete report states that the target, repository history, and forge state remain unchanged. For each Composite Review Skill, provenance names every required role, its assigned agent, and the orchestrator's synthesis. Record peak pool size and any reviewer reuse. State the exact Review Request count and explain each Delta subset while confirming that the authoritative Review Policy remained unchanged.

Finish with exactly one terminal outcome. The downstream handoff is the sole input later history or publication skills need from this run.

• clean: a Full round on the complete current diff has no Verified Findings, or a later clean Delta round meets the narrow-repair closure conditions.
• incomplete: the requested policy could not finish safely.

Leave all repairs uncommitted. Do not commit, rebase, comment, or push. The caller owns the repository's history and publication workflows.