Review choices

Use this when the user asks how much review to run, how to get another pass, when to stop, why review is slow, or how to change review.

Review depth in bmad-build and bmad-build-auto

• none: no reviewers. Reasonable for a throwaway prototype.
• quick: one reviewer checks acceptance criteria, the repo's agent rules, and bugs.
• thorough: four independent lenses covering the bare diff, edge cases, test gaps, and intent alignment.
• Default: quick. auto follows the route: quick for oneshot, thorough for full. The user picks by saying "quick", "thorough", or "skip review" when invoking.
• thorough suits a change that is unusually risky or makes many design decisions.
• It fixes clear findings itself, asks the user when the intent cannot settle one, and logs pre-existing issues to deferred-work.md.

Another pass, and when to stop

• After bmad-build: hand bmad-build the plan it left at built. It goes straight to review and triage, at the depth named in the request, and can be repeated. bmad-build does not resume a done plan; hand that one to bmad-code-review.
• After bmad-build-auto: dispatch its built plan again.
• Worth it after material fixes, or when an unattended run set followup_review_recommended. After a thorough build review it only repeats the same lenses.
• The depth a build ran at, skipped included, is the user's choice and no reason for another pass.
• At the end of an epic, bmad-retrospective is the thorough pass: it runs the review lenses over the epic's diff and proposes fixes as action items.
• Stop when findings are mostly minor notes about unlikely corner cases.
• Real findings on a third pass point outside the change: a weak spec or unclear repo rules. Tell the user to fix that.

bmad-code-review

• Target: a PR, commit, branch, commit range, uncommitted changes, a pasted diff, or files.
• Tell the user to supply the intent: a ticket, a plan, or a plain description. A ticket in review brings its plan; both are read in full. Without it the reviewers can only judge the diff against itself.
• Defaults to thorough; "quick" uses one reviewer. Above about 3000 diff lines it offers to review in file groups.
• Triage checks every finding against the code and rejects disproved ones, plus low ones whose fix would add complexity.
• Survivors become patch (a clear fix), defer (pre-existing or unverified), or decision needed (when the right fix depends on what you meant).
• The user chooses: apply all patches, walk through each, or leave them as action items in the plan's ## Code Review section.

Why review is slow

• It is thorough on purpose and can take half an hour or more. Offer quick.
• AGENTS.md has too many rules, or source files are very large. Reviewers read both.
• The platform has no subagents or runs them one at a time.

bmad-walkthrough: the human reviews

Recommend it when a person must understand and accept a change: after a build, at the end of an epic, or on someone else's PR. It walks the change in blocks, intent first, and stays on a block until the user says it is done. It gives no severity and no verdict. It is the human's review pass: the findings come from the person, not from the agent. bmad-code-review and bmad-retrospective are the agentic passes over the same change.

For tickets and other documents, bmad-review (core tools), if installed, reports findings and fixes nothing.

What bmad-customize can change

• The default depth, separately for bmad-build, bmad-build-auto, and bmad-code-review.
• The lenses: add, replace, disable, or run one on another model.
• bmad-walkthrough: instructions at start, per block, and at wrap-up.