product-analyze

product-analyze

此技能的作用

执行只读产品一致性分析：

1. PDR 质量 — 完整性、清晰度、标准合规性
2. PDR→PRD 偏差 — PRD 中未体现的决策
3. PRD→PDR 偏差 — 缺乏 PDR 支持的 PRD 要素
4. 跨 PDR 一致性 — PDR 之间的冲突
5. 过时内容 — 过时的引用、占位符、仍被引用的已弃用 PDR
6. Mermaid 语法 — 标记无效的图表代码块，并提供位置和建议的补丁（Mermaid 检测阶段）

输出：结构化 Markdown 分析报告（不修改任何文件）

适用场景

• 执行 /product-implement 后，验证生成的 PRD
• 执行 /product-clarify 后，验证完善结果
• 开始功能开发前，确保产品方案完善
• 定期检测产品演进过程中出现的偏差

不适用场景

• 不存在产品制品（请先使用 /product-init 或 /product-specify）
• 需要修改文件（此技能仅用于分析）

执行步骤

阶段 1：加载制品

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

读取：

• docs/adlc/product/PRD.md（回退到仓库根目录中的旧版 PRD.md — 双重读取）
• {REPO_ROOT}/.adlc/drafts/pdr/PDR-*.md（单独的 PDR 文件）
• {REPO_ROOT}/docs/adlc/memory/constitution.md，若不存在则回退到旧版 {REPO_ROOT}/.adlc/memory/constitution.md（双重读取；任一文件存在时）

构建清单：

| Artifact | Path | Status |
|----------|------|--------|
| Product PRD | docs/adlc/product/PRD.md (legacy PRD.md fallback) | Found/Missing |
| Product PDRs | .adlc/drafts/pdr/ | [N] files |
| Constitution | docs/adlc/memory/constitution.md (legacy .adlc/memory fallback) | Found/Missing |

阶段 2：PDR 质量分析

检查每个 PDR 文件：

维度	检查内容	严重程度
背景	清晰陈述问题	中
决策	可执行、可测试	高
后果	同时包含正面和负面影响	高
成功指标	已定义并设定目标	高
备选方案	至少 2 个，且权衡分析客观中立	高
宪章	与愿景一致	严重

阶段 3：PDR 间一致性

1. 决策冲突：相互矛盾的 PDR（例如，B2B 与 B2C）
2. 缺少依赖关系：本应相互引用的 PDR
3. 术语偏差：同一概念使用不同名称
4. 策略一致性：问题、角色和指标之间的一致性

阶段 4：PDR→PRD 偏差（向前同步）

对于每个 PDR，检查其中的决策是否出现在 PRD 中：

PDR 要素	PRD 中的预期内容	章节
问题决策	问题陈述	3
角色决策	角色	6
范围决策	需求 / 范围外内容	7 / 9
指标决策	成功指标	5
商业模式	概述	2
NFR 决策	非功能需求	8

阶段 5：PRD→PDR 偏差（向后同步）

1. 缺少 PDR 的需求：缺少范围依据的用户故事
2. 缺少 PDR 的角色：没有角色 PDR 的角色
3. 缺少 PDR 的指标：没有指标 PDR 的成功指标
4. 缺少 PDR 的风险：没有后果文档记录的风险

阶段 6：过时内容检测

1. 仍被引用的已弃用 PDR：PRD 引用了状态为“已弃用”的 PDR
2. 占位符：[TODO]、[TBD]、[PRODUCT_NAME]、[DATE]
3. 日期不一致：PDR 日期早于 PRD 的最后更新时间
4. 孤立引用：提及了 PDR ID，但对应文件不存在

Phase 7：Mermaid 语法验证（Mermaid 检测阶段）

目标：标记 PRD 中无效的 Mermaid 代码块，注明位置并提供建议补丁，确保不会有损坏的图表未经提醒就发布。

运行共享验证器——规则集由它负责维护（以 architect-clarify 中的规则为准；规则只在验证器自身中记录一次）。此处不要重新推导或重述阈值：

sh: {REPO_ROOT}/.agents/skills/architect-clarify/scripts/bash/mermaid-lint.sh --tsv <artifact>

需要 architect-clarify 技能（adlc-cli skills add tikalk/adlc-team-skills --skill architect-clarify）。退出码：0 表示无问题，1 表示存在 HIGH（语法错误），2 表示仅有 MEDIUM（样式）问题。

规则词汇表——采用验证器自身的 ID；严重级别随每条发现一起给出，绝不在此处推断：

规则	含义
M001-fence-not-closed	```mermaid 代码块未闭合
M002-unknown-diagram-type	类型关键字不在已知集合中——需复核，绝不能误报为 HIGH
M003-missing-diagram-type	代码块未声明任何图表类型
M004-empty-block	代码块不含图表内容——注释和指令不计入
M005-empty-body	已声明类型，但后面没有语句——Mermaid 仍会渲染它（生成空图表），因此这是 MEDIUM 样式问题，绝不是语法错误；问题定位在类型声明处
M006-malformed-gantt-header	gantt 代码块的第一条语句（跳过注释和指令）既不是 gantt 关键字，也不是任务行——格式错误的第一条语句属于语法错误（HIGH）；形似任务行的语句至多为 MEDIUM，绝不能误报为 HIGH
M007-malformed-sequence-diagram	sequenceDiagram 的第一条语句（跳过注释和指令）不是文档规定的序列语句——例如 participant、消息，或 title、autonumber、box、critical、break 等关键字；不符合上述任何一种的语句属于语法错误（HIGH）
M008-malformed-entity-diagram	erDiagram 的第一条语句（跳过注释和指令）含有被 Mermaid 实体名称语法拒绝的字符——关系、属性块，或由字母、数字、_、-、. 和空格组成的裸名称均有效（Mermaid 会将裸名称解析为独立实体），因此只有无法解析的名称才属于语法错误（HIGH）
M009-non-mandated-keyword	产品要求使用 flowchart 的地方使用了 graph

规则：

• 对 PRD 以及任何包含图表的产品文档运行验证器。
• 将验证器发现的问题原样纳入报告——严重级别、位置和建议补丁均由验证器提供；不要改写或重新评定。
• 此阶段为只读（生命周期写入范围生命周期写入范围）：修复工作由 /product-implement 或人工负责，绝不由此技能执行。
• 无法识别的图表类型属于 MEDIUM，绝不属于 HIGH——规则集不得造成语法错误误报。
• 已声明类型但完全没有语句时，图表仍会渲染（生成空图表）：验证器将其报告为 MEDIUM（M005-empty-body），定位在类型声明处——绝不视为语法错误。只有格式错误的第一条语句才属于 HIGH。
• Mermaid 注释（%% …）或指令（%%{ … }%%）不属于内容——验证器读取代码块的类型或第一条语句时都会跳过它们，因此以注释开头的图表有效。

Phase 8：严重级别评定

严重级别	标准
CRITICAL	违反章程、未记录主要需求
HIGH	PDR→PRD 偏差影响需求、PDR 之间存在冲突
MEDIUM	后果不完整、内容过时、术语偏差
LOW	样式改进、轻微文档缺漏

Phase 9：生成报告

## Product Analysis Report

### Analysis Summary
| Attribute | Value |
|-----------|-------|
| Mode | [Full/PDRs/Sections] |
| Files Analyzed | [List] |
| Analysis Date | [Current date] |

### Findings
| ID | Pass | Severity | Location | Summary | Recommendation |
|----|------|----------|----------|---------|----------------|
| A1 | PDR Quality | MEDIUM | PDR-003 | Missing success metrics | Add metrics section |
| B1 | Inter-PDR | HIGH | PDR-002, PDR-005 | Conflicting target markets | Resolve B2B vs B2C |
| C1 | PDR→PRD | HIGH | PRD:5 | Persona not in PRD | Update PRD section 5 |
| D1 | PRD→PDR | HIGH | PRD:6 | Feature has no PDR | Create PDR |
| F1 | Staleness | LOW | PRD:1 | [PRODUCT_NAME] placeholder | Fill product name |
| G1 | Mermaid Syntax | HIGH | PRD:42 (fence #3) | ` ```mermaid ` block has no content | add the diagram body, e.g. `flowchart TD / A[Start] --> B[End]` |

### Coverage Metrics
| Metric | Value |
|--------|-------|
| PDR Count | [N] |
| PRD Sections Complete | [N]/12 |
| PDR→PRD Coverage | [N]% |
| PRD→PDR Coverage | [N]% |

### Issue Distribution
| Severity | Count |
|----------|-------|
| CRITICAL | [N] |
| HIGH | [N] |
| MEDIUM | [N] |
| LOW | [N] |

### Next Actions
- **CRITICAL issues**: Resolve constitution violations before proceeding
  - Command: `/product-clarify`
- **HIGH PDR quality**: Address missing alternatives and consequences
  - Command: `/product-clarify`
- **PDR→PRD drift**: Update PRD to reflect PDR decisions
  - Command: `/product-implement --update`
- **PRD→PDR drift**: Create missing PDRs
  - Command: `/product-specify` or `/product-init`

关键规则

分析完整性

• 绝不修改文件——此操作为只读
• 绝不臆造缺失内容——如实报告缺失项
• 优先处理违反章程的情况——一律标记为 CRITICAL
• 基于证据给出发现——引用具体位置
• Mermaid 检查阶段不写入任何内容——仅生成报告；由 /product-implement 或人工修复（生命周期的写入范围）

报告规范

• 最多列出 50 项发现——超出的部分汇总到摘要中
• 注明位置——始终引用文件或章节
• 提供可执行的建议——为每项发现给出修复建议
• 计算覆盖率指标——量化完整程度

配置

• PDR_DRAFTS_DIR — {REPO_ROOT}/.adlc/drafts/pdr
• PRD_FILE — {REPO_ROOT}/docs/adlc/product/PRD.md
• CONSTITUTION — {REPO_ROOT}/docs/adlc/memory/constitution.md（回退至旧路径 .adlc/memory/constitution.md）
• MERMAID_LINTER — {REPO_ROOT}/.agents/skills/architect-clarify/scripts/bash/mermaid-lint.sh（architect-clarify 中的规范版本；需要安装该技能）

与 12-Factor 的对齐

• Factor IX（验证优先）：在下游工作开始前验证产物
• Factor XI（指令即代码）：检查受版本控制的指令质量

验证

• 已加载并盘点所有产物
• 已对每个文件应用 PDR 质量检查清单
• 已验证各 PDR 之间的一致性
• 已完成双向漂移检测
• 已执行陈旧项扫描
• 已验证 Mermaid 语法（已运行共享检查器；每个错误代码块均包含严重程度、位置和补丁）
• 已正确分配严重程度
• 报告已按发现项表格的结构编写
• 已计算覆盖率指标
• 已通过命令提出后续操作建议
• 未修改任何文件