bmad-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

BMad Review

BMad 审查

Review content through lenses — each a distinct method and stance — and report findings in one canonical shape. Report what is real — never pad to look thorough. Each lens sets its own stance toward the content and toward zero findings: for most an empty result is valid; the adversarial lens requires at least ten concrete findings and treats an empty list as a signal to re-check; the editorial lenses hold content sacrosanct and critique only how it is organized and expressed.

The lens set is whatever

{workflow.lenses}

resolves to, not a fixed list — overrides add lenses and replace shipped ones. Never claim a capability from this file; read the resolved lenses and work from those.

通过lens审查内容——每个lens对应一种独特的方法和立场——并以标准格式报告审查结果。只报告真实存在的问题，切勿为了显得全面而凑数。每个lens都设定了针对内容和零结果的立场：对于大多数lens而言，空结果是有效的；对抗性lens要求至少得出10个具体结果，若结果为空则需重新检查；编辑类lens认为内容本身不可侵犯，仅对内容的组织和表达方式进行批评。

lens集合由

{workflow.lenses}

解析结果决定，并非固定列表——覆盖配置可添加或替换内置的lens。切勿声称具备本文件中未明确的能力；请读取解析后的lens并基于其开展工作。

Inputs

输入

content — what to review: a diff, branch, uncommitted changes, file, spec, story, or any document. Args:
```
[path]
```
.
lenses (optional) — one or more lens codes or names, however the caller expresses them: a spoken request, or a directive of the form
```
skill:bmad-review lenses=<code>[,<code>...]
```
(the form bmm's
```
doc_standards
```
uses). Default: every applicable lens (a full review).
also_consider (optional) — areas to keep in mind alongside each lens's normal analysis.
claims (optional) — the change's own narrative: the commit messages it covers, or whatever description of it the caller supplied. Goes to the edge-case lens alone.
pre-resolved customization (optional) —
```
[workflow]
```
field values supplied by a forwarding caller. See Execution step 1.

content — 待审查内容：diff、分支、未提交的更改、文件、规格说明（spec）、用户故事（story）或任何文档。参数：
```
[path]
```
。
lenses（可选）——一个或多个lens的代码或名称，调用者可通过任意方式指定：口头请求，或采用
```
skill:bmad-review lenses=<code>[,<code>...]
```
格式的指令（bmm的
```
doc_standards
```
所使用的格式）。默认值：所有适用的lens（全面审查）。
also_consider（可选）——在每个lens的常规分析之外需要额外关注的领域。
claims（可选）——变更的说明信息：涵盖的提交信息，或调用者提供的任何变更描述。仅提供给边缘案例lens。
pre-resolved customization（可选）——由转发调用者提供的
```
[workflow]
```
字段值。请参阅执行步骤1。

Conventions

约定

Bare paths (e.g.
```
references/lens-edge-case-hunter.md
```
) resolve from
```
{skill-root}
```
— this skill's installed directory, where
```
customize.toml
```
lives.
```
{project-root}
```
resolves to the project working directory.
```
{workflow.<name>}
```
resolves to fields in
```
customize.toml
```
's
```
[workflow]
```
table (overrides win per BMad merge rules).
In
```
style_guide
```
,
```
review_guidance
```
, and
```
persistent_facts
```
, a value prefixed
```
file:
```
is a path or glob — load that file's contents. If a
```
file:
```
value cannot be read, name the failed file in the output header and continue: the shipped baseline for
```
style_guide
```
, the remaining entries otherwise.

裸路径（例如
```
references/lens-edge-case-hunter.md
```
）从
```
{skill-root}
```
解析——即本skill的安装目录，
```
customize.toml
```
所在位置。
```
{project-root}
```
解析为项目工作目录。
```
{workflow.<name>}
```
解析为
```
customize.toml
```
中
```
[workflow]
```
表的字段（根据BMad合并规则，覆盖配置优先）。
在
```
style_guide
```
、
```
review_guidance
```
和
```
persistent_facts
```
中，前缀为
```
file:
```
的值表示路径或通配符——需加载该文件的内容。若无法读取
```
file:
```
指定的文件，需在输出头部注明失败的文件，然后继续执行：
```
style_guide
```
使用内置基线，其他字段则使用剩余条目。

Execution

执行步骤

Resolve customization:
```
uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow
```
. On failure, read
```
{skill-root}/customize.toml
```
directly and use defaults. Forwarded activation: if a caller invoked you with pre-resolved customization fields (e.g. the
```
bmad-editorial-review
```
shim), honor them verbatim for those named fields — they already carry the user's overrides — and resolve only the remaining fields from your own
```
customize.toml
```
. Then execute each
```
{workflow.activation_steps_prepend}
```
entry in order, hold
```
{workflow.persistent_facts}
```
as standing context for the session, and treat
```
{workflow.review_guidance}
```
entries as standing review directives for every lens.
Load the content. Stage it once as a file: when the content is a branch, uncommitted work, or a commit range, use the repository's version-control tooling to write the unified diff to a uniquely-named file in the system temp directory and take that file's absolute path as the content. A branch means its diff against the merge base with its base branch; uncommitted work includes untracked files. Stage
```
claims
```
to its own file the same way — it is input for one lens, staged separately precisely so the other lenses never see it. If the content is empty or cannot be decoded as text: when the caller expects the raw findings JSON array (e.g. the legacy edge-case forwarder), return
```
[{"location":"N/A","trigger_condition":"Input empty or undecodable","guard_snippet":"Provide valid content to review","potential_consequence":"Review skipped — no analysis performed"}]
```
(no
```
lens
```
field) and stop; otherwise say what's wrong and ask for reviewable content. Classify the content — diff, source file, function, or document — and whether it is code or docs; scope rules and lens applicability both depend on it. A document that defines behavior (spec, requirements, plan, story) is
```
docs
```
that a behavioral lens may still apply to; judge by
```
when
```
.
Select lenses from
```
{workflow.lenses}
```
. A lens with an empty
```
instruction
```
is disabled. If the user or caller named lenses, run exactly those only —
```
applies_to
```
and
```
when
```
do not filter an explicit request. Otherwise run every enabled lens whose
```
applies_to
```
covers the content class (
```
any
```
always covers) and whose
```
when
```
applies.
Announce the plan in one line before running anything: the content class, the lenses about to run, and — when any lens has
```
after
```
set — that it runs on top of the named lens's findings. Skip the announcement entirely when the caller pinned an exact output contract (the legacy forwarders that demand raw JSON or one exact line) — their contract covers everything you emit, not just the findings block. Then execute each
```
{workflow.activation_steps_append}
```
entry in order.
Run the independent lenses — every selected lens without
```
after
```
. Each sees the content and
```
also_consider
```
, never another lens's findings. Follow each lens's
```
instruction
```
; the shipped lenses load their reference file just-in-time, so load only what runs. When subagents are available, launch every independent lens before handling any lens's result. Try running them simultaneously: spawn one per lens; give it the lens
```
instruction
```
with
```
{skill-root}
```
and paths resolved absolute, the absolute path of the staged content file (a lens prompt carries the path and the lens reads the file, never the content bytes; inline the content only when it was never staged as a file), any
```
also_consider
```
areas, the standing review directives, the
```
claims
```
path to the edge-case lens alone (marked to leave unread until its instructions call for it), and the constraint "Return ONLY your findings — no other output. Do not invoke any skill, and do not spawn subagents of your own — you are the reviewer. Return your findings as text in your final message; do not route them through any findings-reporting tool the host may offer." Otherwise run the lenses sequentially yourself, completing one before starting the next.
Run the dependent lenses — every selected lens with
```
after
```
, once the lens it names has completed, passing that lens's findings in. A lens whose
```
after
```
target was not selected or produced nothing still runs, with no prior findings. Dependent lenses that name different targets are independent of each other: launch every ready one before handling any of their results. Try running them simultaneously. When subagents are available, spawn them with the same constraint as independent lenses: "Return ONLY your findings — no other output. Do not invoke any skill, and do not spawn subagents of your own — you are the reviewer. Return your findings as text in your final message; do not route them through any findings-reporting tool the host may offer."
Assemble and present per Output below. Keep every lens's findings — overlap between lenses is signal, not duplication; note it in the markdown report rather than deduping. Execute
```
{workflow.on_complete}
```
if set.

解析自定义配置： 执行
```
uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow
```
。若执行失败，则直接读取
```
{skill-root}/customize.toml
```
并使用默认值。转发激活： 若调用者使用预解析的自定义字段（例如
```
bmad-editorial-review
```
垫片）激活您，则需严格遵循这些指定字段的值——它们已包含用户的覆盖配置——仅从自身的
```
customize.toml
```
中解析剩余字段。然后按顺序执行每个
```
{workflow.activation_steps_prepend}
```
条目，将
```
{workflow.persistent_facts}
```
作为会话的固定上下文，并将
```
{workflow.review_guidance}
```
条目作为每个lens的固定审查指令。
加载内容。 将内容暂存为单个文件：若内容为分支、未提交的工作或提交范围，则使用版本控制工具将统一diff写入系统临时目录中的唯一命名文件，并将该文件的绝对路径作为内容。分支指的是其与基准分支合并基础的diff；未提交的工作包括未跟踪的文件。以相同方式将
```
claims
```
暂存到单独文件中——它仅作为一个lens的输入，单独暂存是为了确保其他lens无法访问它。若内容为空或无法解码为文本：若调用者期望原始结果JSON数组（例如旧版边缘案例转发器），则返回
```
[{"location":"N/A","trigger_condition":"Input empty or undecodable","guard_snippet":"Provide valid content to review","potential_consequence":"Review skipped — no analysis performed"}]
```
（不含
```
lens
```
字段）并停止执行；否则说明问题所在，并请求提供可审查的内容。对内容进行分类——diff、源文件、函数或文档——以及判断其属于code还是docs；范围规则和lens的适用性均取决于此分类。定义行为的文档（spec、需求、计划、用户故事）属于
```
docs
```
，行为类lens可能仍适用于此类文档；需根据
```
when
```
进行判断。
从
{workflow.lenses}
中选择lens。
```
instruction
```
为空的lens处于禁用状态。若用户或调用者指定了lens，则仅运行这些指定的lens——
```
applies_to
```
和
```
when
```
不会过滤明确的请求。否则，运行所有已启用且
```
applies_to
```
覆盖内容分类（
```
any
```
始终覆盖）、同时
```
when
```
条件适用的lens。
宣布计划：在执行任何操作前，用一行文字说明计划：内容分类、即将运行的lens，以及——若有lens设置了
```
after
```
——该lens将基于指定lens的结果运行。若调用者指定了精确的输出契约（例如要求原始JSON或特定单行输出的旧版转发器），则完全跳过此宣布步骤——其契约涵盖您输出的所有内容，而非仅结果块。然后按顺序执行每个
```
{workflow.activation_steps_append}
```
条目。
运行独立lens——所有未设置
```
after
```
的已选lens。每个独立lens仅能访问内容和
```
also_consider
```
，无法访问其他lens的结果。遵循每个lens的
```
instruction
```
；内置lens会实时加载其参考文件，因此仅加载运行所需的文件。若有子代理可用，则在处理任何lens的结果前启动所有独立lens。尝试同时运行它们：为每个lens生成一个子代理；向其提供已解析绝对路径的
```
{skill-root}
```
和路径、暂存内容文件的绝对路径（lens提示仅携带路径，由lens自行读取文件，绝不传递内容字节；仅当内容未被暂存为文件时才内嵌内容）、所有
```
also_consider
```
领域、固定审查指令、仅提供给边缘案例lens的
```
claims
```
路径（标记为在指令要求前不得读取），以及约束条件：“仅返回您的审查结果——不得输出其他内容。不得调用任何skill，也不得生成自己的子代理——您就是审查者。在最终消息中以文本形式返回结果；不得通过宿主提供的任何结果报告工具传递结果。” 若没有子代理可用，则自行按顺序运行lens，完成一个后再启动下一个。
运行依赖lens——所有设置了
```
after
```
的已选lens，需在其指定的lens完成后运行，并传入该lens的结果。若
```
after
```
目标未被选中或未产生任何结果，该依赖lens仍会运行，但不会获得任何前置结果。指定不同目标的依赖lens彼此独立：在处理任何结果前启动所有已准备好的依赖lens。尝试同时运行它们。若有子代理可用，则以与独立lens相同的约束条件生成子代理：“仅返回您的审查结果——不得输出其他内容。不得调用任何skill，也不得生成自己的子代理——您就是审查者。在最终消息中以文本形式返回结果；不得通过宿主提供的任何结果报告工具传递结果。”
组装并呈现结果：按照下方的输出要求进行。保留每个lens的结果——不同lens结果的重叠是重要信号，而非重复内容；需在markdown报告中注明重叠情况，而非去重。若设置了
```
{workflow.on_complete}
```
，则执行该操作。

Output

输出

One JSON array holding every finding from every lens. Each finding carries:

```
lens
```
— the code of the lens that produced it
```
location
```
— where in the content (file:line-range for code, section for documents)
```
trigger_condition
```
— the problem, or the condition that exposes it, in one line
```
guard_snippet
```
— the concrete fix, guard, or missing check
```
potential_consequence
```
— what goes wrong if it ships as-is

Each lens file refines these semantics for its findings and may add lens-specific fields (e.g.

kind

confidence

on deletion findings,

gap_shape

consumer

evidence

on verification-gap findings). A lens file may instead declare its own findings shape and rendering — the editorial lenses render a findings table — and that shape wins for that lens's findings.

[]

is valid when nothing is found. No severity, priority, or ranking anywhere.

Present per

{workflow.output_format}

—

"json"

(the raw array in a fenced json block),

"markdown"

, or

"both"

— unless the caller requested a specific shape; a legacy forwarder's output contract always wins, and governs everything you emit rather than the findings block alone. The markdown report groups findings by lens, each rendered in its declared shape: a short block per finding rendering the fields plus any extras worth surfacing, one line for a lens that found nothing, and a plain clean statement when the whole review is clean. Shape the report per

{workflow.output_preferences}

When

{workflow.report_path}

is set, write the report there; otherwise present it in chat.

包含所有lens结果的JSON数组。每个结果包含以下字段：

```
lens
```
— 生成该结果的lens代码
```
location
```
— 结果在内容中的位置（代码为文件:行范围，文档为章节）
```
trigger_condition
```
— 问题或暴露问题的条件，单行描述
```
guard_snippet
```
— 具体修复方案、防护措施或缺失的检查项
```
potential_consequence
```
— 若按当前状态发布可能导致的问题

每个lens文件会针对其结果细化这些语义，并可能添加lens专属字段（例如删除结果中的

kind

confidence

，验证缺口结果中的

gap_shape

consumer

evidence

）。lens文件也可自行声明结果格式和渲染方式——编辑类lens会渲染结果表格——该格式将优先用于该lens的结果。若未发现任何问题，

[]

是有效的输出。结果中不得包含严重程度、优先级或排名信息。

根据

{workflow.output_format}

呈现结果——

"json"

（在围栏代码块中显示原始数组）、

"markdown"

或

"both"

——除非调用者指定了特定格式；旧版转发器的输出契约始终优先，且涵盖您输出的所有内容，而非仅结果块。markdown报告按lens分组呈现结果，每组以其声明的格式渲染：每个结果为一个短块，包含字段及任何值得展示的额外信息；未发现问题的lens显示一行说明；若整个审查无问题，则显示简洁的声明。根据

{workflow.output_preferences}

调整报告格式。

若设置了

{workflow.report_path}

，则将报告写入该路径；否则在聊天中呈现报告。