design-decision-audit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Design Decision Audit

设计决策审计

Overview

概述

Use this skill to audit a design document before implementation. The job of this skill is to find missing or weak design decisions, explain the risk, and propose targeted additions.

This skill does not directly edit the design document unless the user explicitly asks for that in a later step.

使用本技能在实现前审计设计文档。本技能的作用是找出缺失或不完善的设计决策，说明风险，并提出针对性的补充建议。

除非用户在后续步骤中明确要求，否则本技能不会直接编辑设计文档。

Inputs

输入

Required input:

A design document path, design document content, or both

Optional input:

Extra context paths such as related design docs, implementation plans, or requirement notes

必填输入：

设计文档路径、设计文档内容，或两者皆有

可选输入：

额外上下文路径，如相关设计文档、实现计划或需求说明

Language Strategy

语言策略

Match the audit language to the user's instruction language.

Use this priority order:

An explicit output-language request from the user
The dominant natural language of the user's current instruction
The dominant natural language of the most recent user instructions in the same task
English if the signal is weak or ambiguous

Rules:

Keep the chat response and any saved report in the same language
Translate section headings into the chosen output language
Keep file paths, code identifiers, and literal config keys unchanged
Do not mix languages unless the user explicitly asks for bilingual output

Default heading examples:

If the output language is English:

```
Executive Summary
```
```
Triggered Modules
```
```
Findings
```
```
Suggested Additions
```
```
Open Questions
```
```
Report Path
```

If the output language is Chinese:

```
Executive Summary
```
→ translate heading
```
Triggered Modules
```
→ translate heading
```
Findings
```
→ translate heading
```
Suggested Additions
```
→ translate heading
```
Open Questions
```
→ translate heading
```
Report Path
```
→ translate heading

审计语言与用户指令语言保持一致。

遵循以下优先级顺序：

用户明确指定的输出语言请求
用户当前指令的主导自然语言
同一任务中用户最近指令的主导自然语言
若信号较弱或模糊，默认使用英文

规则：

聊天回复和保存的报告使用同一种语言
将章节标题翻译成选定的输出语言
保留文件路径、代码标识符和字面配置键不变
除非用户明确要求双语输出，否则不要混合语言

默认标题示例：

若输出语言为英文：

```
Executive Summary
```
```
Triggered Modules
```
```
Findings
```
```
Suggested Additions
```
```
Open Questions
```
```
Report Path
```

若输出语言为中文：

```
Executive Summary
```
→ 执行摘要
```
Triggered Modules
```
→ 触发模块
```
Findings
```
→ 审计发现
```
Suggested Additions
```
→ 建议补充内容
```
Open Questions
```
→ 待解决问题
```
Report Path
```
→ 报告路径

Minimal Prompt Handling

极简提示处理

Do not require the user to spell out the full audit scope.

If the user gives a short instruction such as:

```
review <file>.md
```
```
audit <file>.md
```
```
check <file>.md
```

infer a full design-decision audit when the target appears to be one of these:

design doc
architecture proposal
implementation plan
checklist-backed review doc
proposal or decision record

Strong clues include:

filename terms such as

design

review

plan

proposal

architecture

decision

repo locations such as
```
docs/
```
,
```
design-docs/
```
,
```
exec-plans/
```
,
```
proposals/
```
document content that describes rollout, schema, compatibility, migration, states, jobs, or observability

When a short prompt names a markdown file but the document type is still unclear:

open the file first
if the file reads like a design, plan, or architecture doc, proceed with the audit
ask a clarifying question only if the file is clearly not design-adjacent and running this skill would likely be wrong

无需用户明确说明完整的审计范围。

如果用户给出如下简短指令：

```
review <file>.md
```
```
audit <file>.md
```
```
check <file>.md
```

当目标文件属于以下类型时，默认执行完整的设计决策审计：

设计文档
架构提案
实现计划
基于检查清单的评审文档
提案或决策记录

强烈线索包括：

文件名包含

design

、

review

、

plan

、

proposal

、

architecture

、

decision

等词汇

仓库路径如
```
docs/
```
、
```
design-docs/
```
、
```
exec-plans/
```
、
```
proposals/
```
文档内容涉及上线、 schema、兼容性、迁移、状态、任务或可观测性

当简短提示指向一个Markdown文件，但文档类型仍不明确时：

先打开文件
如果文件看起来是设计、计划或架构文档，继续执行审计
仅当文件明显与设计无关，且执行本技能可能出错时，才提出澄清问题

Context Strategy

上下文策略

Always read the target design document before forming conclusions.

If the user provides additional document paths, read them when they affect compatibility, migration, or design intent.

Honor explicit user scoping before inheriting ambient repo conventions. Examples:

"Treat this as a standalone doc"
"Do not use the current repo rules"
"Use only the checklist I provided"

When the user explicitly narrows the rule source:

use only the files and instructions explicitly named by the user
do not inherit unrelated repo standards just because they exist nearby
do not infer a repo report directory from the current workspace unless the user asked for saving

When the document is explicitly marked as draft, WIP, or incomplete (e.g., contains "WIP", "draft", "TBD", "work in progress" in the title, frontmatter, or first section):

Note the draft status in the Executive Summary
Downgrade all
```
[GAP]
```
findings by one priority level (
```
P1
```
→
```
P2
```
,
```
P2
```
→
```
P3
```
)
Prefix downgraded gap findings with
```
[DRAFT]
```
to signal the author likely knows these are missing
Keep all
```
[RISK]
```
and
```
[ASSUME]
```
findings at their original priority — a wrong decision is still wrong in a draft

If the user does not override the scope and the repo contains project-standard files, inherit them instead of ignoring them. Typical examples:

```
AGENTS.md
```
```
CONTRIBUTING.md
```
```
docs/design-docs/*checklist*.md
```
other review standards or design templates explicitly referenced by the user

When project-standard files exist, resolve them in this order:

Explicit user instructions in the current task
Explicitly provided checklist or standard files
Repo-wide review contracts such as
```
AGENTS.md
```
or
```
CONTRIBUTING.md
```
Repo checklist or template files that are clearly design-review specific
Default rules in this skill

When multiple candidate repo files exist at the same priority:

prefer the file whose title or filename most clearly matches design review, design decision, or architecture review
prefer the file closest in scope to the target document
ignore release, implementation, or deployment checklists unless the user asked for them
ask the user only if competing files would likely change the audit conclusion

When project-standard files exist and are in scope:

follow their review contract
follow their finding-ID format if one is explicitly required
follow their report location if one is explicitly required
use their design checklist to refine or override the default checklist in this skill

When project-standard files do not exist:

use the default review scope and checklist defined in this skill

在得出结论前，务必先阅读目标设计文档。

如果用户提供了额外的文档路径，当这些文档影响兼容性、迁移或设计意图时，才阅读它们。

优先遵循用户明确指定的范围，而非仓库默认约定。示例：

"将此视为独立文档"
"不要使用当前仓库规则"
"仅使用我提供的检查清单"

当用户明确缩小规则来源范围时：

仅使用用户明确指定的文件和指令
不要因附近存在无关的仓库标准就直接沿用
除非用户要求保存，否则不要从当前工作区推断仓库报告目录

当文档明确标记为草稿、WIP（进行中）或未完成时（例如标题、前置内容或第一节包含"WIP"、"draft"、"TBD"、"work in progress"）：

在执行摘要中注明草稿状态
将所有
```
[GAP]
```
发现的优先级降低一级（
```
P1
```
→
```
P2
```
，
```
P2
```
→
```
P3
```
）
降级的缺口发现前添加
```
[DRAFT]
```
前缀，表明作者可能已知这些内容缺失
所有
```
[RISK]
```
和
```
[ASSUME]
```
发现保持原优先级——错误的决策在草稿中依然是错误的

如果用户未覆盖范围，且仓库包含项目标准文件，则沿用这些文件而非忽略。典型示例：

```
AGENTS.md
```
```
CONTRIBUTING.md
```
```
docs/design-docs/*checklist*.md
```
用户明确引用的其他评审标准或设计模板

当存在项目标准文件时，按以下顺序优先级处理：

当前任务中用户的明确指令
用户明确提供的检查清单或标准文件
仓库级评审约定，如
```
AGENTS.md
```
或
```
CONTRIBUTING.md
```
明确针对设计评审的仓库检查清单或模板文件
本技能中的默认规则

当同一优先级存在多个候选仓库文件时：

优先选择标题或文件名与设计评审、设计决策或架构评审最匹配的文件
优先选择与目标文档范围最接近的文件
忽略发布、实现或部署检查清单，除非用户明确要求
仅当竞争文件可能改变审计结论时，才询问用户

当项目标准文件存在且在范围内时：

遵循其评审约定
如果明确要求，遵循其发现ID格式
如果明确要求，遵循其报告存储位置
使用其设计检查清单来完善或覆盖本技能中的默认检查清单

当不存在项目标准文件时：

使用本技能中定义的默认评审范围和检查清单

Core Goal

核心目标

Produce a structured audit that answers three questions:

Which important design decisions are already explicit?
Which important design decisions are missing, weak, or contradictory?
What exact content should be added to make the design reviewable and implementation-safe?

生成结构化审计报告，回答三个问题：

哪些重要的设计决策已明确？
哪些重要的设计决策缺失、不完善或相互矛盾？
需要添加哪些具体内容才能使设计可评审且实现安全？

Default Review Scope

默认评审范围

When the repo does not define a stricter review scope, audit these dimensions:

Correctness and project standards
Performance bottlenecks
KISS and DRY
Observability: logs, metrics, alerts
Idempotency and data consistency

Then audit the design against this default checklist:

Migration and cutover
Data handling
Schema and storage
Backward compatibility
Observability

Only add conditional modules when the design actually triggers them.

当仓库未定义更严格的评审范围时，审计以下维度：

正确性与项目标准
性能瓶颈
KISS和DRY原则
可观测性：日志、指标、告警
幂等性与数据一致性

然后针对以下默认检查清单审计设计：

迁移与切换
数据处理
Schema与存储
向后兼容性
可观测性

仅当设计实际触发时，才添加条件模块。

Default Conditional Modules

默认条件模块

Use the repo checklist when one exists. Otherwise use these default module triggers.

Trigger a module only when the design clearly matches its signals. Do not force every module into every audit. If a module does not apply, omit it.

Module	Trigger signals
Semi-structured payloads	JSON fields, dynamic columns, flexible schema, payload validation, extensible attributes, `interface{}` or `any` typed storage
Performance and indexing	query patterns, index design, pagination, bulk reads/writes, hot-path latency, large table scans
State machine or orchestration	status transitions, state enum, workflow steps, job scheduling, retry logic, FSM diagrams
Concurrency and locking	mutex, row-level lock, optimistic lock, concurrent writers, race condition mitigation, distributed lock
Async jobs and failure isolation	background jobs, queues, workers, dead-letter queues, retry with backoff, at-least-once delivery
Human review	manual approval steps, escalation paths, review SLA, operator action required
Audit and compliance	audit log, PII handling, data retention, GDPR/CCPA, regulatory requirements, immutable records
Scan and alert design	scheduled scans, anomaly detection, alert thresholds, on-call routing, runbook references

如果存在仓库检查清单，则使用它。否则使用以下默认模块触发规则。

仅当设计明确匹配触发信号时，才触发模块。不要强行将每个模块加入所有审计。如果模块不适用，则省略。

模块	触发信号
Semi-structured payloads	JSON字段、动态列、灵活schema、负载验证、可扩展属性、 `interface{}` 或 `any` 类型存储
Performance and indexing	查询模式、索引设计、分页、批量读写、热路径延迟、大表扫描
State machine or orchestration	状态转换、状态枚举、工作流步骤、任务调度、重试逻辑、FSM图
Concurrency and locking	互斥锁、行级锁、乐观锁、并发写入、竞争条件缓解、分布式锁
Async jobs and failure isolation	后台任务、队列、工作者、死信队列、退避重试、至少一次投递
Human review	手动审批步骤、升级路径、评审SLA、需要操作员操作
Audit and compliance	审计日志、PII处理、数据保留、GDPR/CCPA、监管要求、不可变记录
Scan and alert design	定时扫描、异常检测、告警阈值、值班路由、运行手册参考

Default Finding Contract

默认发现约定

If the repo defines a finding format, priority scheme, or review contract, follow the repo contract. Otherwise use the defaults below.

如果仓库定义了发现格式、优先级方案或评审约定，则遵循仓库约定。否则使用以下默认规则。

Findings Standard

发现标准

Rules:

Use thread-unique IDs
Default ID format:
```
CR01 [P1] [GAP]
```
— priority tag followed by type tag
Order findings from highest priority to lowest priority
Treat
```
P0
```
and
```
P1
```
as merge-blocking by default
Do not give conclusion-only findings
If there are findings, use a flat bullet list and keep the full prefix on every item
If there are no findings, use the Verified Checklist format described below

Default priorities:

```
P0
```
: merging or deploying will necessarily cause at least one of: data corruption, service unavailability, security vulnerability, or no rollback path
```
P1
```
: damage is possible but requires specific conditions to trigger, OR a design gap that prevents engineers from safely proceeding with implementation
```
P2
```
: meaningful correctness or operability risk that is unlikely to cause immediate harm but degrades reliability or maintainability
```
P3
```
: minor but real improvement with no production risk

Finding type tags — always include one per finding:

```
[GAP]
```
: a required decision is absent from the document
```
[RISK]
```
: a decision exists but is incorrect, contradictory, or dangerously incomplete
```
[ASSUME]
```
: the design implies a decision that was never made explicit; flag the hidden assumption

Explain each finding in this order:

What the issue is
How the current design triggers it
One concrete example
Why it matters to this change

Use expected behavior versus current behavior when that comparison makes the risk clearer.

Do NOT write conclusion-only findings. Examples:

BAD:

CR01 [P1] [GAP]: Migration strategy is unclear and may cause data loss.

CR02 [P2] [RISK]: Observability is insufficient.

GOOD:

CR01 [P1] [GAP]: The design does not specify how the job handles partial failures. If the job inserts 500 rows and fails at row 300, there is no rollback or resume mechanism described. Re-running the job would create duplicate rows unless the caller enforces idempotency externally.

CR02 [P2] [RISK]: The rollback plan in step 4 says "revert the migration" but the migration is destructive (column drop). A revert would require restoring from backup, which is not mentioned. Operators following this plan would have no path forward during an incident.

规则：

使用线程唯一ID
默认ID格式：
```
CR01 [P1] [GAP]
```
—— 优先级标签后跟类型标签
按优先级从高到低排序发现结果
默认将
```
P0
```
和
```
P1
```
视为合并阻塞项
不要只给出结论性的发现
如果有发现结果，使用扁平项目符号列表，且每个项保留完整前缀
如果没有发现结果，使用下文描述的已验证检查清单格式

默认优先级：

```
P0
```
：合并或部署必然会导致以下至少一种情况：数据损坏、服务不可用、安全漏洞或无回滚路径
```
P1
```
：可能造成损害，但需要特定条件触发，或者存在设计缺口导致工程师无法安全推进实现
```
P2
```
：存在有意义的正确性或可操作性风险，但不太可能造成即时危害，会降低可靠性或可维护性
```
P3
```
：微小但实际的改进，无生产风险

发现类型标签——每个发现必须包含一个：

```
[GAP]
```
：文档中缺少必要的决策
```
[RISK]
```
：决策存在，但不正确、相互矛盾或严重不完整
```
[ASSUME]
```
：设计隐含了一个从未明确做出的决策；标记隐藏的假设

按以下顺序解释每个发现：

问题是什么
当前设计如何触发该问题
一个具体示例
该问题对本次变更的影响

当对比预期行为与当前行为能更清晰地说明风险时，使用这种对比方式。

不要只写结论性的发现。示例：

错误示例：

CR01 [P1] [GAP]: 迁移策略不明确，可能导致数据丢失。

```
CR02 [P2] [RISK]: 可观测性不足。
```

正确示例：

CR01 [P1] [GAP]: 设计未指定任务如何处理部分失败。如果任务插入500行数据并在第300行失败，文档中未描述回滚或恢复机制。除非调用方在外部强制执行幂等性，否则重新运行任务会创建重复行。

CR02 [P2] [RISK]: 步骤4中的回滚计划提到"回滚迁移"，但该迁移是破坏性的（删除列）。回滚需要从备份恢复，而这一点未被提及。操作员按照此计划执行时，在事件发生时将无计可施。

No-Findings Protocol

无发现结果协议

When there are no findings, do not write only

No findings identified.

Instead, produce an explicit verified checklist that confirms what was checked and what was not triggered:

No findings identified.

Verified:
- ✓ <dimension>: <one sentence confirming what was checked and what was found sound>
- ✓ <dimension>: ...

Skipped (not triggered):
- <Module name>: <one-line reason why it was not triggered>

Example:

No findings identified.

Verified:
- ✓ Migration strategy: gradual rollout with feature flag and dual-write described; rollback path explicit
- ✓ Idempotency: job uses upsert on unique constraint; safe to re-run
- ✓ Observability: structured log on every state transition; alert threshold defined

Skipped (not triggered):
- State machine module: no status transitions in scope
- Concurrency and locking module: single-writer path only

当没有发现结果时，不要只写

未发现任何问题。

相反，生成明确的已验证检查清单，确认已检查的内容和未触发的模块：

未发现任何问题。

已验证：
- ✓ <维度>: <一句话确认已检查的内容及确认无误的结论>
- ✓ <维度>: ...

已跳过（未触发）：
- <模块名称>: <一行说明未触发的原因>

示例：

未发现任何问题。

已验证：
- ✓ 迁移策略：描述了基于功能标志的逐步上线和双写机制；回滚路径明确
- ✓ 幂等性：任务在唯一约束上使用upsert；可安全重新运行
- ✓ 可观测性：每个状态转换都有结构化日志；告警阈值已定义

已跳过（未触发）：
- 状态机模块：范围内无状态转换
- 并发与锁模块：仅单写入路径

Suggested Additions Standard

建议补充内容标准

After findings, provide suggested additions that the author can copy into the design document.

Suggested additions must be:

Concrete
Short
Decision-oriented
Grouped by section or topic
Based on the recommended repair option, not every option

Do not write generic advice such as "consider adding more detail". Write the missing decision directly.

Good example:

```
Migration Strategy
```
: Use gradual rollout behind a feature flag. Keep reads on the legacy path for one release while dual-writing the new field. Roll back by disabling the flag and stopping dual-write.

Bad example:

```
Migration Strategy
```
: Add more migration details.

在发现结果之后，提供作者可直接复制到设计文档中的建议补充内容。

建议补充内容必须：

具体
简洁
面向决策
按章节或主题分组
基于推荐的修复方案，而非所有可选方案

不要写诸如"考虑添加更多细节"之类的通用建议。直接写出缺失的决策内容。

正确示例：

```
迁移策略
```
：在功能标志后逐步上线。在一个版本周期内保持从旧路径读取，同时双写新字段。通过禁用标志并停止双写来回滚。

错误示例：

```
迁移策略
```
：添加更多迁移细节。

Remediation Options Standard

修复方案选项标准

For every material finding, compare repair options instead of giving only one answer.

Apply this rule to:

all
```
P0
```
all
```
P1
```
all
```
P2
```

Do not apply this rule to:

```
P3
```
findings unless the user explicitly asks for option analysis
no-finding reviews

For each applicable finding, create exactly three distinct repair options:

```
Option A
```
```
Option B
```
```
Option C
```

The three options must differ in approach or trade-off. Do not create fake variety by rewording the same solution three times.

Then choose one recommended option and explain why it is best for the current design. Also explain briefly why the other two options were not selected.

Keep the comparison concise:

use one compact markdown table for the three options
one short paragraph for the recommendation
one short line per rejected option

The options table should prefer these columns:

```
Option
```
```
Approach
```
```
Pros
```
```
Trade-offs
```

Do not add more columns unless the user explicitly asks for deeper analysis.

Good comparison dimensions:

implementation complexity
rollback safety
compatibility risk
runtime cost
operability
long-term maintainability

Bad comparison dimensions:

vague preference
duplicated wording
generic statements such as "less ideal"

If the design is clearly blocked by one finding, the recommended option should prefer safety and reversibility over speed.

对于每个重要的发现结果，对比修复方案，而非只给出一个答案。

此规则适用于：

所有
```
P0
```
发现
所有
```
P1
```
发现
所有
```
P2
```
发现

此规则不适用于：

```
P3
```
发现，除非用户明确要求选项分析
无发现结果的评审

对于每个适用的发现结果，创建三个完全不同的修复选项：

```
Option A
```
```
Option B
```
```
Option C
```

三个选项必须在方法或权衡上有所不同。不要通过改写同一解决方案来制造虚假差异。

然后选择一个推荐选项，并解释为什么它最适合当前设计。同时简要说明为什么未选择另外两个选项。

保持对比简洁：

对三个选项使用紧凑的Markdown表格
用一小段话说明推荐理由
每个被拒绝的选项用一行简要说明

选项表格优先使用以下列：

```
Option
```
```
Approach
```
```
Pros
```
```
Trade-offs
```

除非用户明确要求更深入的分析，否则不要添加更多列。

良好的对比维度：

实现复杂度
回滚安全性
兼容性风险
运行成本
可操作性
长期可维护性

不良的对比维度：

模糊的偏好
重复的措辞
诸如"不太理想"之类的通用表述

如果设计明显被一个发现结果阻塞，推荐选项应优先考虑安全性和可逆性，而非速度。

Output Calibration

输出校准

Scale remediation verbosity to document complexity.

For short or simple documents (under 300 words, or fewer than 3 triggered modules, or all findings are P3):

Collapse the three-option table into a single recommended approach plus one-line trade-off note
Do not suppress findings — only reduce remediation prose

Example:

Recommended: use a feature flag for rollout. Trade-off: adds one release cycle of flag management overhead.

For complex documents (5 or more triggered modules, or any P0 finding, or more than 6 findings total):

Apply the full three-option table format for every P0–P2 finding
Do not abbreviate option analysis

Default to the full format when complexity is unclear.

根据文档复杂度调整修复方案的详细程度。

对于简短或简单的文档（少于300字，或触发模块少于3个，或所有发现均为P3）：

将三选项表格合并为单一推荐方案加一行权衡说明
不要隐藏发现结果——仅减少修复方案的文字描述

示例：

推荐：使用功能标志进行上线。权衡：增加一个版本周期的标志管理开销。

对于复杂文档（触发模块5个或以上，或存在任何P0发现，或总发现数超过6个）：

对每个P0–P2发现使用完整的三选项表格格式
不要简化选项分析

当复杂度不明确时，默认使用完整格式。

Output Format

输出格式

Always use this structure in the chat response:

markdown

undefined

聊天回复始终使用以下结构：

markdown

undefined

Design Audit

设计审计

Executive Summary

执行摘要

Triggered Modules

触发模块

Findings

审计发现

Suggested Additions

建议补充内容

Open Questions

待解决问题

Report Path

报告路径


Section rules:
- `Executive Summary`: 2 to 5 sentences on overall audit posture
- `Triggered Modules`: list only the modules actually used; if none apply, write `- None`
- `Findings`: include the chosen `XX [P#]` items or state `No findings identified.`
- `Suggested Additions`: grouped by section heading or topic
- `Open Questions`: include only questions that materially block confident review
- `Report Path`: this section must always exist
- if a report file was written, include the saved path
- if the task is chat-only and no file was required, write `- Chat only (not requested)`

Use section names in the chosen output language while preserving the same logical structure.

Within each applicable finding, use this sub-structure:
- finding statement (include type tag: `[GAP]`, `[RISK]`, or `[ASSUME]`)
- `Options`
- `Recommended Option`
- `Why Not Others`

Within `Options`, use a markdown table instead of prose whenever possible.

Do not replace the required sections with a free-form review.
Even short audits must keep the exact section names.

For `Suggested Additions`:
- Write copy-ready sentences, not reminders
- Use only the recommended option when turning analysis into suggested document text
- Prefer section labels such as `Migration Strategy`, `Rollback Plan`, `Observability`, `Consumer Impact`
- If there are no useful additions, say `No suggested additions.`


章节规则：
- `执行摘要`：2-5句话说明整体审计情况
- `触发模块`：仅列出实际使用的模块；如果无适用模块，写`- None`
- `审计发现`：包含选定的`XX [P#]`项，或注明`未发现任何问题。`
- `建议补充内容`：按章节标题或主题分组
- `待解决问题`：仅包含会实质性阻碍评审信心的问题
- `报告路径`：此章节必须始终存在
- 如果已生成报告文件，包含保存路径
- 如果仅为聊天任务且无需生成文件，写`- 仅聊天（未要求保存）`

使用选定输出语言的章节名称，同时保留相同的逻辑结构。

每个适用的发现结果使用以下子结构：
- 发现陈述（包含类型标签：`[GAP]`、`[RISK]`或`[ASSUME]`）
- `Options`
- `Recommended Option`
- `Why Not Others`

在`Options`中，尽可能使用Markdown表格而非散文。

不要用自由形式的评审替代必填章节。
即使是简短审计，也必须保留确切的章节名称。

对于`建议补充内容`：
- 编写可直接复制的句子，而非提醒
- 将分析转化为文档建议文本时，仅使用推荐选项
- 优先使用章节标签，如`迁移策略`、`回滚计划`、`可观测性`、`消费者影响`
- 如果没有有用的补充内容，写`无建议补充内容。`

Report File

报告文件

Save a report file only when one of these is true:

the user explicitly asks to save the report
the repo has an obvious existing report directory and the task implies report persistence

Preferred path selection:

Use a path explicitly requested by the user
Use the repo's established report directory if one clearly exists, such as
```
docs/reports/
```
, and repo conventions are in scope
If the task clearly requires saving but no path can be inferred, ask the user where to save the report
Otherwise keep the result in the chat only

If writing a report file:

use the current local date in the repo timezone
derive
```
<topic>
```
from the design document filename when possible
use a short stable fallback such as
```
design-audit
```
when needed
keep the file sections aligned with the chat response

Do not claim the report path unless the file has actually been written.

仅在以下情况之一成立时保存报告文件：

用户明确要求保存报告
仓库存在明显的现有报告目录，且任务暗示需要持久化报告

路径选择优先级：

使用用户明确要求的路径
如果仓库存在明确的报告目录（如
```
docs/reports/
```
）且仓库约定在范围内，则使用该目录
如果任务明确要求保存但无法推断路径，询问用户保存位置
否则仅在聊天中保留结果

如果生成报告文件：

使用仓库时区的当前本地日期
尽可能从设计文档文件名中提取
```
<topic>
```
必要时使用简短稳定的备用名称，如
```
design-audit
```
保持文件章节与聊天回复一致

除非文件已实际生成，否则不要声明报告路径。

Workflow

工作流

Phase A: Context Preparation

阶段A：上下文准备

Goal: Build a complete context package and perform default checklist audit.

Read the design document.
Determine the audit output language from the user instruction.
Read repo-standard files when present and relevant.
Read user-provided context files that affect scope or intent.
Determine whether the user explicitly limited the audit to standalone mode or named files only.
Resolve the review contract, finding format, checklist, and report-path conventions using the priority order in this skill.
Determine which conditional modules are triggered.
Default checklist audit: Audit the design against the 5 default dimensions (correctness and project standards, performance bottlenecks, KISS and DRY, observability, idempotency and data consistency). Record these as preliminary findings.
Assemble context package: Combine the design document content, repo standards, review contract, draft status, and triggered module list into a structured context package for Phase B.

目标：构建完整的上下文包并执行默认检查清单审计。

读取设计文档。
根据用户指令确定审计输出语言。
读取仓库中存在且相关的标准文件。
读取用户提供的影响范围或意图的上下文文件。
确定用户是否明确将审计限制为独立模式或仅指定文件。
使用本技能中的优先级顺序确定评审约定、发现格式、检查清单和报告路径约定。
确定哪些条件模块被触发。
默认检查清单审计：针对5个默认维度（正确性与项目标准、性能瓶颈、KISS和DRY原则、可观测性、幂等性与数据一致性）审计设计。记录这些作为初步发现。
组装上下文包：将设计文档内容、仓库标准、评审约定、草稿状态和触发模块列表组合成结构化上下文包，用于阶段B。

Phase B: Parallel Module Audit

阶段B：并行模块审计

Goal: Audit each triggered conditional module in parallel using specialized subagents.

When no modules are triggered: Skip Phase B entirely. Use only Phase A preliminary findings.

When one or more modules are triggered:

For each triggered conditional module, launch a parallel Sonnet subagent:
- Read the agent template at
```
skills/design-decision-audit/agents/module-auditor.md
```
- Fill in the template parameters:
  - ```
  {{MODULE_NAME}}
```
  : the module name (e.g., "State Machine and Orchestration")
- ```
{{TRIGGER_SIGNALS}}
```
    : the trigger signals that matched this module
  - ```
  {{DESIGN_DOC}}
```
  : the design document content
- ```
{{REPO_STANDARDS}}
```
    : repo standards content (or "None" if standalone)
  - ```
  {{REVIEW_CONTRACT_SECTION}}
```
  : review contract if one exists (or empty)
- Use the filled template as the subagent prompt
- Each subagent runs independently with no shared state
Collect findings from all subagents as they complete.

Fallback: If a subagent fails or times out, the main agent audits that module inline using the same dimension scope.

目标：使用专用子代理并行审计每个触发的条件模块。

当无模块被触发时：完全跳过阶段B。仅使用阶段A的初步发现。

当一个或多个模块被触发时：

针对每个触发的条件模块，启动并行Sonnet subagent：
- 读取
```
skills/design-decision-audit/agents/module-auditor.md
```
  中的代理模板
- 填充模板参数：
  - ```
  {{MODULE_NAME}}
```
  ：模块名称（如"State Machine and Orchestration"）
- ```
{{TRIGGER_SIGNALS}}
```
    ：匹配此模块的触发信号
  - ```
  {{DESIGN_DOC}}
```
  ：设计文档内容
- ```
{{REPO_STANDARDS}}
```
    ：仓库标准内容（如果是独立模式则为"None"）
  - ```
  {{REVIEW_CONTRACT_SECTION}}
```
  ：如果存在评审约定则填写（否则为空）
- 使用填充后的模板作为子代理提示词
- 每个子代理独立运行，无共享状态
收集所有子代理完成后的发现结果。

回退方案：如果子代理失败或超时，主代理使用相同的维度范围内联审计该模块。

Phase C: Synthesis

阶段C：合成

Goal: Merge, deduplicate, prioritize, and format all findings into the final audit output.

Merge findings: Combine Phase A preliminary findings (default checklist) and Phase B findings (module audits) into a single list.
Deduplicate using this decision tree:
- Two findings describe the same issue at the same location → merge into one, keep the finding with richer detail. If from different sources, append
```
[CROSS-VALIDATED]
```
  to the finding tag.
- Two findings share a root cause but describe different manifestations → keep both, add cross-references (e.g., "see also CR01").
- Unsure whether two findings overlap → keep both, do not merge.
Assign final IDs: Number findings as CR01, CR02, ... in priority order (P0 first, then P1, etc.).
Token guard: If the merged findings text exceeds roughly 4000 tokens, keep all P0 and P1 findings in full. For P2 and P3, keep only the summary line and defer detail to the report file.
Generate repair options: For each P0 to P2 finding, generate three distinct repair options and recommend the best one. Apply Output Calibration rules (full table for complex documents, collapsed format for simple ones).
Write suggested additions: Based on the recommended options, produce copy-ready additions grouped by section or topic.
Draft handling: If the document was marked draft/WIP, downgrade
```
[GAP]
```
findings by one priority level and prefix with
```
[DRAFT]
```
.
Format output: Assemble the final response using the required six-section structure (Executive Summary, Triggered Modules, Findings, Suggested Additions, Open Questions, Report Path).
Save report: If the task requires saving, write the report file. If no save path can be inferred, ask the user.
Return the structured audit response with the report path in the chosen language.

目标：合并、去重、排序并格式化所有发现结果，生成最终审计输出。

合并发现结果：将阶段A的初步发现（默认检查清单）和阶段B的发现结果（模块审计）合并为一个列表。
去重遵循以下决策树：
- 两个发现描述同一位置的同一问题 → 合并为一个，保留细节更丰富的发现。如果来自不同来源，在发现标签后追加
```
[CROSS-VALIDATED]
```
  。
- 两个发现共享根本原因但描述不同表现 → 保留两者，添加交叉引用（如"另见CR01"）。
- 不确定两个发现是否重叠 → 保留两者，不合并。
分配最终ID：按优先级顺序（先P0，再P1等）为发现结果编号为CR01、CR02……
令牌限制：如果合并后的发现文本超过约4000令牌，完整保留所有P0和P1发现。对于P2和P3，仅保留摘要行，详细内容放在报告文件中。
生成修复选项：针对每个P0至P2发现，生成三个不同的修复选项并推荐最佳选项。应用输出校准规则（复杂文档使用完整表格，简短/简单文档使用简化格式）。
编写建议补充内容：基于推荐选项，生成按章节或主题分组的可直接复制的补充内容。
草稿处理：如果文档标记为草稿/WIP，将
```
[GAP]
```
发现的优先级降低一级，并添加
```
[DRAFT]
```
前缀。
格式化输出：使用必填的六节结构（执行摘要、触发模块、审计发现、建议补充内容、待解决问题、报告路径）组装最终回复。
保存报告：如果任务要求保存，生成报告文件。如果无法推断保存路径，询问用户。
返回结构化审计回复，报告路径使用选定语言。

Boundaries

边界

Do:

Audit the design document
Call out missing or weak decisions
Propose concrete additions
Compare repair options for material findings and recommend the best one
Save a report file when required by the task or repo convention
Make the triggered checklist scope explicit
Keep the response reviewable by a human without extra interpretation

Do not:

Edit the design document directly
Generate an implementation plan unless the user asks for one
Expand into code review unless the user changes scope
Ask unnecessary questions if the missing information can be identified as a design gap
Collapse the audit into informal prose
Omit the report path or the triggered module declaration

允许：

审计设计文档
指出缺失或不完善的决策
提出具体的补充建议
针对重要发现对比修复选项并推荐最佳方案
根据任务或仓库约定保存报告文件
明确触发的检查清单范围
保持回复可供人类评审，无需额外解释

禁止：

直接编辑设计文档
生成实现计划，除非用户明确要求
扩展到代码评审，除非用户更改范围
如果缺失信息可被识别为设计缺口，不要提出不必要的问题
将审计简化为非正式散文
省略报告路径或触发模块声明

Escalation Rules

升级规则

Ask a short blocking question only when:

The target design document is not identifiable
The repo contains multiple candidate docs and the correct one is ambiguous
A missing context file is necessary to avoid a likely wrong conclusion
Multiple in-scope standards conflict and the choice would likely change the audit result
The task requires a saved report but no report path can be inferred from the user request or repo conventions

Otherwise, continue the audit and list the uncertainty under

Open Questions

仅在以下情况提出简短的阻塞性问题：

无法识别目标设计文档
仓库包含多个候选文档，且正确文档不明确
缺少上下文文件会导致可能的错误结论
多个范围内的标准冲突，且选择会改变审计结果
任务要求保存报告，但无法从用户请求或仓库约定推断报告路径

否则，继续审计并将不确定性列在

待解决问题

下。

Quality Bar

质量标准

Before finishing, check these points:

The response has all six required sections
```
Triggered Modules
```
is explicit, even when empty; each triggered module names the signals that fired it
Findings follow the repo-required format, or
```
CRXX [P#] [TYPE]
```
when no repo format exists
Every finding includes a type tag:
```
[GAP]
```
,
```
[RISK]
```
, or
```
[ASSUME]
```
No finding is conclusion-only — each one states what, how, a concrete example, and why it matters
Every
```
P0
```
to
```
P2
```
finding contains repair options, one recommendation, and brief rejection reasons
- Full three-option table for complex documents
- Single recommended approach + one-line trade-off for short/simple documents
```
Suggested Additions
```
reflect the recommended option rather than repeating all options
If there are no findings, the response uses the Verified Checklist format (not just
```
No findings identified.
```
)
If the document was marked draft/WIP,
```
[GAP]
```
findings are downgraded one level and prefixed
```
[DRAFT]
```
The chat response and saved report use the same inferred output language
Suggested additions are copy-ready
Explicit user overrides beat ambient repo conventions
If the task requires saving, a report path was either written or explicitly confirmed by the user

完成前检查以下要点：

回复包含所有六个必填章节
```
触发模块
```
明确，即使为空；每个触发模块注明触发信号
发现结果遵循仓库要求的格式，若无仓库格式则使用
```
CRXX [P#] [TYPE]
```
每个发现结果包含类型标签：
```
[GAP]
```
、
```
[RISK]
```
或
```
[ASSUME]
```
没有结论性发现——每个发现都说明问题是什么、如何触发、具体示例以及影响
每个
```
P0
```
至
```
P2
```
发现包含修复选项、一个推荐方案和简短的拒绝理由
- 复杂文档使用完整的三选项表格
- 简短/简单文档使用单一推荐方案+一行权衡说明
```
建议补充内容
```
反映推荐选项，而非重复所有选项
如果没有发现结果，回复使用已验证检查清单格式（而非仅
```
未发现任何问题。
```
）
如果文档标记为草稿/WIP，
```
[GAP]
```
发现优先级降低一级并添加
```
[DRAFT]
```
前缀
聊天回复和保存的报告使用相同的推断输出语言
建议补充内容可直接复制
用户明确的覆盖规则优先于仓库默认约定
如果任务要求保存，报告路径已生成或经用户明确确认

Journal Integration

日志集成

When operating on a task tracked under

.agents/tasks/<task-id>/

, append a journal entry at this skill's milestone.

Trigger: after the audit completes and findings are returned
Reserved key(s):
```
note
```
for clean audits;
```
blocker
```
if findings are blocking

Entry shape:

## <ISO8601-timestamp> — design-decision-audit
note: audit complete; <N> findings, <M> blocking
[optional ≤ 15-line body; longer content goes to artifacts/]

Resolve the task id from the explicit caller argument or

.agents/tasks/.current

. If neither resolves, skip the append; do not guess.

See

task-journal

for the full convention.

当在

.agents/tasks/<task-id>/

下跟踪的任务上运行时，在本技能的里程碑处追加日志条目。

触发时机：审计完成并返回发现结果后
保留键：无问题审计使用
```
note
```
；发现结果阻塞时使用
```
blocker
```

条目格式：

## <ISO8601-timestamp> — design-decision-audit
note: 审计完成；<N>个发现，<M>个阻塞项
[可选≤15行正文；更长内容放入artifacts/]

从显式调用参数或

.agents/tasks/.current

解析任务ID。如果两者都无法解析，跳过追加；不要猜测。

有关完整约定，请参阅

task-journal

。