docs: followup_review_recommended is now scored upstream (BMAD-METHOD#2580)

[pbean]

What

Prose-only refresh after upstream BMAD-METHOD#2580 merged. No behavior change — limits.max_followup_reviews (default 1) and all code paths stay as they are.

• README / FEATURES / TUI guide / [review].enabled description — stop hardcoding the layer count ("triple-review", "three-layer", "Blind + Edge-Case hunters") and the old judgment wording. The skill's default review layers are four now (the inline Intent Alignment Auditor landed in #2560), and followup_review_recommended is computed from a severity-weighted score over the final pass's patched findings (any high, or 3×medium + 1×low ≥ 5) instead of a significance judgment.
• engine.py damping comments — mark "every review pass patches findings and recommends another pass" as the historical (pre-#2580) motivation rather than present-tense fact.
• README policy example — the [review].enabled comment said "quick-dev's own internal triple-review"; the loop drives bmad-dev-auto, fixed alongside.

Why

Our #126→#124 damping work documented the upstream non-convergence as a live failure mode. #2580 fixes it at the source (closing our #2576 and #2570) and explicitly leaves "budgeting and damping" to the orchestrator — so the knob remains as the orchestrator-side bound, now belt-and-suspenders, and the docs should say so.

Testing

• Full suite: 2224 passed, 1 skipped.
• trunk check: no issues.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Changed

  • Recommended follow-up reviews are now based on the severity of patched findings.
  • Review workflows now include four parallel adversarial review layers, including intent alignment.
  • Dedicated review sessions remain bounded by the configured maximum review limits.
  • Review settings now clearly distinguish inline development reviews from separate adversarial review sessions.

• Documentation

  • Updated the README, feature guide, TUI guide, and settings descriptions to reflect the revised review flow and recommendation criteria.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ffb607d6-a491-4388-a5a6-d728c0c4a154

📥 Commits

Reviewing files that changed from the base of the PR and between eb780d5 and bfda022.

📒 Files selected for processing (6)

• CHANGELOG.md
• README.md
• docs/FEATURES.md
• docs/tui-guide.md
• src/bmad_loop/data/settings/core.toml
• src/bmad_loop/engine.py

---

Walkthrough

Documentation, settings descriptions, and engine comments now describe severity-weighted followup_review_recommended semantics, four review layers, inline development reviews, and existing review limits. Runtime control flow remains unchanged.

Changes

Review semantics

Layer / File(s)	Summary
Review workflow and trigger documentation CHANGELOG.md, README.md, docs/FEATURES.md	Documentation describes severity-weighted recommendations, inline development review layers, four adversarial layers, and unchanged review bounds.
Settings descriptions and engine commentary docs/tui-guide.md, src/bmad_loop/data/settings/core.toml, src/bmad_loop/engine.py	Settings text and engine comments explain dedicated versus inline reviews and follow-up damping without changing executable logic.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Poem

A rabbit reviews with a hop and a score,
Four layers now guard the story’s door.
Inline thoughts bloom in the dev-pass bright,
A fresh gated review follows when right.
The old bounds still keep cycles in flight.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main documentation update about upstream scoring of followup_review_recommended.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/followup-scoring-2580

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}