flo:review
Tiered QA review for epic implementations. Three-level criteria merge (lib + project + issue), structured findings output, bead proposals for remediation.
Quick Reference
| Tier |
Groups |
Cost |
| gate |
mechanical, hygiene |
Low — scripts, grep |
| quality |
consistency, architecture, product |
Medium — diff scan + judgment |
| polish |
security, edge-cases, production, human |
High — deep review + user action |
| Criteria level |
Location |
Merge |
| lib |
$CLAUDE_PLUGIN_ROOT/skills/review/references/criteria-lib.md |
Always runs |
| project |
.claude/review-criteria.md |
Additive |
| issue |
.issues/<key>/4-qa/CRITERIA.md |
Additive |
See $CLAUDE_PLUGIN_ROOT/skills/review/references/criteria-format.md for the criteria file format and findings output format.
Requirements
bd CLI (beads plugin active)- Git repo with an active beads epic (auto-detected via
.flo/state.yml — bootstraps on first use)
- If the epic has a linked issue directory (
.issues/<key>/): spec and design docs are used for judgment checks
- If no issue directory: the epic's own fields (description, design, notes) carry the context
Steps
1. Resolve issue context
Resolve the epic via .flo/state.yml (auto-bootstraps on first use, same as flo:next). Read the epic's design field — if it points to an issue directory, read the spec and terminology doc. If the epic has no linked issue directory, use the epic's own description and bead descriptions for judgment-based checks.
2. Discover and merge criteria
- Load built-in criteria from $CLAUDE_PLUGIN_ROOT/skills/review/references/criteria-lib.md
- Check for
.claude/review-criteria.md — if present, merge
- Check for issue-level criteria (
.issues/<key>/4-qa/CRITERIA.md) — if present, merge; skip if no issue directory
- Apply tier toggles from all levels
Report which sources were found and which tiers are enabled.
3. Determine tier
Check $ARGUMENTS for a tier name (/flo:review quality) or all.
- One tier enabled → skip prompt, run it
- Valid argument → use it
- Otherwise → AskUserQuestion with each enabled tier +
all (multiSelect)
Each tier runs independently. all runs every enabled tier.
4. Execute and write findings
- Run each group's checks against the codebase. Gate checks run commands; judgment checks read code.
- Only review the diff — never flag pre-existing code.
- Record every criterion's outcome — passes and failures both. Failures go under
## FAILING (first), passes under ## PASSING.
- Write findings: if
.issues/<key>/4-qa/ exists, write to FINDINGS.{N}.md there. Otherwise, write to .claude/review/FINDINGS.{N}.md (create the directory if needed).
- Summarize: criteria checked, findings count, groups with most findings, gate blockers.
5. Flag interactive beads
If reviewing an epic, check for open beads with the flo/interactive label. Report them in a separate section as "Awaiting human input" — do not treat them as stalled or blocked work. These beads are intentionally excluded from autonomous execution.
## Awaiting Human Input
- <bead-id>: <title> — flo/interactive (requires human-in-the-loop)
6. Propose beads
Group related findings into logical work units. Present proposed bd create commands for user approval before creating.
Common Mistakes
| Mistake |
Fix |
| Flagging pre-existing code outside the diff |
Only review changed files |
| Flagging patterns consistent with the existing codebase |
The review is not a refactor mandate — flag deviations from established patterns, not "I'd do it differently" |
| Flagging type-level circular references in TS |
Normal in TypeScript — not a smell |
| Running quality/polish before gate passes |
Gate is binary — if it fails, nothing else matters |
| Skipping the spec coverage walk |
Line-by-line requirement walk is the highest-value product check — don't summarize, walk each bullet |
| Executing human-tier checks autonomously |
Present human checks as a checklist — the agent cannot do manual E2E QA |
| Overwriting previous findings files |
Findings are append-only — always increment the file number |
1---2name: flo-review3description: Use when asked to review, audit, or QA an epic's implementation. Triggers on "review the issue", "run QA", "audit quality", or /flo:review.4---56# flo:review78Tiered QA review for epic implementations. Three-level criteria merge (lib + project + issue), structured findings output, bead proposals for remediation.910## Quick Reference1112| Tier | Groups | Cost |13| ----------- | --------------------------------------- | -------------------------------- |14| **gate** | mechanical, hygiene | Low — scripts, grep |15| **quality** | consistency, architecture, product | Medium — diff scan + judgment |16| **polish** | security, edge-cases, production, human | High — deep review + user action |1718| Criteria level | Location | Merge |19| -------------- | ------------------------------------------------------------------------------- | ----------- |20| lib | [$CLAUDE_PLUGIN_ROOT/skills/review/references/criteria-lib.md](references/criteria-lib.md) | Always runs |21| project | `.claude/review-criteria.md` | Additive |22| issue | `.issues/<key>/4-qa/CRITERIA.md` | Additive |2324See [$CLAUDE_PLUGIN_ROOT/skills/review/references/criteria-format.md](references/criteria-format.md) for the criteria file format and findings output format.2526## Requirements2728- `bd` CLI (beads plugin active)29- Git repo with an active beads epic (auto-detected via `.flo/state.yml` — bootstraps on first use)30- If the epic has a linked issue directory (`.issues/<key>/`): spec and design docs are used for judgment checks31- If no issue directory: the epic's own fields (description, design, notes) carry the context3233## Steps3435### 1. Resolve issue context3637Resolve the epic via `.flo/state.yml` (auto-bootstraps on first use, same as `flo:next`). Read the epic's `design` field — if it points to an issue directory, read the spec and terminology doc. If the epic has no linked issue directory, use the epic's own description and bead descriptions for judgment-based checks.3839### 2. Discover and merge criteria40411. Load built-in criteria from [$CLAUDE_PLUGIN_ROOT/skills/review/references/criteria-lib.md](references/criteria-lib.md)422. Check for `.claude/review-criteria.md` — if present, merge433. Check for issue-level criteria (`.issues/<key>/4-qa/CRITERIA.md`) — if present, merge; skip if no issue directory444. Apply tier toggles from all levels4546Report which sources were found and which tiers are enabled.4748### 3. Determine tier4950Check `$ARGUMENTS` for a tier name (`/flo:review quality`) or `all`.5152- One tier enabled → skip prompt, run it53- Valid argument → use it54- Otherwise → AskUserQuestion with each enabled tier + `all` (multiSelect)5556Each tier runs independently. `all` runs every enabled tier.5758### 4. Execute and write findings59601. Run each group's checks against the codebase. Gate checks run commands; judgment checks read code.612. Only review the diff — never flag pre-existing code.623. Record every criterion's outcome — passes and failures both. Failures go under `## FAILING` (first), passes under `## PASSING`.634. Write findings: if `.issues/<key>/4-qa/` exists, write to `FINDINGS.{N}.md` there. Otherwise, write to `.claude/review/FINDINGS.{N}.md` (create the directory if needed).645. Summarize: criteria checked, findings count, groups with most findings, gate blockers.6566### 5. Flag interactive beads6768If reviewing an epic, check for open beads with the `flo/interactive` label. Report them in a separate section as **"Awaiting human input"** — do not treat them as stalled or blocked work. These beads are intentionally excluded from autonomous execution.6970```71## Awaiting Human Input72- <bead-id>: <title> — flo/interactive (requires human-in-the-loop)73```7475### 6. Propose beads7677Group related findings into logical work units. Present proposed `bd create` commands for user approval before creating.7879## Common Mistakes8081| Mistake | Fix |82| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |83| Flagging pre-existing code outside the diff | Only review changed files |84| Flagging patterns consistent with the existing codebase | The review is not a refactor mandate — flag deviations from established patterns, not "I'd do it differently" |85| Flagging type-level circular references in TS | Normal in TypeScript — not a smell |86| Running quality/polish before gate passes | Gate is binary — if it fails, nothing else matters |87| Skipping the spec coverage walk | Line-by-line requirement walk is the highest-value product check — don't summarize, walk each bullet |88| Executing human-tier checks autonomously | Present human checks as a checklist — the agent cannot do manual E2E QA |89| Overwriting previous findings files | Findings are append-only — always increment the file number |
jasonkuhrt