product-roadmap

product-roadmap

此技能的作用

跟踪跨越四个真相层级的产品里程碑进度——因为“已完成”比“任务已完成”是更强的说法：

层级	问题	来源
决策	是否已作出/批准决策？	PDR 状态（Proposed → Accepted → Completed）
执行	是否已完成工作？	通过 MCP 获取的实时 issue 状态（GitHub / GitLab / Jira / Linear）
证据	代码是否确实体现了这一点？	代码与 PDR 验证（init 概念）
门槛	是否达到了标准？	里程碑 PDR 门槛表

只有四个层级全部为绿色，里程碑才算正式生效。否则会发出“完成意味着什么”的警告。

适用场景

• 每周进度检查
• 发布前验证里程碑是否完成
• 季度路线图审查
• 关闭 issue 后检查里程碑是否可以晋级

不适用场景

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

执行步骤

阶段 A：加载 PDR

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

读取 PDR 文件（优先读取 memory，找不到时再读取 drafts；memory 会根据共享布局，依次读取 docs/adlc/memory/pdr/ 和旧版 .adlc/memory/pdr/）：

1. {REPO_ROOT}/docs/adlc/memory/pdr/PDR-*.md + 旧版 {REPO_ROOT}/.adlc/memory/pdr/PDR-*.md（Accepted/Completed）
2. {REPO_ROOT}/.adlc/drafts/pdr/PDR-*.md（Proposed/Discovered）

识别里程碑：查找包含 Category: Milestone 的 PDR。这些 PDR 定义路线图结构，并包含 ### Gates 表、### Features Included 表、### Done Means 定义，以及可选的 ### Tracker Milestone URL。

阶段 B：通过 MCP 获取 issue 状态

从所有 PDR 中提取 issue URL——查找包含完整 URL 的 ### Issues 章节。

根据 URL 主机名检测跟踪器：

URL 主机名	跟踪器	MCP 工具模式
github.com	GitHub	github_* MCP tools
gitlab.com	GitLab	gitlab_* MCP tools
*.atlassian.net	Jira	jira_* MCP tools
linear.app	Linear	linear_* MCP tools

查询 issue 状态——对于每个 issue URL，使用对应的 MCP 工具获取状态（open/closed/in-progress）：

GitHub:   gh issue view NNN --json state,title,labels  (CLI fallback if MCP unavailable)
GitLab:   glab issue view NNN                            (CLI fallback)
Jira:     jira issue view ISSUE-KEY                      (CLI fallback)
Linear:   linear issue view ISSUE-ID                     (CLI fallback)

原生里程碑链接——如果里程碑 PDR 包含 ### Tracker Milestone URL：

• 直接从跟踪器获取原生进度（已关闭/总数 + 到期日期）
• 将其作为权威执行汇总；该里程碑跳过逐个 issue 查询

降级方案（MCP 或 CLI 不可用时）：

1. 尝试使用该跟踪器的 MCP 工具
2. 回退到 CLI（gh/glab/jira/linear）
3. 如果两者都不可用 → 将 issue 引用报告为“状态未知”，并针对每个跟踪器发出一条警告

每个 issue 的执行状态：

状态	含义
closed / done	✅ 工作已完成
open + 进行中标签/负责人	🔄 进行中
open + 未分配	⏳ 尚未开始

阶段 C：代码与 PDR 验证（Init 概念）

代码才是事实依据；PDR 是声明。如果某项功能标记为已完成，但代码中没有任何体现，那就是偏差。

对里程碑中的每个功能 PDR，验证代码证据：

模式 A——明确证据（首选）：

• 阅读 PDR 的 ### Evidence 章节（代码路径/符号列表）
• 验证每个路径是否存在：test -f "{path}" 或 test -d "{path}"
• 状态：verified（所有路径均存在）| stale（部分路径缺失）| missing（没有 Evidence 章节）

模式 B——启发式（回退方案，采用 init 风格）：

• 没有 Evidence 章节 → 复用 product-init 的目录检测逻辑
• 检查 PDR 的 Feature-Area 目录是否存在：test -d "src/{feature-area}/"
• 可选：在代码库中搜索标题关键词
• 置信度较低——报告为“启发式证据”

交接规则：深入重新发现不属于 roadmap 的工作。当标记为“Completed”的条目缺少证据或证据过时，报告会写明：“⚠️ 缺少代码证据——运行 /product-init 以重新发现”。Roadmap 只做轻量检查；完整发现仍由 init 负责。

阶段 D：汇总门槛

阅读每个里程碑 PDR 的 ### Gates 表格。对于每个门槛：

门槛类型	检查方法
engineering	检查关联 issue 的状态或 Evidence 验证结果
sign-off	检查是否有审批证据（已记录日期、已注明审批人）
time	根据切换日期与所需周期计算经过的天数

门槛状态：green（符合标准且已记录证据）| pending（尚未符合）| unknown（没有门槛部分——旧版 PDR）

阶段 E：报告

生成合并后的四层进度报告：

## Product Roadmap Progress

### M01: Q2 User Auth — *Done means: production traffic on new auth, legacy login retired*
Tracker: github.com/org/repo/milestone/3 (native: 67% closed, due Sep 5)

| Item | Decision | Execution | Evidence | Status |
|------|----------|-----------|----------|--------|
| PDR-003: OAuth2 login | ✅ Completed | ✅ 3/3 closed (#142–#144) | ✅ src/auth/oauth/ verified | Live |
| PDR-004: SSO | ✅ Accepted | 🔄 2/4 closed (#186–#189) | ⚠️ no evidence section | In progress |
| PDR-005: Password reset | 🔄 Proposed | ⏳ 0/2 (#190, #191) | ❌ src/auth/reset/ missing | Not started |

| Gate | Type | Owner | Status |
|------|------|-------|--------|
| Security review passed | engineering | Sec team | ✅ green |
| Clinician sign-off | sign-off | Maya | ⏳ pending |
| 7-day cooling period | time | Lead | ⏳ pending (day 3/7) |

**Features**: 1/3 · **Issues**: 5/9 closed · **Gates**: 1/3 green · **Live**: No

⚠️ Done-means check: "production traffic on new auth" cannot be true while
2 items lack execution and 2 gates are pending.

完成标准警告——当里程碑声称“已上线”或“已完成”，但各层并非全绿时：

条件	警告
所有功能均为 Completed，但仍有未关闭的 issue	"⚠️ 功能已声称完成，但仍有 N 个 issue 未关闭——执行尚未完成"
所有 issue 均已关闭，但缺少代码证据	"⚠️ issue 已关闭，但缺少代码证据——请使用 /product-init 验证"
所有功能均已完成，但仍有待处理的门槛	"⚠️ 功能已完成，里程碑尚未上线——仍有 N 个待处理门槛：[列表]"
里程碑标记为 Completed，但没有门槛部分	"⚠️ 里程碑没有门槛——请考虑添加验收标准"

跨里程碑汇总：

## Overall Roadmap

| Milestone | Target | Features | Issues | Gates | Live |
|-----------|--------|----------|--------|-------|------|
| M01: Q2 User Auth | Sep 5 | 1/3 | 5/9 | 1/3 | No |
| M02: Q3 Enhancements | Oct 15 | 0/2 | 0/5 | 0/2 | No |

阶段 F：更新状态（可选）

仅在用户明确请求更新时（例如，在参数中包含“update”）：

对于每个功能 PDR：

• 所有关联 issue 均已关闭且证据已验证 → 将状态更新为 Completed
• 仍有 issue 未关闭或缺少证据 → 阻止更新，报告："无法将 PDR-XXX 标记为 Completed：有 N 个 issue 未关闭 / 缺少证据"
• 例外：用户明确说“force” → 更新并添加警告注释

对于每个里程碑 PDR：

• 所有功能均为 Completed且所有门槛均为绿色 → 将状态更新为 Completed
• 否则 → 阻止更新，报告待处理事项/门槛
• 例外：用户明确说“force” → 更新并添加警告

写入更新后的 PDR 文件，设置新状态，同时保留所有其他内容。

任何更新后都要重新生成 pdr.md 索引。

Tracker 检测顺序

查询 issue 状态时，按以下顺序检测可用工具：

1. MCP 工具（首选）——检查已连接的 MCP 服务：

   • GitHub：github_* 工具可用
   • GitLab：gitlab_* 工具可用
   • Jira：jira_* 工具可用
   • Linear：linear_* 工具可用

2. CLI 回退方案——如果对应 Tracker 的 MCP 不可用：

   • GitHub：gh CLI
   • GitLab：glab CLI
   • Jira：jira CLI
   • Linear：linear CLI

3. 无法访问——如果某个 Tracker 的 MCP 和 CLI 均不可用：

   • 将 issue URL 报告为“状态未知”
   • 每个无法解析的 Tracker 发出一条警告
   • 继续检查决策、证据和门槛层

关键规则

四层诚信原则

• 只有四层（决策 + 执行 + 证据 + 门槛）全部为绿色时，里程碑才算已上线
• 切勿仅凭一层就报告“已完成”
• 各层不一致时，必须提供完成标准警告

Issue 引用

• PDR 中的 issue URL 必须是完整 URL（主机名决定 Tracker）
• 原生 Tracker 里程碑链接可选，但推荐使用（用于提取原生进度）
• 缺少 issue 引用 → 执行层报告为“没有 Tracker 关联”

代码验证

• 模式 A（显式 Evidence）为首选——PDR 应包含带代码路径的 ### Evidence
• 模式 B（启发式）为回退方案——置信度较低，报告时应注明
• 深度重新发现属于 init 的工作，而不是 roadmap 的工作——应提供建议并移交

状态更新

• 有待处理的 issue、门槛或证据时，--update 会阻止更新，除非用户明确覆盖
• 仅更新 PDR 状态，不直接更新 PRD——/product-implement 会重新生成 PRD
• 更新状态时保留 PDR 的所有其他字段

向后兼容

• 没有 ### Gates 的 PDR → gates 层 =“未声明门禁”+ 提示添加门禁
• 没有 ### Issues 的 PDR → 执行层 =“无跟踪器关联”
• 没有 ### Evidence 的 PDR → 证据层 =启发式（模式 B）
• 旧版里程碑仍可使用 — 完成状态仅依据功能，并建议采用门禁

配置

• PDR_DRAFTS_DIR — {REPO_ROOT}/.adlc/drafts/pdr
• PDR_MEMORY_DIR — {REPO_ROOT}/docs/adlc/memory/pdr（兼容读取旧版 .adlc/memory/pdr；计数会汇总两个根目录）
• PRD_FILE — {REPO_ROOT}/docs/adlc/product/PRD.md
• MCP 服务 — GitHub、GitLab、Jira、Linear（自动检测）
• CLI 工具 — gh、glab、jira、linear（备用方案）

与 12-Factor 的一致性

• 因子 III（使命定义）：通过诚实的完成标准语义跟踪使命进度
• 因子 IX（验证优先）：根据代码证据和实时跟踪器状态验证声明
• 因子 XI（指令即代码）：门禁状态在 PDR 文件中进行版本控制

常见的自我安慰

自我安慰	实际情况
“问题都已关闭，所以事情完成了。”	问题关闭并不能证明代码可用。证据层会发现偏差。
“我直接手动将 PDR 标记为已完成就好。”	门禁未全部通过时，“已完成”只是一种声明，而非已验证状态。--update 会阻止此操作。
“我们不需要问题跟踪 — PDR 状态就够了。”	自行报告的状态会产生偏差。实时跟踪器状态才是执行情况的事实依据。
“路线图无法访问跟踪器，那我们就跳过吧。”	系统内置了降级处理 — 报告“状态未知”，并继续检查其他层。

危险信号

• 在门禁仍待处理时将里程碑标记为上线 — 门禁是硬性标准，不是建议。
• 没有代码证据就相信问题状态 — 问题可能过早关闭；代码才是事实依据。
• 跳过完成标准检查 — “代码已就绪” ≠ “生产流量已迁移”。设置“完成意味着”字段正是为了避免这种混淆。
• 在路线图中执行完整发现 — 深入的重新发现属于 init 的工作。路线图只做轻量检查并移交后续工作。

验证

• 已加载所有 PDR 文件（记忆 + 草稿）
• 已识别里程碑 PDR 及其 Features Included 和 Gates 表
• 已从 PDR 中提取问题 URL
• 已通过 MCP 查询问题状态（或使用 CLI 备用方案，或报告为未知）
• 已获取存在关联时的原生跟踪器里程碑进度
• 已验证代码证据（模式 A 为显式验证，模式 B 为启发式）
• 已汇总各里程碑的门禁状态
• 已生成包含逐项状态的四层报告
• 已针对各层不匹配的情况发出完成标准警告
• 已生成整体路线图摘要表
• 已在存在待处理层时正确阻止 --update（如果有此要求）
• 任何更新后都已重新生成 pdr.md 索引
• 除非明确请求 --update，否则未修改任何文件