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 in a fresh, report-only Reviewer Tree. A Leaf Review Skill
reports through one Reviewer; a Composite Review Skill may delegate the review
work it requires. Every agent in the tree inherits the same report-only boundary.
- 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 the complete Reviewer Tree 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. Reserve
enough agent slots for Composite Review Skills; serialize top-level requests
when concurrent dispatch would starve their descendants. The runtime chooses
models and reasoning effort; this skill carries no model matrix. Record each
resolved Reviewer Tree and its slot reservation for the final report.
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 descendant; 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
Tree identities and slot reservations, 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.
- Record the target's HEAD, status, and complete diff. Do not edit while
Reviewers run.
- Select a Full or Delta round and record why each request is included. Dispatch
one fresh top-level Reviewer per included Review Request, concurrently where
the preflighted nesting budget allows. Give each tree the same target, base,
diff scope, Scope Contract, Claim Ledger, and repository instructions. Mark
ledger conclusions as prior evidence, not authority: every fresh 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.
- Require every Reviewer Tree to inspect and report only. A Composite Review
Skill delegates only where required and passes the target context and
report-only boundary to every descendant. A Reviewer executing a Leaf Review
Skill or ad-hoc focus does not delegate. 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.
- Wait for every Reviewer Tree. If any agent fails or times out, or the target
changed during review, apply no orchestrator edits and return
incomplete
with the failed request or changed state.
- 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.
- 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.
- Apply the synthesized repair batch as tight edits. Do not expand the target's
scope or edit adjacent code without a Verified Finding.
- 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.
- 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
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 Tree provenance and slot reservation, 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 Tree provenance, 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 Tree provenance.
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 the top-level Reviewer and every
descendant role, and records that preflight accepted the tree with enough agent
capacity. State the exact Review Request count, identify the fresh top-level
Reviewer dispatched for each included request, 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.
1---2name: review-fix-23description: Run configurable review-and-fix rounds on a working change until clean.4disable-model-invocation: true5metadata:6 source: https://skillmd.com/skills/wkentaro/review-fix-27---89# Review fix1011Run Review Rounds until clean from a resolved Review Policy:1213```text14/review-fix [target] [free-form review brief]15```1617Examples:1819```text20/review-fix21/review-fix #12322/review-fix over-engineering23/review-fix #123 specification compliance and authorization boundaries24/review-fix ponytail-review and ask-exemplar25```2627An explicit brief chooses the Review Policy; no brief uses the Default Review28Policy. This skill owns reviewer orchestration, evidence verification, repairs,29and checks.3031## Resolve the request3233Treat the leading argument as the target only when it unambiguously resolves as34an existing Git ref, a PR or MR number in the current repository, or a PR or MR35URL. Otherwise use the current branch and working tree as the target and treat36the whole argument as the Review Brief.3738Resolve an explicit target into an editable local checkout without disturbing39uncommitted work. A target that cannot be checked out safely makes the outcome40`incomplete`. Determine the target's base from forge metadata, its upstream, or41the repository's default branch, in that order.4243When the request contains no brief, use the Default Review Policy below. This44includes a target-only request such as `/review-fix #123`.4546## Resolve the review policy4748A Review Request runs in a fresh, report-only Reviewer Tree. A Leaf Review Skill49reports through one Reviewer; a Composite Review Skill may delegate the review50work it requires. Every agent in the tree inherits the same report-only boundary.5152- Each explicitly named review skill creates one Review Request.53- Explicitly named skills replace the Default Review Policy rather than adding54 to it.55- Read each named skill during preflight. Accept leaf and composite Review Skills56 that can complete the request without writes or external mutations. Reject57 cycles and skills whose required descendants cannot be resolved or kept58 report-only.59- When no skill is named, match the brief against installed Review Skills.60 One unambiguous match uses that skill; no match creates one ad-hoc Reviewer61 from the brief; several plausible matches require native structured input to62 select one. Start no Reviewer and leave the target unchanged until selection.63 Offer a multi-skill panel only when the caller explicitly asks for multiple64 Review Requests.65- Several concerns in one skill-free brief remain one ad-hoc Review Request.66 Never split prose into an implicit panel.67- Text around explicit skill names refines those requests. If it clearly adds a68 separate, unassigned concern, ask whether it belongs to a named Reviewer or a69 separate ad-hoc Reviewer.7071Preflight the complete Reviewer Tree before starting any Reviewer. Resolve named72skills and their required review skills to absolute directories so every agent73can read its skill directly even when model invocation is disabled. Reserve74enough agent slots for Composite Review Skills; serialize top-level requests75when concurrent dispatch would starve their descendants. The runtime chooses76models and reasoning effort; this skill carries no model matrix. Record each77resolved Reviewer Tree and its slot reservation for the final report.7879### Default Review Policy8081Use one Review Request per row when the caller supplies no Review Brief. The82mode narrows write-capable skills to report-only evaluation.8384| Review skill | Mode |85| --- | --- |86| `code-review` | Standards and Spec review |87| `simplify` | Report-only Composite Review Skill with Reuse, Simplification, Efficiency, and Altitude Reviewers |88| `improve-codebase-architecture` | Diff-bounded Deepening analysis using `codebase-design` vocabulary and one report-only exploration descendant; return findings without creating HTML, opening a browser, starting the grilling loop, or writing files |89| `ask-exemplar` | Embedded Evaluation |9091## Establish the scope contract9293Before the first round, derive a compact Scope Contract from the user's brief,94the target's issue or PR, repository terminology, repository instructions, and95relevant durable docs. Record the intended behavior, canonical terms, owned96dependency or module boundary, explicit non-goals, and required verification.9798A defect claim must protect a Scope Contract clause or a concrete repository99standard and name a consequence in the reviewed change. Record unsupported100observations as suggestions, not Verified Findings or repair work.101102## Run until clean103104Keep the resolved Review Policy authoritative across rounds. A Full Review105Round dispatches every Review Request; a Delta Review Round dispatches only the106Impacted Review Requests. The first round is Full. After a repair, a clean Delta107round may finish the run only when the Impacted set is demonstrably complete,108every accepted claim is verified-closed, the Repair Gate passes, and the repair109does not change a public interface, cross-module behavior, dependency boundary,110security boundary, or contract term. Ambiguity requires a later Full round.111112Maintain two compact ledgers in orchestration state, never in the target:113114- The Run Ledger records each round's scope, HEAD, status, diff hash, Reviewer115 Tree identities and slot reservations, reports, target-mutation result,116 repairs, checks, and CI classification.117- The Claim Ledger keys each claim by location and meaning, and records its118 Scope Contract or repository-standard basis, provenance, evidence, required119 validation, and one finding state: accepted-pending, accepted-repaired,120 rejected with reason, unverified with evidence gap, or verified-closed. Record121 each proposed remedy separately with its provenance and disposition: accepted,122 rejected with reason, or superseded with replacement. Merge repeated claims123 without erasing remedy decisions. Reconsider a rejected or superseded remedy124 only when new evidence answers its recorded reason.125126After a repair, derive the Impacted Review Requests from the repair diff. Include127every request that reported an accepted claim and every request whose criteria128cover the changed files, interfaces, sibling paths, or behavior. Ambiguity widens129the set. When that set is the complete Review Policy, the next round is Full.1301311. Record the target's HEAD, status, and complete diff. Do not edit while132 Reviewers run.1332. Select a Full or Delta round and record why each request is included. Dispatch134 one fresh top-level Reviewer per included Review Request, concurrently where135 the preflighted nesting budget allows. Give each tree the same target, base,136 diff scope, Scope Contract, Claim Ledger, and repository instructions. Mark137 ledger conclusions as prior evidence, not authority: every fresh Reviewer138 independently inspects the current target and may challenge them. A139 named-skill Reviewer reads and follows that skill and its required references;140 an ad-hoc Reviewer uses the Review Brief as its review criteria.1413. Require every Reviewer Tree to inspect and report only. A Composite Review142 Skill delegates only where required and passes the target context and143 report-only boundary to every descendant. A Reviewer executing a Leaf Review144 Skill or ad-hoc focus does not delegate. No Reviewer may modify files, commit,145 comment on a forge, or push. Each finding includes its location, claim,146 evidence, and proposed remedy; a clean Reviewer says so.1474. Wait for every Reviewer Tree. If any agent fails or times out, or the target148 changed during review, apply no orchestrator edits and return `incomplete`149 with the failed request or changed state.1505. Route an observable claim that source inspection cannot decide to the151 smallest in-scope direct check. When that check is unavailable, retain one152 automation gap instead of redispatching the same claim as new. Claims that153 remain unverified are not findings and never receive fixes.1546. Pass the Synthesis Gate before editing. Merge claims by root cause while155 retaining every Reviewer's provenance; independently verify each hypothesis156 against the exact source, Scope Contract, repository standards, or observable157 behavior; and resolve conflicting remedies. Test each proposed remedy against158 the contract, likely regression paths, and sibling callers. Reject speculative159 hardening and scope expansion, then batch compatible smallest root-cause160 repairs. An unresolved remedy conflict makes the outcome `incomplete`.1617. Apply the synthesized repair batch as tight edits. Do not expand the target's162 scope or edit adjacent code without a Verified Finding.1638. Pass the Verification Gate before recording any outcome by running the Scope164 Contract's required verification and the smallest relevant tests, lint, and165 type checks. Exercise a changed output surface directly when existing tests do166 not observe it. After a repair, this is the Repair Gate: also independently167 confirm each repaired claim is absent and inspect sibling paths sharing its168 root cause. A code or test failure, unmet required verification, or unsafe169 repair makes the outcome `incomplete`.170 Treat remote CI as evidence for the reviewed snapshot only when the target has171 no uncommitted changes and the run's head SHA equals the round's recorded HEAD.172 Otherwise the run is prior context, not Verification Gate evidence. Observe173 matching CI when it already exists; do not wait for, trigger, or rerun it.174 Classify each non-successful remote CI result as a code or test failure,175 infrastructure or account failure, cancelled or superseded run, or unavailable176 evidence by inspecting executed steps and annotations. When no steps ran for177 an infrastructure reason, run the closest safe local equivalents and report178 remote CI as unavailable, never passed. Infrastructure-only CI does not block179 `clean` when those local equivalents satisfy the required verification.1809. Record the round's Review Outcome. A Full round with no Verified Findings is181 `clean`. A repaired round is `fixed` and starts the round selected from the182 Impacted Review Requests: Full when the set is the complete Review Policy,183 Delta otherwise. A Delta round with no Verified Findings is184 `clean` when it meets the narrow-repair closure conditions above; otherwise it185 is `ready-for-full-review` and starts a Full round. `incomplete` ends the run186 without further edits.187188Continue only while each `fixed` round changes the target and passes the Repair189Gate. A repeated Verified Finding without new evidence, or any round that cannot190make a supported repair, makes the outcome `incomplete` instead of cycling.191192## Return the outcome193194Choose one output form:195196- For a one-round `clean` run, return only the compact downstream handoff. Include197 the policy source, exact Review Request count, Scope Contract, round scope,198 Reviewer Tree provenance and slot reservation, target and base refs, final HEAD199 and diff hash, checks and CI classifications, and terminal outcome once. Do not200 narrate the workflow separately or include empty categories; omission means the201 category is absent, not rendered as `None`.202- Otherwise, report the policy source, resolved Review Requests, Scope Contract,203 each round's scope and Reviewer Tree provenance, non-empty Claim Ledger states,204 Verified Findings, rejected claims and remedies, unverified claims and evidence205 gaps, superseded remedies, automation gaps, repairs, Verification and Repair206 Gates, checks and CI classifications, and Review Outcome. Use compact tables or207 lists, omit empty categories, and state repeated clean provenance once. End with208 a compact downstream handoff containing the target and base refs, final HEAD and209 diff hash, terminal outcome, non-empty repair and claim summaries, checks and CI210 classifications, automation gaps, and Reviewer Tree provenance.211212For each repaired round, explicitly name the Synthesis Gate, Repair Gate, and213`fixed` outcome. Give each repaired claim one ledger row containing its Reviewer214provenance and complete state progression. A preflight `incomplete` report states215that the target, repository history, and forge state remain unchanged. For each216Composite Review Skill, provenance names the top-level Reviewer and every217descendant role, and records that preflight accepted the tree with enough agent218capacity. State the exact Review Request count, identify the fresh top-level219Reviewer dispatched for each included request, and explain each Delta subset while220confirming that the authoritative Review Policy remained unchanged.221222Finish with exactly one terminal outcome. The downstream handoff is the sole input223later history or publication skills need from this run.224225- `clean`: a Full round on the complete current diff has no Verified Findings, or226 a later clean Delta round meets the narrow-repair closure conditions.227- `incomplete`: the requested policy could not finish safely.228229Leave all repairs uncommitted. Do not commit, rebase, comment, or push. The230caller owns the repository's history and publication workflows.