170 lines
12 KiB
Markdown
170 lines
12 KiB
Markdown
---
|
||
name: review-fix-loop
|
||
description: Run a review-and-fix loop on a path or on a branch's changes vs main. Each round a fresh reviewer subagent reviews the code with the code-review skill and returns severity-tagged findings and a verdict; you fix every blocker and major as the front-end-architect skill, or push back with a concrete reason, run lint, type-check, and tests, and hand the reviewer a changelog. Repeats until the reviewer approves, 5 rounds pass (or the limit the user sets), or a dispute needs the user, then reports every finding's status in a table. Use when the user asks to review and fix, review until approved, run review rounds, iterate on review feedback, or get a branch, PR, or folder merge-ready with a reviewer, even without the word "loop". Not for a one-time review with no fixes (use code-review alone).
|
||
---
|
||
|
||
# Review-fix loop
|
||
|
||
Run rounds between two roles until the code is approved:
|
||
|
||
- **Reviewer:** a fresh subagent each round that uses the code-review skill. It sees only the code, its previous round's findings, and your short changelog. It never sees your reasoning, so its approval is an independent check, not an echo of yours.
|
||
- **Fixer:** you, acting as the front-end-architect skill. Fixes follow the project's architecture, and every pushback cites something the reviewer can check.
|
||
|
||
The goal is code the reviewer approves with nothing hidden: no weakened check, no silent change of scope, no disagreement left unstated.
|
||
|
||
## 1. Setup (once)
|
||
|
||
1. **Target.** Use the path the user gave. With none, use the changes on this branch vs `main` (use the remote's default branch when there is no `main`).
|
||
- Branch: `BASE=$(git merge-base main HEAD)`. The scope is `git diff --name-only $BASE` plus the untracked files in `git status --porcelain`. It holds committed and uncommitted changes, so your fixes stay in view in later rounds.
|
||
- Path: the scope is every file under it.
|
||
- With an empty scope, tell the user and stop. The scope stays the same for the whole loop; files your fixes touch join it.
|
||
2. **Fixer skill.** Load front-end-architect through the Skill tool when it is listed; otherwise read its `SKILL.md` (look in `.claude/skills/`, `~/.claude/skills/`, and `skills/`). Follow its "How to read references": open a reference section only when a fix needs it. If you can't find the skill, tell the user and ask before going on, because fixes and pushbacks depend on its rules.
|
||
3. **Checks.** Find the lint, type-check, and test commands for the affected projects. In an Nx repo use `nx affected -t <targets> --base=$BASE`, with target names from `nx show project <name>`; otherwise use the `package.json` scripts. Run them once as a baseline before round 1:
|
||
- A failure in a scope file: fix it now, and list it as a pre-loop fix in the report. The reviewer would block it anyway.
|
||
- A failure outside the scope (it fails on the base too): show the command and the shortest decisive error line, and ask whether to fix it first or to use "no new failures" as the bar.
|
||
- A check the repo doesn't have: note it in the report. Don't invent one.
|
||
4. **No commits.** Leave changes in the working tree unless the user asked you to commit. The reviewer reads the working tree.
|
||
|
||
Keep a ledger through the loop: each finding's ID, severity, status, location or reason, and how many times you disputed it. The final report comes from it.
|
||
|
||
## 2. Each round
|
||
|
||
Rounds are numbered 1 to 5, or to the limit the user sets (section 3).
|
||
|
||
### Step 1: Review
|
||
|
||
Spawn a new general-purpose subagent (it needs the Skill tool) and wait for its reply. Its prompt is the reviewer brief in section 4, filled in with the round number, the target, and, from round 2, the previous reviewer's reply and your changelog. Pass nothing else: no front-end-architect rules, no plan, no discussion of fixes. Never resume an earlier reviewer, because one that remembers its own reasoning anchors on it. If you can't spawn a subagent, stop and tell the user: reviewing your own fixes defeats the loop.
|
||
|
||
Check the reply before you use it:
|
||
|
||
- Every finding has an ID, a severity, a `file:line`, a problem, and a suggested fix, and the last line is a verdict line. If not, ask the same reviewer once to reformat only. That doesn't count as a round.
|
||
- The verdict follows the findings: any open blocker or major, new or kept open, means `CHANGES_REQUESTED`, whatever the verdict line says.
|
||
|
||
Tell the user one line per round: the round, the open findings by severity, and the verdict.
|
||
|
||
### Step 2: Approved?
|
||
|
||
If the verdict is `APPROVED`, go to the final report.
|
||
|
||
### Step 3: Fix
|
||
|
||
Address every open blocker and major, new or kept open. Each one gets a fix or a dispute.
|
||
|
||
- **Fix** the problem in the layer that owns it, with the smallest change that resolves it fully and follows front-end-architect's rules. Read the code first. The suggested fix is a suggestion: a different fix that solves the problem is fine, and the changelog says what you did.
|
||
- **Dispute** only with a reason a third party can check: a front-end-architect rule (name its section), an accepted entry in `docs/decisions/`, or a fact in the code with its location ("the value is validated at `schemas.ts:12`"). Taste, effort, and "out of scope" are not reasons to leave a real bug. If the reviewer is right, fix it, and tell the user when the fix is large.
|
||
- **Minors and nits:** fix one when it is cheap (a few lines, no behavior risk, no new file). Otherwise defer it with a one-line reason. Blockers and majors can't be deferred.
|
||
|
||
Two rules keep the loop honest:
|
||
|
||
- Never pass a check by weakening it: no `eslint-disable` or `oxlint-ignore` comments, `@ts-ignore` or `@ts-expect-error`, `as any`, skipped or deleted tests, or loosened assertions. They hide the bug, and the reviewer would flag them anyway. If one really is the right fix, say so in the changelog.
|
||
- Change only what a finding asks for. Write other problems you see as follow-ups in the report instead of fixing them silently, so every change the reviewer sees traces to a finding.
|
||
|
||
**Dispute limit.** If you would dispute a finding that the reviewer already kept open after your earlier dispute, it has stayed disputed for 2 rounds. Finish the round's other fixes and step 4, then stop and ask the user: show the finding, the reviewer's reasoning, your reason, and the options. Don't start another review. The user's decision binds both roles: apply it, write `R1-4 decided by user: <decision>` in the changelog, and continue with the next round if rounds remain.
|
||
|
||
### Step 4: Verify
|
||
|
||
Run the baseline checks again. Every check must pass, or show no new failures when the user chose that bar. Fix a failure under the same rules as a finding, then run the checks again. If they still fail after 3 attempts, stop and report: never hand failing code to the reviewer.
|
||
|
||
### Step 5: Changelog
|
||
|
||
Write one line for each finding you acted on, in ID order, for the next round:
|
||
|
||
```
|
||
R1-2 fixed in src/atoms/button/Button.tsx:40: the disabled state now sets aria-disabled
|
||
R1-4 disputed: island rule "never restyle an island component in a feature; add a variant" (front-end-architect section 3)
|
||
R1-6 deferred: renaming the hook touches 12 files outside the scope
|
||
```
|
||
|
||
## 3. Stop conditions
|
||
|
||
- The verdict is `APPROVED`.
|
||
- The last round's review (round 5, or the user's limit) returned `CHANGES_REQUESTED`. Don't fix after the last review: no reviewer would check those fixes, and the report would show unreviewed work as done.
|
||
- A finding stayed disputed for 2 rounds. Ask the user (step 3).
|
||
- The checks still fail after 3 attempts (step 4).
|
||
|
||
The limit is 5 rounds. The developer can set another one in the prompt ("at most 3 rounds", "up to 8 rounds").
|
||
|
||
## 4. Reviewer brief
|
||
|
||
Fill in the angle brackets. In round 1, delete the parts marked `(round 2+)`; in later rounds, delete only the markers. Send the rest unchanged.
|
||
|
||
````
|
||
You are the reviewer in round <N> of a review-and-fix loop. Another agent fixes the code. You never edit files.
|
||
|
||
TARGET
|
||
<one of:>
|
||
- Path: <path>. Review every file under it.
|
||
- The changes on this branch vs <base branch>: `git diff <BASE>` for tracked files, plus the untracked files in `git status --porcelain`.
|
||
Scope files: <list>
|
||
Review the working tree as it is now, committed and uncommitted.
|
||
|
||
HOW
|
||
1. Review the target with the code-review skill (Skill tool, skill "code-review", args: the target<, plus the effort level if the user gave one>). Never pass --fix, --comment, or ultra. The review must cover the whole scope: if code-review's target covers less (for example, only uncommitted changes), review the rest yourself the same way. If the skill is unavailable, review the code yourself for correctness, security, performance, accessibility, and maintainability.
|
||
2. Confirm every finding in the code before you report it. Drop what you can't confirm.
|
||
3. (round 2+) Check each previous finding in the code itself, not in the changelog's claims:
|
||
- Claimed fixed: resolved if the problem is gone and the fix adds no new problem. Otherwise keep it open and say what remains.
|
||
- Disputed: accept if the reason holds (read the rule or file it cites). Otherwise keep it open and answer its reason.
|
||
- Deferred: accept for a minor or nit. A blocker or major can't be deferred; keep it open.
|
||
- Decided by the user: accept.
|
||
A previous finding missing from the changelog stays open unless the problem is gone. Never report a previous problem again as new; use its ID.
|
||
|
||
SEVERITY
|
||
- blocker: a bug in a main path, a security hole, data loss, a crash, a broken build or type-check, or a broken project rule that blocks merge (CLAUDE.md, docs/decisions).
|
||
- major: a bug in an edge case; a missing error, loading, or empty state; a performance or bundle-size regression; an accessibility failure; a design that will cause bugs.
|
||
- minor: works, but worse than it should be: unclear code, small duplication, a missing test for a non-critical path.
|
||
- nit: style, naming, taste.
|
||
|
||
OUTPUT
|
||
Reply with only this. Whatever code-review says about reporting, the fixer reads only your final message.
|
||
|
||
PREVIOUS (round 2+)
|
||
- R1-2: resolved
|
||
- R1-4: kept open: <reasoning, 1–2 sentences>
|
||
- R1-5: dispute accepted: <why>
|
||
- R1-6: deferral accepted
|
||
|
||
NEW
|
||
- id: R<N>-1
|
||
severity: blocker | major | minor | nit
|
||
file:line: <path>:<line>
|
||
problem: <1–2 sentences>
|
||
suggested fix: <concrete change>
|
||
(or "NEW: none")
|
||
|
||
End with exactly one of these lines:
|
||
VERDICT: APPROVED (no blocker or major is open, new or kept open)
|
||
VERDICT: CHANGES_REQUESTED (otherwise)
|
||
|
||
PREVIOUS ROUND'S FINDINGS (round 2+)
|
||
<the previous reviewer's reply, verbatim>
|
||
|
||
CHANGELOG (round 2+)
|
||
<your changelog>
|
||
````
|
||
|
||
## 5. Final report
|
||
|
||
Reply with this, filled in from the ledger:
|
||
|
||
```
|
||
## Review-fix loop: <target>
|
||
|
||
| ID | Severity | Status | Where fixed / reason |
|
||
|---|---|---|---|
|
||
| R1-1 | blocker | fixed | src/atoms/button/Button.tsx:40 |
|
||
| R1-4 | major | disputed (accepted) | island rule: add a variant, never restyle |
|
||
| R2-1 | major | disputed (open) | see Open disagreements |
|
||
| R1-6 | nit | deferred | the rename touches 12 files outside the scope |
|
||
|
||
Rounds: <n> of <limit, 5 by default>. Stopped because: <approved | round limit | dispute needs your decision | checks fail>.
|
||
Checks: <commands>: <pass | which failed>.
|
||
Changed files (uncommitted): <list>
|
||
|
||
Open disagreements
|
||
- R2-1 (major): <problem>. Reviewer: <reasoning>. Me: <reason>. Decide: <option A> or <option B>.
|
||
|
||
Follow-ups: <problems seen outside the findings, or "none">
|
||
```
|
||
|
||
Statuses: `fixed`; `disputed (accepted)`, when the reviewer accepted your reason; `disputed (open)`; `deferred`; `decided by user`; and `open`, for a finding unresolved at the round limit or when the checks fail. List pre-loop fixes as their own rows with IDs `pre-1`, `pre-2`. When the loop ends, offer to commit the changes.
|