| name | check-review-loop |
| description | Phase 6 review-fix loop — run an independent (adversarial) reviewer, track each finding as a checklist in evidence, then loop fix -> re-review until every finding is resolved. The review counterpart of check-qa. Use when: a child-task diff is coded and needs review before verify, driving review findings to closure, the Phase 6 review gate, or any change that must not self-review. |
One-Liner
Review is a converging loop, not a one-shot pass: an independent reviewer files findings as a
tracked checklist, and the gate stays shut until every - [ ] is fixed or consciously accepted.
Input: a coded child-task diff. Output: a ## Review section in docs/design-docs/<id>/evidence.md
where every finding is resolved ([x]), and the code fixed accordingly.
This is to review what check-qa is to tests: a tracked, capped,
converging loop — not a one-shot pass.
1. Independent review — role-based, no self-review
The reviewer is not a faceless agent: resolve its role from the design, spawn it on the
strong tier, and bracket the review with CLI-recorded provenance. The author must never review
their own code.
- Resolve the role from the design. Run the role-resolver against the Stack block:
bash .harness/skills-src/scripts/role-resolver.sh --phase review --stack docs/design/architecture.md
→ a spec like {title:"Go Backend Tech Lead", expertise:["dev-be","dev-go","golang-pro"], mandate:…} (see ../../resources/phase-roles.md). The reviewer
is a tech lead in the project's actual language/component, not a generic agent.
- Open provenance.
harness review open <id> --phase review --role '<spec>' mints a one-time
nonce, binds the current diff-hash, and prints the role brief to inject.
- Spawn the reviewer with the spawn-subagents capability
(../../resources/agent-tool-mapping.md), injecting the
role title + mandate + the
expertise SKILL.md chain to load. It applies the
check-code-review dimensions (correctness, security, contract,
scope, clarity) and is prompted to try to find problems, not to approve.
- Record the verdict.
harness review record <id> --nonce <n> --verdict clean|findings --findings <N> stamps provenance bound to the reviewed diff — this is what the
review-provenance-gate checks at verify.
- Fallback: no subagent capability → a fresh-context pass that sees only the diff + design
docs (not the author's reasoning); still
open/record provenance and note the fallback in the
evidence.
2. Record findings as a tracked checklist
Write each finding to evidence ## Review as a checkbox so its resolution is durable and gate-checkable:
## Review
- [ ] <finding> (file:line, severity) # open — must be resolved
- [x] <finding> (file:line) — fixed in <commit/diff>
- [x] <finding> — (accepted: <reason>) # consciously accepted, with rationale
- [ ] = open · - [x] = fixed or consciously accepted (reason required). "No issues found"
(with a one-line justification of what was checked) is valid when the reviewer is genuinely clean.
3. Fix -> re-review loop
- For each
- [ ] finding: make the minimal fix (or mark - [x] (accepted: reason) with the
user's agreement), updating the checkbox.
- Re-run the independent review on the new diff — a fix can introduce a new issue.
- Repeat until no
- [ ] remains.
4. Cap & escalation
Cap at 3–5 iterations. If findings keep reopening after the cap, stop and ask-user with the
open list and a hypothesis — never mark a finding resolved without actually addressing it, and never
delete a finding to pass the gate.
Gate
Two complementary gates guard harness verify <id>:
review-fix-gate blocks while any - [ ] remains in ## Review (the tracked checklist proves
what was found and that it was resolved).review-provenance-gate blocks unless an independent review provenance is recorded and CURRENT
— its diff-hash still matches the working tree. A fix made after the review makes it STALE and
re-opens the gate (re-run step 1 on the new diff). This proves an independent role reviewer
actually ran on this exact diff, not just that text was written into evidence.
Pairs with check-qa (tests) before verify. Persona: Non-Technical gets a plain-language
"found and fixed N issues"; Developer gets the full finding trail.
