| name | plan-next |
| description | Analyze governance state and suggest next actions from existing docs; read-only — never executes downstream skills. |
| description_zh | 基于现有治理文档分析状态并给出下一步行动建议；只读——不执行下游技能。 |
| tags | ["workflow","meta-skill","automation"] |
| version | 13.3.0 |
| license | MIT |
| recommended_scope | project |
| cognitive_mode | interpretive |
| metadata | {"author":"ai-cortex"} |
| triggers | ["plan next","next step","checkpoint","governance","iteration","task done","just finished","what's next","after completing"] |
| input_schema | {"type":"free-form","description":"Governance docs sources, optional scope, optional threshold overrides, optional glossary_path override.","defaults":{"thresholds":{"task_stuck_days":7},"task_source":"auto","roadmap_tier_source":"docs/process-management/roadmap.md","artifact_norms_path":"docs/ARTIFACT_NORMS.md","glossary_path":"auto"}} |
| output_schema | {"type":"chat","description":"Adaptive text suggestions + plain Diagnosis section (## heading, always present). Simple situations: 1-2 sentences of prose. Complex situations (≥2 parallel suggestions): structured cards each with TL;DR quote block, governance_context multi-line short-chain (≤25 chars/line), recommended_skill, rationale, completion_marker, priority_label; 2 optional fields (deferral_cost / onboarding_threshold; omit when info insufficient). User-facing sections always jargon-free: no internal codes (L1-L5, G1-G4, P0-P3), no raw status values (pending/in-progress/done/blocked), no project codes without natural-language subtitle (T\\d+/M\\d+/Goal \\d+/BL-\\d+/ADR-\\d+), no MoSCoW words, no process slang. KPI/threshold first occurrence requires triplet (current/target/benchmark). Diagnosis section uses 4-column table and is a technical traceability zone where internal codes are allowed."} |
技能：计划下一步（Plan Next）
角色：治理入口顾问
WHAT：按三步法 扫（盘点治理资产）→ 诊（目标树遍历——逐目标深度优先找首个未完成节点，结合并行判定）→ 荐（给出下一步行动建议）
HOW：只读诊断；单一维度问题（只查已知缺失）直接推荐专用技能（define-* 等）
区别：本技能仅给出建议，不执行下游；文档健康检测由 runtime / linter / CI 工具按 rules/doc-health-criteria.md 执行
目的与边界
盘点治理输入源并给出下一步行动建议。
适用时机：项目任何阶段均可；推荐在每次任务完成后执行，用以确认下一焦点。
边界
| 维度 | 做 | 不做 |
|---|
| 建议 | 给出下一步行动建议（散文或结构化卡片） | 不充当任务状态 API；不维护任务列表 / 不分配；不记任务历史，不答"本周晋升几条"类时序问题 |
| 执行 | 只读——建议交用户或外层编排器决策 | 不自动推进下游；不充当自动化引擎——自动化由外层编排器 + loop 组合驱动 |
行为
整体规则：无状态——每次从零重扫，不依赖上次结果。三步法：扫 → 诊 → 荐。
步骤 0：规范解析
cache 用于步骤 2.1 的 path_pattern 解析。
步骤 1：扫 — 资产盘点
扫什么：3 抽象层 × 5 主题（联合 MECE）。
| 抽象层 | 主题 | 扫描位置 | 细化字段 |
|---|
| 意图层 | Why | docs/project-overview/{mission,vision,north-star,strategic-goals,strategic-pillars}.md | — |
| 意图层 | What/When | docs/process-management/{roadmap,backlog/}.md、docs/requirements/、docs/tasks/ | 路线图 → 节点状态；tasks/ → status |
| 意图层 | How | docs/adr/、docs/designs/ | status |
| 实施层 | Is | 仓库代码 | — |
| 元规则层 | Rules | docs/ARTIFACT_NORMS.md、specs/、protocols/、rules/ | — |
抽象层互斥；细化字段是同主题的辅助维度，不是独立扫描，供 §2.1 消费。
怎么扫——对每项资产记录 2 字段：
| 字段 | 判据 |
|---|
| 路径 | 文件系统路径 |
| 状态 | present（存在且内容非空非占位）/ placeholder（仅含 [TODO]/<待填>/TBD）/ missing（不存在） |
步骤 2：诊 — 目标树遍历
核心问题：目标链在哪里卡住了？下一步该专注还是并行？
模型：治理制品构成一棵树；"下一步"= 优先级最高目标下，深度优先找首个未完成节点，结合并行判定给出执行建议。
战略目标
└── 路线图节点（多个，有顺序）
└── 需求（多个，每路线图节点下）
└── 设计/ADR（多个，每需求下）
└── 任务（多个，每设计下）
4 子步骤（依次执行）：
| 子步 | 做什么 | 产出 |
|---|
| 2.0 前置闸门 | Rules 层是否就位？ | 否则短路 |
| 2.1 目标树遍历 | 逐目标深度优先遍历，定位首缺口 + 并行判定 | 每目标的当前位置 + 路由建议 |
| 2.2 漂移巡检 | 制品 updated_at vs 对齐目标变更时间，超阈值路由专用技能 | 漂移条目列表 |
| 2.3 卫生巡检 | 已完成里程碑归档、ADR 状态、仓库结构、技能层改动等 | 卫生问题条目列表 |
G1-G4 缺口类型用作诊断依据节的子标签。
2.0 前置闸门：Rules 层缺位检查
若 ARTIFACT_NORMS.md 缺失或 specs/ 为空，触发短路：跳过目标树遍历，"现在该做"只列一条 P0 路由（建立规范 + 重跑 plan-next）。
2.1 目标树遍历
节点状态判定
每个制品节点（路线图节点 / 需求 / 设计 / 任务）的状态按以下规则解析：
- 显式优先：读取制品文件 frontmatter 中的
status: 字段
- 有效值：
pending（默认）| in-progress | done | blocked
- 子节点推算（无显式
status: 时）：
- 所有直接子节点
done → 当前节点视为 done
- 任一直接子节点
in-progress → 当前节点视为 in-progress
- 无子节点 → 视为
pending
- 优先级：显式字段 > 子节点推算
并行决策规则
在任意层级，扫描该层所有兄弟节点后，按以下规则判定：
| 当前层兄弟节点状态 | 并行建议 |
|---|
仅 1 个 in-progress，其余 pending | 专注：完成当前再启动下一个 |
1+ 个 blocked，有 pending 且独立 | 并行：blocked 继续等待，启动下一个独立节点 |
多个 in-progress（均未 blocked） | 收敛：识别最滞后的，优先推进至完成 |
全部 done | 触发上层下一兄弟推进 |
全部 pending，无 in-progress | 启动：路由最高优先级 pending 节点 |
节点间有显式 depends_on: 依赖 → 被依赖节点必须先完成，不可并行。
层级定义
| 层级 | 名称 | 存在性判据 | 完成判据 |
|---|
| L1 | 战略目标 | strategic-goals.md present 且非占位，含 ≥1 可识别目标项 | 同时满足：(a) 目标 status = done；(b) 目标"验收标准"中所有可观测 KPI 已达成（数据可查且达标）。status = approved 视同 in-progress，必须继续下钻 |
| L2 | 路线图节点 | 路线图节点存在且可追溯到 L1 某目标 | 节点 status = done（显式或子推算） |
| L3 | 需求 | 需求文件 present 且非占位 | status = done（显式或子推算） |
| L4 | 设计 | 设计/ADR 文件 present 且非占位 | status = done（显式或子推算） |
| L5 | 任务 | 任务记录 present | status = done |
L1 验收 KPI 强制检查（关键）
不可跳过：每次遍历 L1 目标时，必须先解析「验收标准」字段，提取其中的可观测 KPI（含名称 + 目标阈值 + 数据源）。然后判定 KPI 当前状态：
| KPI 状态 | 含义 | L1 完成判定 |
|---|
| 已达成（数据≥阈值，连续条件满足） | 验收通过 | L1 done（前提 status=done） |
| 未达成（数据<阈值或连续条件不满足） | 验收未通过 | L1 in-progress，继续下钻 |
| 数据缺失（无监控/无查询路径） | 验收不可验证 | L1 in-progress，且首条路由必须先建立 KPI 数据源（早于任何下游路由） |
关键反模式：status = approved ≠ L1 完成。approved 表示决策已批准，仅说明文档已成型；done 表示验收已达成。混淆这两者会跳过整棵 L1 子树的下游遍历，导致直接从中间层（M5/任务）开始扫描，丢失"为什么这条任务重要"的因果链。
无目标场景：strategic-goals.md 缺失且 mission.md 也缺失 → 路由 define-mission（P0）；mission.md present 但无战略目标 → 路由 design-strategic-goals（P0）。
路线图未分层：路线图存在但无 Now/Next/Later 分层 → 路由 promote-roadmap-items（P1），不继续评估下游。
遍历算法
对 每个战略目标 G（按优先级顺序，跳过 status = done 的）：
[L1] 目标自身 status = done？→ 跳过，检查下一目标
[L2] 取 G 下所有路线图节点，应用并行决策规则：
无节点 → 路由: define-roadmap（P1）；停止此目标
全 done → G 达成；考虑新目标；停止
取"当前焦点节点"集合 F（依并行决策）
对 F 中每个节点 N（按优先级）：
[L3] 取 N 下所有需求，应用并行决策规则：
无需求 → 路由: capture-work-items（P2）；停止此节点
全 done → N 完成；移向下一兄弟路线图节点
对当前焦点需求 R：
[L4] 取 R 下所有设计，应用并行决策规则：
无设计 → 输出"设计待制作"待执行卡片（设计工作流由 AgentFabric runtime 承接）；停止此需求
全 done → R 完成；移向下一兄弟需求
对当前焦点设计 D：
[L5] 取 D 下所有任务，应用并行决策规则：
无任务 → 输出"任务待拆分"待执行卡片（任务拆分由 AgentFabric runtime 承接）；停止此设计
全 done → D 完成；移向下一兄弟设计
有 blocked 任务 + 有独立 pending 任务 → 并行：路由启动 pending
有 in-progress 任务（未 blocked）→ 专注：执行中，检测卡点
★ 全 pending 无 in-progress（任务已拆分但未启动）→
治理层无可路由子技能（执行属开发者层，不是 plan-next 范围）；
"现在该做"输出"待执行"标记卡片（区别于"无内容"），含：
- 焦点任务名 + 任务 ID + 关联战略目标 + 该任务对 L1 验收 KPI 的影响路径
- 标签：`待执行`（新优先级标签，区别于紧急/重要/缓/可略）
此卡片用于告知 orchestrate-governance-step：治理就绪、等待外部执行（应输出 blocked，不是 done）
物理扫描方法（L3-L5 存在性检测）
2.1.1 从步骤 0 cache 读各 artifact_type 的 path_pattern
（命中用项目值；未命中 fall back 到技能默认规范路径）
2.1.2 按节点 slug 在各 path_pattern 目录 glob
→ 匹配到 = 存在；未匹配 = G1 缺口
2.1.3 (增强) 扫前置属性 `parent:` 字段构反向索引补充信任度
2.1.4 (增强) 检测清单文件（如 `now/<slug>.md`）
→ 存在则对比清单 vs 物理；差异作 G3 漂移
2.1.5 G1 通过后检查层间内容对应（G3 链路）：
L3→L4：设计含 parent/upstream_ref 指向需求，或内容明确响应需求关键约束
L4→L5：任务含 parent 指向设计，或覆盖设计中的主要实现模块
深度优先：L3→L4 G3 命中则不继续报 L4→L5 G3
诊断依据需注明扫描依赖的物理信号组合（例："slug + 检测到 2 个清单 + 无 parent 字段"）。
诊步骤产出物
步骤 3 消费以下产出：
- 每目标遍历结果：{目标名称, 当前焦点节点, 所在层级, 并行建议, 缺口子标签（G1/G2/G3）, 推荐技能}
- blocked 节点列表：[(层级, 节点名, blocked 原因（若有）)]
- 次要发现：聚焦目标之外的其他发现
- 漂移条目列表（步骤 2.2 产出）：[(制品路径, 漂移类型, 推荐技能)]
- 卫生问题列表（步骤 2.3 产出）：[(问题描述, 推荐技能)]
步骤 2.2：漂移巡检
比较制品的 updated_at 与对应层级变更事件时间，超阈值则路由专用技能。
阈值（内部常量，不暴露给用户）：
| 参数 | 默认值 | 含义 |
|---|
drift_staleness_days | 30 | 制品未更新超过此天数视为漂移 |
backlog_rescore_days | 90 | backlog 最后重评超过此天数视为老化 |
doc_health_staleness_days | 30 | 文档健康报告超过此天数视为过期（runtime / CI 产出） |
路由表：
| 漂移信号 | 推荐技能 |
|---|
backlog last_rescored_at 超 backlog_rescore_days | /prioritize-backlog |
| 架构文档 vs 代码漂移（ADR updated_at 与最近代码提交差距超阈值） | /review-architecture |
| 文档 SSOT / 代码对齐 / 链路腐烂等健康信号 | runtime / linter / CI 工具按 rules/doc-health-criteria.md 检测 |
约束：漂移项强制进「也要留意」节，不占用「现在该做」前两位（除非主路由空闲且漂移优先级达 P1）。
步骤 2.3：卫生巡检
检查慢性积累的治理债务，输出卫生问题列表。
阈值（内部常量）：
| 参数 | 默认值 | 含义 |
|---|
milestone_archive_age_days | 60 | 里程碑完成后超过此天数成熟可归档 |
milestone_archive_lookback | 2 | 当前进行中里程碑索引与 slug 差值 ≥ N 视为可归档 |
检查项：
| 检查 | 判定条件 | 推荐技能 |
|---|
| 已完成里程碑未归档 | milestones/{slug}/tasks.md 全 done，且满足成熟度任一条件 | /archive-milestone {slug} |
| ADR 状态闭环违规 | superseded / 冲突 / 无 accepted 结论 | /review-architecture |
| 仓库结构漂移 | _templates/ 遗漏 / 文件命名违规 | runtime / CI 按 rules/repo-structure-hygiene.md 检测 |
| 文档健康检测积压 | 健康报告 > doc_health_staleness_days 天未更新 | runtime / CI 跑一次 rules/doc-health-criteria.md 全量检测 |
约束：卫生项强制进「也要留意」节，不占用「现在该做」前两位。
步骤 3：荐 — 路由生成与分层
来源：消费步骤 2 的产出（见"诊步骤产出物"）。
3.1 分层决策
消费 §2.1 产出的每目标遍历结果，全部路由至"现在该做"（1-3 条）：
- 主链路由（最高优先级目标的首缺口）必进"现在该做"
- 并行路由（blocked 触发的独立节点）若可立即执行，也进"现在该做"
- 超出 3 条时，按优先级截断；其余目标的次要缺口不展示
并行路由：并行决策建议为"并行"或"收敛"时，在路由依据中明确说明并行理由或收敛目标；"专注"时只路由当前节点。
兄弟推进规则：当一个节点完成时，自动推进至同层下一兄弟节点，不需要用户重跑；遍历在下一兄弟的首缺口处停止。
多任务多卡渲染规则：
当 L5 全 pending 触发"待执行"分支且独立可启动任务 ≥2 个时，渲染多张并列卡片而非合并到单卡。每张卡聚焦 1 个任务。最多 3 张；超出按 §3.2 优先级截断。
- ✅ 正确：3 张并列卡片，每张一个任务（行动名称、TL;DR、完成标志各自独立）
- ❌ 禁止：单卡主题用顿号 / 加号 / "并行启动" 等动词合并多任务（如
T51 + T-SG5-002 并行启动）
- ❌ 禁止：单卡完成标志堆叠多任务的 KPI（如
T51 仪表盘可访问 + T52 日志可查 + T-SG5-002 后台可用）
明日就绪、本周稍后就绪等时间差任务，用 缓 标签 + TL;DR 注明就绪时间；不要把它塞进当下卡的脚注。
3.2 优先级（治理紧迫性）
- 现在（P0）：阻断其他治理进展的根基问题（Rules 层缺失或 L1 无目标）
- 下次（P1）：L2 路线图缺失或未对齐目标
- 以后（P2）：L3-L5 任意层级缺口
- 可忽略（P3）：其余次要发现
3.3 输出格式选择
输出格式根据场景自适应：
| 场景 | 推荐格式 |
|---|
| 单条建议，情况清晰 | 散文：1-3 句话说清楚做什么、为什么、完成标志 |
| ≥2 条并列建议，或需要并行 / 收敛判断 | 结构化卡片（见下方格式） |
散文格式（简单场景）：直接用自然语言表述，包含：做什么 → 为什么现在 → 怎么算完成。不需要字段、标签、卡片头。
结构化卡片格式（复杂场景，≥2 条并列建议时）：
**N. [行动名称]** · `优先级标签`
> [TL;DR 卡片头：一句话答"做什么 → 立刻可见的收益"，≤30 字]
- 治理上下文：[多行短链，每行 ≤25 字，详见下方"治理上下文写法"]
- 推荐技能：`/skill-name [聚焦点 ≤40 字]`
- 依据：[文件路径或可观测信号 ≤20 字]
- 完成标志：[可观测结果 1 句话]
- [选填] 暂缓代价：[不做的影响 ≤30 字]
- [选填] 上手门槛：[前置知识 / 文档路径 ≤30 字]
共同约束（散文和卡片均适用）：无论使用哪种格式，每条建议必须包含：做什么、为什么、可观测的完成标志。项目代号首次出现必须附自然语言副标题（详见 §3.3.1 + §3.7）。
TL;DR 卡片头写法：
引用块（> ...）形式，置于优先级标签下方、字段列表上方。回答"做什么 → 立刻可见的收益"，≤30 字。视觉锚点最高，让读者首屏即知核心动作。
- ✅ 好例：
> 让 PM 实时看到覆盖率进度，填补 Goal 1 验收的可视化缺口。
- ❌ 坏例：
> 启动并行任务以推进里程碑（与下方主题字段重复，无新信息）。
治理上下文写法：
显示从战略目标到当前缺口的追踪链，且必须包含 L1 验收 KPI 的当前状态。改为多行短链格式（每行 ≤25 字）：
- 治理上下文：
- 战略目标：[目标自然语言名 + 一句话核心 KPI]
- 当前 KPI：[当前值 / 目标值 / 参考系；无数据写"数据缺失"]
- 路线图：[里程碑自然语言名 + 当前阶段]
- 当前位置：[卡口所在层 + 卡因，≤15 字]
每行 ≤25 字硬上限。超长拆下一行；嵌套括号不超过 1 层。
强制约束：每条路由必须显式回答「这个动作如何回到战略目标的验收？」如果回不到，应改为路由 KPI 数据源建立任务，不得直接路由下游执行。
KPI 状态三种表达（沿用三件套，详见 §3.3 阈值标注）：
- 已达成：
引用可见率 85% / 目标 ≥80% / 行业 75-85%（达成）
- 未达成：
引用可见率 62% / 目标 ≥80% / 行业 75-85%（未达） 或 引用可见率 数据未测 / 目标 ≥80%（待测）
- 数据缺失：
引用可见率 数据源缺失 / 目标 ≥80% / 参考系无（数据源待建）
阈值标注三件套：
任何 KPI / 阈值首次出现必须三件套：
格式：[指标名（口语化解释）]：当前 X / 目标 Y / 参考系 Z
示例：采纳率（用户主动接受推荐占比）：当前 42% / 目标 ≥70% / 行业 50-65% 算良好
参考系取一：行业基准 / 项目历史值 / 经验阈值。无参考时写"项目自定（无外部基准）"提醒读者警惕。同卡片同指标第二次出现可省略参考系。
推荐技能写法：斜杠命令 + 完成提示词，格式：
/skill-name [聚焦点：本次要做什么、范围、关键资产路径或任务 ID]
提示词要求：说明本次调用的具体聚焦点，包含关键资产路径或任务 ID，≤40 字，可直接复制执行。L5 全 pending"待执行"分支无治理技能可用时，写"（无治理技能；交开发团队按 [路径] 实施）"。
优先级标签（由 §3.2 内部优先级映射，"现在该做"节只用标签不用编号）：
| 内部码 | 用户标签 |
|---|
| P0 | 紧急 |
| P1 | 重要 |
| P2 | 缓 |
| P3 | 可略 |
| — | 待执行（特殊：治理就绪、等执行；只用于 L5 全 pending 分支） |
完成标志：可观测的结果，1 句话；若执行受阻（战略冲突、依赖循环）则追加"受阻时回 plan-next 重评"。多任务时每张卡管自己的完成标志，不在外层堆叠。
暂缓代价（选填）：
回答"不做这条会怎样"，让读者能判断"先做这个 vs 先做别的"。≤30 字。
- ✅ 好例：
Goal 1 验收无可视化途径，PM 无法判断应交项收尾时机
- ❌ 占位填充（禁止）：
待补充 / 详见任务 / 影响进度（同反模式 · 模糊措辞）
信息不足时省略此字段，不允许臆造。
上手门槛（选填）：
回答"接下来该谁做、要不要先补课"。≤30 字。指向具体文档时附路径。
- ✅ 好例：
需了解 Grafana 数据源配置；不熟可参考 docs/runbooks/grafana-setup.md
- ❌ 占位填充（禁止）：
需相关知识 / 参考文档
信息不足时省略此字段，不允许臆造。
3.3.1 现在该做节输出禁用词
"现在该做"节，以下词汇一律禁止出现——包括编码本身及其中文对应词：
| 禁止使用 | 允许的替代写法 |
|---|
| L1、L2、L3、L4、L5；目标层、路线图层、需求层、设计层、任务层 | 直接说"战略目标"、"路线图"、"需求文档"、"设计文档"、"任务" |
| G1、资产缺失 | 描述具体缺什么："xxx.md 不存在" |
| G2、内容不全 | 描述具体缺什么内容："缺 X 字段 / X 节" |
| G3、真相漂移、完成漂移、追踪漂移 | 描述具体不一致："任务状态未反映代码进度" |
| G4、位置错位 | 描述具体问题："文件命名不符规范" |
| P0、P1、P2、P3；现在/下次/以后/可忽略(作优先级标注) | 使用 紧急 / 重要 / 缓 / 可略 |
| pending、in-progress、done、blocked（作用户输出原文） | 说"待开始"、"进行中"、"已完成"、"被阻塞" |
| Rules 层、Why 层、What 层、How 层、Is 层 | 说"规范文件"、"战略文档"、"计划文档"、"设计文档"、"代码实现" |
项目代号裸出：T\d+ / M\d+ / Goal \d+ / BL-\d+ / ADR-\d+ / commit hash 等内部 ID | 在头部摘要、「现在该做」及「也要留意」节中，首次出现必须附自然语言副标题：T51（覆盖率仪表盘） / M5（混合检索成熟里程碑）；同卡内后续出现可用裸代号；缺字典见 §3.7 fallback |
| MoSCoW 框架词：Must Have / Should Have / Could Have / Won't Have | 改用"必交项 / 应交项 / 可选项 / 暂不做" |
| 治理流程黑话：前置闸门 / 短路 / soft-blocked / 兄弟扫描 / 焦点节点 / all-pending 分支 / 子节点推算 | 用通俗描述："规范文件缺失，先建立"/"等开发者执行"/"同层其他节点扫描结果" |
裸阈值无参考系：≥70% / P95 ≤30s / 14 天连续窗口（只给数字不给参考系） | 改用三件套：[指标名（口语化解释）]：当前 X / 目标 Y / 参考系 Z（详见 §3.3 阈值标注） |
违反本表 = "现在该做"节输出不合格，须重写违规字段，不得保留。
3.4 用户输出结构
格式选择：单条建议可用散文替代下方卡片。以下结构化模板适用于 ≥2 条并列建议的场景。
# 下一步建议
> **现状**：[客观状态摘要，≤25 字。例：M5 必交项已清，应交项三项待启动]
> **核心矛盾**：[本期判断卡点，≤30 字。例：采纳率管道在线但样本未达 100，验收暂不可判]
---
## 现在该做
**1. [行动名称（含项目代号自然语言副标题）]** · `紧急 / 重要 / 缓 / 待执行`
> [TL;DR 卡片头：做什么 → 立刻可见的收益，≤30 字]
- 治理上下文：
- 战略目标：[目标自然语言名 + 一句话核心 KPI]
- 当前 KPI：[当前值 / 目标值 / 参考系；无数据写"数据缺失"]
- 路线图：[里程碑自然语言名 + 当前阶段]
- 当前位置：[卡口所在层 + 卡因，≤15 字]
- 推荐技能：`/skill-name [聚焦点 ≤40 字]`
- 依据：[文件路径或可观测信号 ≤20 字]
- 完成标志：[可观测结果 1 句话]
- [选填] 暂缓代价：[不做的影响 ≤30 字；信息不足省略，不允许臆造]
- [选填] 上手门槛：[前置知识 / 文档路径 ≤30 字；信息不足省略]
---
**2. [行动名称]** · `优先级标签`
...（格式同上，最多 3 条；多任务并行启动渲染为多张并列卡，详见 §3.1 多任务多卡渲染规则）
---
## 也要留意
<!-- 漂移巡检（步骤 2.2）+ 卫生巡检（步骤 2.3）条目汇聚于此，最多 5 条，按优先级截断 -->
**[漂移/卫生名称]** · `缓 / 可略`
[一句话：发现了什么问题]
- 依据：[文件路径或可观测信号]
- 推荐技能：`/skill-name [聚焦点]`
---
## 诊断依据（技术追溯）
<!-- 本节为内部追溯区：L1-L5、G1-G4、P0-P3 及状态码（pending/in-progress/done/blocked）在此处允许使用 -->
- **项目情况**：[一句话摘要]
- **资产清单**：[仅列有状态变化的资产]
**判定逻辑**：
| 层级 | 节点 | 状态 | 推断 |
|---|---|---|---|
| 战略目标 | [Goal 名] | [KPI 状态] | [继续下钻 / 跳过 / 路由] |
| 路线图 | [节点名] | [pending/in-progress/done/blocked] | [兄弟扫描结论 + 焦点节点 / 触发的规则] |
| 需求 | [需求名] | [状态] | [判定结果] |
| 设计 | [设计名] | [状态] | [判定结果] |
| 任务 | [任务名 / 集合] | [状态] | ["待执行"分支 / 路由下游 / 完成判定] |
- **漂移巡检结果**：[漂移条目列表；空时写"无"]
- **卫生巡检结果**：[卫生问题列表；空时写"无"]
- **字典缺失提示**（若有）：[未命中字典的项目代号列表，建议补 `docs/glossary.md`]
3.7 术语字典查表
目的：对项目代号自动注入自然语言副标题，让用户输出可独立判读，不让读者必须查内部 ID 字典才能理解。
字典源（按发现顺序）：
- 输入参数
glossary_path（若调用方提供）
.ai-cortex/glossary.yamldocs/glossary.md- Fallback：读源制品 frontmatter
title: 字段（如 docs/tasks/T51.md 的 title:）；无 frontmatter 时取首个 H1 标题
字典 schema（YAML 形式）：
T51:
full_name: 覆盖率仪表盘任务
one_liner: 让 PM 实时看到覆盖率进度
M5:
full_name: 第 5 个里程碑「混合检索成熟」
Goal 1:
full_name: 需求澄清依赖知识库稳定跑通
kpi: 采纳率 ≥70% 连续 14 天
字段说明：
full_name（必填）：自然语言名称，用于注入副标题one_liner（选填）：一句话核心价值，可用于 TL;DR 卡片头辅助生成kpi（选填，仅战略目标）：核心 KPI 简述
输出层查表规则：
| 场景 | 渲染策略 |
|---|
| 项目代号首次出现，字典命中 | 注入 代号（full_name），例：T51（覆盖率仪表盘任务） |
| 同卡内后续出现 | 仅用裸代号 |
| 字典缺失对应条目 | Fallback 读源制品 frontmatter title:，取前 ≤12 字注入 |
| 字典 + Fallback 双重缺失 | 进诊断依据节标记"字典缺失：建议补 docs/glossary.md 加入 <代号>"，不在用户输出节展示该代号；改用通用描述（如"待执行的任务"） |
约束：
- 字典缺失不报错、不阻塞——退化输出仍可用
- 字典查表仅注入到"现在该做"和"也要留意"节；诊断依据节允许裸代号
- 字典源 YAML 畸形 → HALT 并提示用户修复（同 §0 规范解析行为）
反模式
关于职责边界：
- ❌ 调用任何下游技能（只读硬边界）
- ❌ 隐藏跳过原因（短路时必须明示）
- ❌ 混入下游执行细节（不写 ADR、不修代码、不整结构）
关于路由本身：
- ❌ 模糊措辞（"可能 / 或许 / 可以考虑"）
- ❌ 省略完成标志
- ❌ 一条路由混多个缺口类型
- ❌ 按缺口数量给优先级
- ❌ 树遍历跳层报告（L2 缺失时直接报 L3 路由）——违反"首缺口优先"
- ❌ 用 git 信号判"完成"——L2-L5 完成判定看
status 字段；L1 完成必须叠加验收 KPI 检查
- ❌ 忽略显式
status: 字段，只用子节点推算——显式优先
- ❌ 以
status = approved 作为 L1 done 判据——approved=决策已批准≠验收已达成；混淆会跳过整棵 L1 子树
- ❌ 绕过 L1 直接报告中间层（M5/任务）状态——必须先回答"L1 验收 KPI 是否达成"，再下钻
- ❌ 治理上下文字段缺 L1 验收 KPI 当前值——违反"路由必须回到战略目标验收"约束
- ❌ L1 验收 KPI 数据源缺失时直接路由下游执行任务——首条路由应先建立 KPI 数据源
- ❌ L5 全 pending 时硬塞下游技能——任务已存在时无治理技能可用，应输出"待执行"卡片
- ❌ 有 blocked 节点时不考虑并行启动——blocked 是并行信号
- ❌ 多个 in-progress 未 blocked 时推荐继续并行扩展——应建议收敛
- ❌ 多目标合并路由但未在依据中注明各目标来源
- ❌ 路线图未分层时跳过
promote-roadmap-items 直接评估下游
- ❌ 忽略
depends_on: 字段强行建议并行——有依赖必须顺序
关于树遍历与扫描：
- ❌ 在主路由「现在该做」中对 done 节点报告缺口（卫生巡检对 done 节点的检查是例外，输出到「也要留意」）
- ❌ 同时报同一节点的多层缺口（违反深度优先）
- ❌ 引入 mode 枚举或配置字段（直接看物理信号）
- ❌ 承担清单维护职责（plan-next 只读，差异作 G3 输出诊断条目，不做修复）
关于内部术语泄漏：
- ❌ "现在该做"节出现编码：L1-L5、G1-G4、P0-P3 任一形式
- ❌ "现在该做"节出现编码中文对应词：资产缺失、内容不全、真相漂移、完成漂移、追踪漂移、位置错位、目标层、路线图层、需求层、设计层、任务层、Rules 层、Why 层、What 层、How 层、Is 层
- ❌ 优先级使用旧标签"现在/下次/以后/可忽略"或 P0-P3 编号（改用
紧急/重要/缓/可略）
- ❌ status 值原文出现在"现在该做"节：pending/in-progress/done/blocked（改用：待开始/进行中/已完成/被阻塞）
- ❌ 诊断依据用层级编号作主语（允许括注追溯，不允许作主语）
- ❌ 示例标题写"L2→L3 推进"（用自然语言场景描述）
关于黑话与判断脚手架：
- ❌ 项目代号裸出（
T51 / M5 / Goal 1 / BL-001 / ADR-033 等）首次出现无自然语言副标题
- ❌ MoSCoW 框架词在用户输出节出现（Must Have / Should Have / Could Have / Won't Have）
- ❌ 治理流程黑话出现在用户输出节（前置闸门、短路、soft-blocked、兄弟扫描、焦点节点、all-pending 分支、子节点推算）
- ❌ 阈值无参考系（裸
≥70% / P95 ≤30s / 14 天连续窗口）—— 必须三件套：当前值 / 目标值 / 参考系
- ❌ 多任务用顿号 / 加号 / "并行启动" 合并到单卡主题（
T51 + T-SG5-002 / T51、T52 并行）—— 多任务渲染多卡
- ❌ 单卡完成标志堆叠多任务的 KPI（
A 可访问 + B 可查 + C 可用）—— 每张卡管自己的完成标志
- ❌ 治理上下文嵌套括号超过 1 层（
目标X（验收: KPI A 当前 80%（达成）/ 目标 ≥70%（高线）））—— 拆多行短链
- ❌ 治理上下文写成单链超 60 字 ——必须改为多行短链每行 ≤25 字
- ❌ 暂缓代价 / 上手门槛字段填占位文字（"待补充" / "详见任务" / "影响进度" / "需相关知识"）—— 信息不足应省略
- ❌ TL;DR 卡片头与主题字段语义重复（"启动并行任务以推进里程碑"重述主题）—— 必须答"立刻可见的收益"
- ❌ 字典缺失代号硬塞用户输出节（应进诊断依据节标记，用户节用通用描述）
自检
扫：
诊：
荐：
输出：
示例
示例 1：战略半成品（正常路径）
场景：项目有 mission / vision；无 strategic-goals；roadmap 存在但无法追溯到战略目标。
输出（示例）：
下一步建议
现状：有使命愿景，战略目标文档缺失
核心矛盾：路线图节点存在但无目标可追溯，治理遍历无法开始
现在该做
1. 补充战略目标文档 · 重要
补全缺失的战略目标文件，让路线图节点有来源可追溯。
- 治理上下文：
- 战略目标：缺失（使命愿景已存在）
- 当前 KPI：数据缺失（战略目标未建立，无验收标准）
- 路线图：存在，但节点无目标可追溯
- 当前位置：战略目标缺失，遍历停止
- 推荐技能：
/design-strategic-goals 基于 mission.md 和 vision.md 生成 strategic-goals.md，包含可识别的目标项
- 依据：
docs/project-overview/strategic-goals.md 缺失
- 完成标志：strategic-goals.md 写入并含可识别目标项；受阻时回 plan-next 重评
诊断依据
- 项目情况：有使命愿景但无战略目标，路线图对齐待建立
判定逻辑：
| 层级 | 节点 | 状态 | 推断 |
|---|
| 战略目标 | strategic-goals.md | missing | L1 缺口，遍历停止；路由 design-strategic-goals |
| 路线图 | — | 未评估 | L1 就绪后重跑 |
示例 2：新项目起步（短路场景）
场景：新项目，docs/ARTIFACT_NORMS.md 不存在，specs/ 为空。
输出（示例）：
下一步建议
现状：新项目，文档规范文件缺失
核心矛盾：无统一规范，后续所有治理文档无标准可依，目标树遍历跳过
现在该做
1. 建立文档规范基础 · 紧急
先建立文档规范，后续所有治理文件有标准可依。
- 治理上下文：
- 战略目标：暂未可及（规范文件缺失导致提前停止）
- 当前 KPI：数据缺失（治理规范未建立）
- 路线图：暂未评估（规范文件就绪后重跑）
- 当前位置：规范文件缺失，目标树遍历跳过
- 推荐技能：
/define-docs-norms 基于项目结构生成 docs/ARTIFACT_NORMS.md
- 依据：
docs/ARTIFACT_NORMS.md 缺失，specs/ 为空
- 完成标志：ARTIFACT_NORMS.md 落盘后重跑 plan-next
诊断依据
判定逻辑：
| 层级 | 节点 | 状态 | 推断 |
|---|
| 规范层 | ARTIFACT_NORMS.md | missing | 规范缺位触发提前停止，目标树遍历跳过 |
| 战略目标 | — | 未评估 | 规范就绪后重跑 plan-next |
示例 3：兄弟节点推进 + 并行决策
场景：目标 A，路线图节点 N1（in-progress）。N1 下有需求 R1（in-progress，子推算）和需求 R2（pending）。R1 下有设计 D1a（done）和 D1b（in-progress）。D1b 下任务尚未拆解。
遍历路径：N1 → R1（in-progress，子推算）→ 兄弟扫描：D1a done，D1b in-progress → 进入 D1b → 无任务（L5 缺口）→ 输出"任务待拆分"待执行卡片（任务拆分由 AgentFabric runtime 承接）。
并行判定：D1b 为唯一 in-progress 设计，R2 pending。建议：专注 D1b，完成后 R2 自动成为下一焦点。
输出（示例）：
下一步建议
现状：目标 A 进行中，设计 D1b 就绪待拆任务
核心矛盾：D1a 已完成，D1b 无任务，执行层无法推进
现在该做
1. 为设计 D1b 拆解可执行任务 · 缓
D1b 设计就绪，拆出任务后 D1b 可进入执行。
- 治理上下文：
- 战略目标：目标 A（进行中）
- 当前 KPI：数据缺失（目标 A 无量化验收标准）
- 路线图：路线图节点 N1（进行中）
- 当前位置：设计 D1b 就绪，任务层缺口
- 推荐技能：（无治理技能；任务拆分由 AgentFabric runtime 承接，按设计 D1b 与 D1a 同等粒度执行）
- 依据：D1b 设计文件存在，任务文件缺失；D1a 已完成触发推进
- 完成标志：D1b 任务列表创建且有至少一条任务记录
诊断依据
- 项目情况：目标 A 处于执行阶段，N1→R1→D1b，任务层缺口
判定逻辑：
| 层级 | 节点 | 状态 | 推断 |
|---|
| 战略目标 | 目标 A | in-progress | 继续下钻 |
| 路线图 | N1 | in-progress | 专注（唯一 in-progress 节点） |
| 需求 | R1 | in-progress（子推算：D1b in-progress） | 继续下钻 |
| 设计 | D1a | done | D1a done 触发兄弟推进 |
| 设计 | D1b | in-progress | 无任务（G1），输出"任务待拆分"待执行卡片 |
示例 4：路线图未分层
场景：战略目标存在，路线图存在但节点无 Now/Next/Later 分层，仅为扁平列表。
输出（示例）：
下一步建议
现状：战略目标存在，路线图为扁平节点列表
核心矛盾：无 Now/Next/Later 分层，无法确定当前执行焦点
现在该做
1. 为路线图建立当期/下期/远期分层 · 重要
分层后可锁定当前焦点节点，下游层级才能继续评估。
- 治理上下文：
- 战略目标：存在
- 当前 KPI：数据缺失（路线图无分层前无法评估）
- 路线图：存在，但无 Now/Next/Later 分层
- 当前位置：路线图层，缺优先级分层
- 推荐技能：
/promote-roadmap-items 将 roadmap.md 中的节点按 Now/Next/Later 优先级分层
- 依据：
docs/requirements-planning/roadmap.md 存在但无分层结构
- 完成标志：路线图含 Now/Next/Later 分层后重跑 plan-next
诊断依据
判定逻辑：
| 层级 | 节点 | 状态 | 推断 |
|---|
| 战略目标 | strategic-goals.md | present | 继续下钻 |
| 路线图 | roadmap.md | 未分层（扁平列表） | 路线图未分层规则命中，路由 promote-roadmap-items，不评估下游 |
示例 5：blocked 触发并行
场景：目标 A，路线图节点 N1。N1 下需求 R1（blocked，等待外部依赖）和 R2（pending，与 R1 无 depends_on 依赖）。
并行判定：R1 blocked，R2 pending 且独立 → 并行：建议同时启动 R2。
输出（示例）：
下一步建议
现状：目标 A 进行中，N1 下 R1 被外部依赖阻塞
核心矛盾：等待 R1 解锁将浪费窗口期，R2 独立且可安全并行推进
现在该做
1. 启动需求 R2 的方案设计 · 缓
R1 阻塞期间并行推进 R2，避免等待浪费。
- 治理上下文：
- 战略目标：目标 A（进行中）
- 当前 KPI：数据缺失（目标 A 无量化验收标准）
- 路线图：路线图节点 N1（进行中）
- 当前位置：设计层，R1 被阻塞触发并行
- 推荐技能：（无治理技能；R2 设计工作流由 AgentFabric runtime 承接，R1 被阻塞期间并行推进）
- 依据：R1 被外部依赖阻塞；R2 无
depends_on 依赖
- 完成标志：R2 设计文件创建；受阻时（R2 与 R1 存在隐含耦合）回 plan-next 重评
诊断依据
- 项目情况：目标 A，N1 下 R1 blocked，R2 pending
判定逻辑：
| 层级 | 节点 | 状态 | 推断 |
|---|
| 战略目标 | 目标 A | in-progress | 继续下钻 |
| 路线图 | N1 | in-progress | 专注 |
| 需求 | R1 | blocked | 被外部依赖阻塞，触发并行决策 |
| 需求 | R2 | pending | 无 depends_on 依赖，可安全并行启动 |
- 被阻塞节点：R1（等待外部依赖，需人工介入解除）
- 漂移巡检结果：无
- 卫生巡检结果：无
示例 6：战略目标 status=approved 但验收未达成（最易误判）
场景：strategic-goals.md 中目标 G1 frontmatter status: approved，验收标准为「引用可见率 ≥ 80% 连续两个迭代」，无监控数据。M5 阶段（承载 G1 的里程碑）下 17 条任务全部 pending，任务已拆分完整、设计/ADR 完备。
关键判定：
- L1: G1
status=approved 视同 in-progress；验收 KPI「引用可见率」数据缺失 → 首条路由必须建立 KPI 数据源
- L5: 任务全 pending 触发"待执行"分支，第二条路由输出"待执行"卡片标记焦点任务
输出（示例）：
下一步建议
现状：G1 验收未达成，引用可见率无监控；M5 任务全部待启动
核心矛盾：KPI 数据源缺失，验收不可验证；任务治理就绪但等开发执行
现在该做
1. 建立 G1（需求澄清稳定跑通）验收 KPI 数据源 · 紧急
建立引用可见率监控，才能判断 G1 验收是否达线。
- 治理上下文：
- 战略目标：G1 需求澄清依赖知识库稳定跑通
- 当前 KPI：引用可见率（用户文档被召回占比）数据源缺失 / 目标 ≥80% / 项目自定（无外部基准）
- 路线图：M5（混合检索成熟里程碑，进行中）
- 当前位置：战略目标验收，KPI 数据源未建立
- 推荐技能：（无治理技能；citation 引用可见率埋点 + 监控查询路径设计由 AgentFabric runtime 承接，落入 docs/architecture/）
- 依据：
strategic-goals.md 验收字段含 KPI 但无数据源指向
- 完成标志：引用可见率可在监控/查询接口取数；数据源指向写入 strategic-goals.md
2. 启动 T47（BM25 稀疏检索集成） · 待执行
任务治理就绪，等开发者执行；T47 是引用可见率提升的关键依赖。
- 治理上下文：
- 战略目标：G1 需求澄清依赖知识库稳定跑通
- 当前 KPI：引用可见率 数据源缺失 / 目标 ≥80%
- 路线图：M5（混合检索成熟里程碑，进行中）
- 当前位置：任务层，全部待启动（治理就绪，等开发执行）
- 推荐技能：（无治理技能；交开发团队按 m5/tasks.md T47 实施）
- 依据：M4 T31（QueryRouter）已完成；T47 待开始且无前置阻塞
- 完成标志：T47 验收通过（BM25 召回率较纯向量提升 ≥15%、混合检索 P95 ≤1.5s）；完成后回 plan-next 重评
诊断依据
- 项目情况：G1 status=approved（设计完成），验收未达成，KPI 数据源缺失；M5 进行中，任务全 pending
判定逻辑：
| 层级 | 节点 | 状态 | 推断 |
|---|
| 战略目标 | G1 | approved（视同 in-progress） | status=approved ≠ done；KPI 数据源缺失 → 首条路由建立数据源 |
| 路线图 | M5 | in-progress | 唯一焦点里程碑，继续下钻 |
| 需求 | M5 需求集 | in-progress | 设计/ADR 已就绪，下钻到任务层 |
| 设计 | ADR-033/034 | done | 无任务缺口 |
| 任务 | T47（共 17 项，all-pending） | all-pending | "待执行"分支，输出焦点任务卡片（标签：待执行） |
