ControlFlow Review
Overview
Review changes by prioritizing correctness, regression risk, and evidence over style. Use this for code or completed-phase review; use controlflow-plan-audit or controlflow-assumption-verifier for pre-execution plan review.
Local Contract
- Findings first, ordered by severity, with file/line evidence and confidence.
- Distinguish validated blockers from hypotheses; state validation gaps explicitly.
- Compare implementation to the plan when one exists; scope drift is a review issue.
- Use references/review-checklist.md, references/validation-status.md, and ../controlflow-planning/references/llm-behavior-guidelines.md for shared checklist and evidence discipline.
Workflow
- Check correctness, regressions, security, data integrity, performance, and contract drift before style.
- Validate feasible suspicions with commands, file reads, or schema checks.
- Label each finding with severity, confidence, file, line, and user impact.
- Present findings first; if there are none, say so and name residual risks or test gaps.
- Use structured text, not raw JSON.
Review Axes
Check correctness/functionality, security, architecture/design, maintainability/style, and test quality/coverage. Style comments should support behavioral risk, not bury it.
Soft Comment Labels
Use Nit, Optional, and FYI only after blocking findings. These are not severity levels and must not hide correctness, security, or test coverage defects.
Change Size Caution
Large reviews lose signal. When a diff is much larger than roughly 100 changed lines or mixes unrelated concerns, ask for a split or review by file area and risk axis with an explicit confidence limit.
Review-Specific Failure Checks
- Do not lead with nits before behavior checks.
- Do not mark missing tests as
FYI when the untested behavior can regress.
- Do not state a blocker without validation evidence or an explicit unconfirmed-risk label.
References
references/evidence-discipline.mdreferences/review-checklist.mdreferences/validation-status.mdreferences/security-review-discipline.md../controlflow-orchestration/references/tdd-patterns.md../controlflow-planning/references/llm-behavior-guidelines.md
1---2name: controlflow-review3description: Use when asked to review code, a diff, or a completed phase, especially when the result should emphasize bugs, regressions, validation status, and evidence-backed findings instead of style commentary.4---5
6# ControlFlow Review
7
8## Overview
9
10Review changes by prioritizing correctness, regression risk, and evidence over style. Use this for code or completed-phase review; use `controlflow-plan-audit` or `controlflow-assumption-verifier` for pre-execution plan review.
11
12## Local Contract
13
14- Findings first, ordered by severity, with file/line evidence and confidence.
15- Distinguish validated blockers from hypotheses; state validation gaps explicitly.
16- Compare implementation to the plan when one exists; scope drift is a review issue.
17- Use [references/review-checklist.md](references/review-checklist.md), [references/validation-status.md](references/validation-status.md), and [../controlflow-planning/references/llm-behavior-guidelines.md](../controlflow-planning/references/llm-behavior-guidelines.md) for shared checklist and evidence discipline.
18
19## Workflow
20
211. Check correctness, regressions, security, data integrity, performance, and contract drift before style.
222. Validate feasible suspicions with commands, file reads, or schema checks.
233. Label each finding with severity, confidence, file, line, and user impact.
244. Present findings first; if there are none, say so and name residual risks or test gaps.
255. Use structured text, not raw JSON.
26
27## Review Axes
28
29Check correctness/functionality, security, architecture/design, maintainability/style, and test quality/coverage. Style comments should support behavioral risk, not bury it.
30
31## Soft Comment Labels
32
33Use `Nit`, `Optional`, and `FYI` only after blocking findings. These are not severity levels and must not hide correctness, security, or test coverage defects.
34
35## Change Size Caution
36
37Large reviews lose signal. When a diff is much larger than roughly 100 changed lines or mixes unrelated concerns, ask for a split or review by file area and risk axis with an explicit confidence limit.
38
39## Review-Specific Failure Checks
40
41- Do not lead with nits before behavior checks.
42- Do not mark missing tests as `FYI` when the untested behavior can regress.
43- Do not state a blocker without validation evidence or an explicit unconfirmed-risk label.
44
45## References
46
47- `references/evidence-discipline.md`
48- `references/review-checklist.md`
49- `references/validation-status.md`
50- `references/security-review-discipline.md`
51- `../controlflow-orchestration/references/tdd-patterns.md`
52- `../controlflow-planning/references/llm-behavior-guidelines.md`
gabrielmoreira