bmad-review

Review diffs, code, and documents through configurable analysis lenses producing structured findings.

Updated Sep 3, 2026
One-click install
npx skills add https://github.com/watchthelight/shatterfish --skill bmad-review-watchthelight
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: bmad-review
Source: https://github.com/watchthelight/shatterfish/tree/main/.claude/skills/bmad-review
Command: npx skills add https://github.com/watchthelight/shatterfish --skill bmad-review-watchthelight

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Reviews of code changes and documents are often shallow or inconsistent, missing edge cases, verification gaps, or structural problems. This Skill runs a disciplined multi-lens review over any diff, spec, or document and returns findings in one canonical, actionable shape. ## Core Features & Use Cases - Multi-lens review: Ships adversarial, edge-case, verification-gap, structure, and prose lenses that run singly or together, selected automatically by content type or explicitly by name. - Canonical findings output: Every finding carries location, trigger condition, guard snippet, and potential consequence, rendered as JSON, markdown, or both. - Customizable workflow: A customize.toml file controls lenses, style guides, review guidance, output format, and report destination, with team and personal override files. - Use Case: Ask for a critical review of a pull request diff; the edge-case hunter enumerates unhandled branches, the verification-gap lens checks whether tests would catch a regression, and the adversarial lens surfaces at least ten concrete issues. ## Quick Start Ask the assistant to review a file or diff, for example: run a full review of the changes in my current branch and report the findings.

Frequently Asked Questions about bmad-review

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I review a code diff for edge cases?

Invoke the review with the diff as content and the edge-case-hunter lens selected. It walks every branch and boundary in the diff hunks, reports only unhandled paths, and emits findings with location, trigger condition, guard snippet, and potential consequence.

What review lenses are included and how do I choose them?

Shipped lenses are adversarial, edge-case-hunter, verification-gap, structure, and prose. Name lenses explicitly to run exactly those, or omit the selection to run every lens whose applies_to and when rules match the content type.

Can I customize the review output format and style guide?

Yes. The customize.toml workflow table sets output_format (json, markdown, or both), report_path, style_guide, reader_type, and standing review_guidance. Team and personal override TOML files merge on top per BMad structural rules.

Does the verification-gap lens work outside a code repository?

No. The verification-gap lens applies only to code reviewed inside a repo where tests can be searched and read, since it must trace changed behavior to consumers and inspect the tests that would catch a regression.

Why does the adversarial lens never return zero findings?

The adversarial lens requires at least ten concrete findings and treats an empty list as a signal to re-check the content. Other lenses, like edge-case-hunter and verification-gap, validly return an empty array when nothing is found.