product-clarify

product-clarify

此技能的作用

审查现有 PDR，找出质量缺口，提出有针对性的澄清问题，并将获批的 PDR 状态提升为 Accepted。这是生成 PRD 前的质量门槛。

输入：.adlc/drafts/pdr/ 中单独的 PDR-*.md 文件（状态为 Proposed 或 Discovered）

输出：更新后的 PDR-*.md 文件（获批后状态为 Accepted），以及重新生成的 pdr.md 索引

适用场景

• 在 /product-specify 或 /product-init 之后，完善初始 PDR
• 在 /product-implement 之前，批准 PDR（必需——implement 会跳过非 Accepted 的 PDR）
• 里程碑之前定期审查 PDR
• 解决跨功能领域分析发现的不一致标记

不适用场景

• 不存在 PDR（请先使用 /product-specify 或 /product-init）

执行步骤

阶段 1：加载 PDR

1. 运行设置脚本：

sh: scripts/bash/setup-product-clarify.sh [--json]
ps: scripts/powershell/setup-product-clarify.ps1

2. 从 {REPO_ROOT}/.adlc/drafts/pdr/PDR-*.md 读取所有 PDR 文件
3. 读取宪章：先读取 {REPO_ROOT}/docs/adlc/memory/constitution.md；若不存在，则回退读取旧路径 {REPO_ROOT}/.adlc/memory/constitution.md（双路径读取），前提是其中任一路径存在
4. 构建清单：

| PDR | Title | Status | Category |
|-----|-------|--------|----------|
| PDR-001 | Target Market | Proposed | Problem |
| PDR-002 | Primary Persona | Proposed | Persona |

步骤 0：检测轻量草稿格式

检查待审查的草稿是否使用轻量草稿模板（其特征是 frontmatter 中包含 type、evidence、source、revisit-when 字段，且正文包含 ## Rejected Alternatives / ## Reason 部分，但不包含完整的正式模板部分）。

如果是轻量格式：

1. 读取草稿中已记录的字段（Context、Decision、Rejected Alternatives、Reason）
2. 转换为完整的正式模板：
   • ADR：完整的 MADR 格式，包含 Decision Drivers、Considered Options、Pros/Cons、Constitution Alignment、Related ADRs
   • PDR：完整的 PDR 格式，包含 Market Forces、Consequences、Alternatives Considered、Links
   • ChDR：完整的 ChDR 格式，包含 Issue Links、Commits、Consequences、Evidence
   • CDR：完整的 CDR 格式，包含 Context Type、Target Module、Descriptor、Evidence
   • EVAL：完整的评估格式，包含 Error Analysis、Pass/Fail Examples、Implementation Notes
3. 根据会话上下文补充内容（添加轻量草稿可能遗漏的细节）
4. 提交补充后的草稿以供审查

如果已经是完整格式，则按常规流程审查。

阶段 2：PDR 质量分析

根据以下标准检查每个 PDR：

维度	检查项	缺失时的严重程度
Context	是否清楚说明问题	MEDIUM
Decision	是否可执行、可测试	HIGH
Consequences	是否记录正面和负面影响	HIGH
Success Metrics	是否已定义并设定目标	HIGH
Alternatives	是否至少包含 2 个且权衡客观	HIGH
Constitution	是否符合愿景	CRITICAL

质量检查清单：

• 清晰说明问题或机会的背景
• 明确且可执行的决策声明
• 记录正面和负面影响
• 至少包含 2 个备选方案，并客观权衡（不能写成“因某原因而拒绝”）
• 定义成功指标
• 识别风险并制定缓解策略
• 状态值有效
• 不与其他 PDR 冲突
• 符合宪章／愿景原则

阶段 3：跨 PDR 一致性

1. 决策冲突：同一概念在不同 PDR 中有不同决策
2. 缺少依赖关系：应相互引用的 PDR 未建立引用
3. 术语漂移：同一概念使用不同名称
4. 优先级冲突：一个 PDR 指定 B2B，另一个则假定 B2C

阶段 4：识别缺口

生成缺口报告：

## PDR Clarification Report

| PDR | Title | Gap Type | Severity |
|-----|-------|----------|----------|
| PDR-001 | [Title] | Missing alternatives | HIGH |
| PDR-002 | [Title] | Incomplete consequences | MEDIUM |

严重程度：

• CRITICAL：违反宪章、缺少决策声明、没有成功指标
• HIGH：没有备选方案、缺少影响说明
• MEDIUM：风险不完整、背景不清楚
• LOW：措辞上的小问题

阶段 5：交互式完善

对于每个缺口，一次提出一个澄清问题：

## Clarification [N]: PDR-XXX — [Gap Type]

**Current State**:
[Quote current PDR content]

**Gap Identified**:
[Explain what's missing]

**Question**:
[Specific question]

**Suggested Options**:
| Option | Description |
|--------|-------------|
| A | [Option A] |
| B | [Option B] |
| C | [Custom response] |

规则：

• 一次提出一个澄清问题
• 按严重程度优先排序——先处理 CRITICAL/HIGH
• 每次会话最多进行 5 项澄清
• 允许用户跳过非关键的澄清问题
• 每次收到回答后都总结变更

阶段 6：章程违规（如有）

对于重复项：

## Constitution Duplication Detected

**PDR**: PDR-XXX — [Title]
**Constitution Principle**: §[Section] — [Principle]

**Options**:
| Option | Action |
|--------|--------|
| A | Remove PDR |
| B | Convert to Reference |
| C | Add Context |
| D | Extend |

对于违规项（⭐ 推荐：修订章程）：

## Constitution Violation Detected ⭐

**⭐ RECOMMENDED: A. Amend Constitution**
Update constitution §[Section] to accommodate this decision.

**Alternatives**:
B. Override in PDR — Document justification
C. Revise PDR — Change decision to comply
D. Remove PDR — Delete and follow constitution

阶段 7：更新 PDR 文件

1. 按文件应用澄清结果
2. 在适用时更新状态
3. 更新“Last Updated”时间戳
4. 重新生成 pdr/pdr.md 索引——调用 pdr-lib.sh 中的 generate_pdr_index drafts（或调用 pdr-lib.ps1 中的 Generate-PdrIndex drafts）。该命令使用以前置元数据为主、标题为后备的解析器，可处理 H2 和 H3 元数据，避免空白行问题。

阶段 8：批准 PDR ⭐

关键：/product-implement 只处理状态为 Accepted 的 PDR。

## PDR Approval ⭐

**Total PDRs**: [N]
**Status Distribution**:
- Accepted: [N]
- Proposed: [N]
- Discovered: [N]

**Options**:
| Option | Action |
|--------|--------|
| A | Accept All — Change Proposed/Discovered → Accepted |
| B | Review Specific — Select individual PDRs |
| C | Defer — Keep current status |

批量批准（选项 A）：

## Confirm Bulk Approval

Change [N] PDRs to Accepted?

| PDR | Current | New |
|-----|---------|-----|
| PDR-001 | Proposed | Accepted |
| PDR-002 | Discovered | Accepted |

批准后：

## PDRs Approved

**Ready for Implementation**:
- Accepted PDRs: [N]
- Pending: [N]

Run `/product-implement` to generate PRD.md.

关键规则

非破坏性完善

• 未经用户明确批准，绝不删除现有 PDR
• 更新措辞时保留原始意图
• 补充而非替换后果和替代方案
• 使用更新后的时间戳标记变更

有针对性的澄清

• 一次只问一个问题
• 问题要具体且易于回答
• 尽可能提供建议选项
• 尊重用户的时间

章程权威性

• 始终标记章程违规
• 未经说明，PDR 不能覆盖 MUST 原则
• 如果冲突具有系统性，建议更新章程

配置

• PDR_DRAFTS_DIR — {REPO_ROOT}/.adlc/drafts/pdr
• PDR_INDEX — {REPO_ROOT}/.adlc/drafts/pdr/pdr.md
• CONSTITUTION — {REPO_ROOT}/docs/adlc/memory/constitution.md（旧版 .adlc/memory/constitution.md 回退路径）

与 12 因子原则的对齐

• 因子 III（使命定义）：确保在执行前明确定义产品使命
• 因子 VII（质量关卡）：在自动生成前应用人工判断

常见自我辩解

自我辩解	实际情况
“PDR 看起来没问题——跳过澄清吧。”	实施流程会跳过状态非 Accepted 的 PDR，从而在 PRD 中悄然遗漏相关决策。
“我直接一次性全部接受就好。”	未经审查就批量接受，可能会将错误决策写入 PRD。
“章程警告基本上没关系。”	章程违规属于 CRITICAL，因为它们会破坏产品的一致性。

危险信号

• 跳过批准步骤——如果状态不是 Accepted，实施流程就会忽略该 PDR。
• 不阅读就接受——这违背了质量关卡的目的。
• 未标记跨 PDR 冲突——不一致的 PDR 会导致 PRD 缺乏一致性。

验证

• 已阅读并清点所有 PDR 文件
• 已对每个 PDR 应用质量检查清单
• 已验证跨 PDR 一致性
• 已检查与章程的一致性
• 已识别缺口并按优先级排序
• 已按文件应用澄清结果
• 已重新生成 pdr.md 索引
• 已完成批准阶段（接受/审查/延期）
• 已接受的 PDR 文件中状态为“Accepted”
• 没有重复或缺失的 PDR ID