plan-next

Skill: Plan Next

Role: Governance entry advisor WHAT: Follow the three-step method Scan(inventory governance assets) → Diagnose(goal tree traversal — depth-first per goal to find the first incomplete node, combined with parallel determination) → Recommend(give next-step action recommendations) HOW: Read-only diagnosis; for single-dimension problems (only checking known gaps) directly recommend a dedicated skill (define-* , etc.) Difference: This skill only gives recommendations and does not execute downstream; document health checks are performed by runtime / linter / CI tools according to rules/doc-health-criteria.md execution

---

Purpose and Boundaries

Inventory governance input sources and give next-step action recommendations.

When to Use: At any stage of the project;recommended after each task completion, to confirm the next focus.

Boundaries

Dimension	Do	Don't Do
Recommend	Give next-step action recommendations (prose or structured card)	Do not act as a task status API; do not maintain a task list / do not assign; do not record task history, and do not answer temporal questions such as "how many were promoted this week"
Execute	Read-only — recommendations are handed to the user or outer orchestrator for decision	Do not automatically advance downstream; do not act as an automation engine — automation is driven by the outer orchestrator + loop combination

---

Behavior

Overall Rules：Stateless— rescan from scratch each time, without relying on previous results. Three-step method:Scan → Diagnose → Recommend。

Step 0: Specification Parsing

cache used for path_pattern parsing in step 2.1.

Step 1: Scan — Asset Inventory

What to scan: 3 abstraction layers × 5 themes (jointly MECE).

Abstraction Layer	Theme	Scan Location	Refinement Field
Intent Layer	Why	docs/project-overview/{mission,vision,north-star,strategic-goals,strategic-pillars}.md	—
Intent Layer	What/When	docs/process-management/{roadmap,backlog/}.md、docs/requirements/、docs/tasks/	Roadmap → node status; tasks/ → status
Intent Layer	How	docs/adr/、docs/designs/	status
Implementation Layer	Is	Repository code	—
Meta-rule Layer	Rules	docs/ARTIFACT_NORMS.md、specs/、protocols/、rules/	—

Abstraction layers are mutually exclusive; refinement fields are auxiliary dimensions of the same theme,not independent scans, and are consumed by §2.1.

How to scan— record 2 fields for each asset:

Field	Criterion
Path	File system path
Status	present(exists and content is non-empty and non-placeholder) / placeholder(contains only [TODO]/<待填>/TBD）/ missing(does not exist)

Step 2: Diagnose — Goal Tree Traversal

Core question: Where is the goal chain stuck? Should the next step focus or parallelize?

Model: Governance artifacts form a tree; "next step" = under the highest-priority goal, depth-first find the first incomplete node, and give execution recommendations combined with parallel determination.

战略目标
└── 路线图节点（多个，有顺序）
    └── 需求（多个，每路线图节点下）
        └── 设计/ADR（多个，每需求下）
            └── 任务（多个，每设计下）

4 substeps(executed in order):

Sub-step	What to do	Output
2.0 Precondition Gate	Is the Rules layer in place?	Otherwise short-circuit
2.1 Goal Tree Traversal	Depth-first traversal goal by goal, locating the first gap + parallel determination	Current position of each goal + routing recommendation
2.2 Drift Inspection	Artifact updated_at vs alignment goal change time; route to dedicated skill when threshold exceeded	List of drift entries
2.3 Hygiene Inspection	Archiving of completed milestones, ADR status, repository structure, skill-layer changes, etc.	List of hygiene issue entries

G1-G4 gap types are used as sub-tags of the diagnostic basis section.

2.0 Precondition Gate: Rules Layer Absence Check

If ARTIFACT_NORMS.md is missing or specs/ is empty, triggershort-circuit: skip goal tree traversal; "what to do now" lists only one P0 route (establish the spec + rerun plan-next).

2.1 Goal Tree Traversal

Node State Determination

The state of each artifact node (roadmap node / requirement / design / task) is resolved according to the following rules:

1. Explicit takes priority: read the status: field in the artifact file frontmatter
   • Valid values:pending(default) | in-progress | done | blocked
2. Child node inference(when there is no explicit status: ):
   • All direct child nodes done → the current node is considered done
   • Any direct child node in-progress → the current node is considered in-progress
   • No child nodes → considered pending
3. Priority: explicit field > child node inference

Parallel Decision Rules

At any level, after scanning all sibling nodes at that level, determine according to the following rules:

State of sibling nodes at the current level	Parallel recommendation
Only 1 in-progress, the rest pending	Focus: finish the current one before starting the next
1+ blocked, with pending and independent	Parallel: blocked ones keep waiting, start the next independent node
Multiple in-progress(none blocked)	Converge: identify the most lagging one and prioritize advancing it to completion
All done	Trigger advancement to the next sibling at the upper level
All pending, no in-progress	Start: route the highest-priority pending node

If there is an explicit depends_on: dependency between nodes → the depended-upon node must be completed first and cannot be parallelized.

Level Definitions

Level	Name	Existence criterion	Completion criterion
L1	Strategic goal	strategic-goals.md present and not a placeholder, containing ≥1 identifiable goal item	Simultaneouslysatisfy: (a) goal status = done; (b) All observable KPIs in the target "acceptance criteria" have been achieved (data is verifiable and meets the threshold).status = approved is treated as in-progress, and drilling down must continue
L2	Roadmap node	Roadmap node exists and is traceable to an L1 objective	Node status = done(explicit or inferred)
L3	Requirements	Requirements file present and not a placeholder	status = done(explicit or inferred)
L4	Design	Design/ADR file present and not a placeholder	status = done(explicit or inferred)
L5	Tasks	Task record present	status = done

Mandatory L1 acceptance KPI check (critical)

Cannot be skipped: Each time an L1 objective is traversed, the "acceptance criteria" field must first be parsed to extract the observable KPIs (including name + target threshold + data source). Then determine the current KPI status:

KPI status	Meaning	L1 completion determination
Achieved (data ≥ threshold, continuous condition satisfied)	Acceptance passed	L1 done (provided status=done)
Not achieved (data < threshold or continuous condition not satisfied)	Acceptance not passed	L1 in-progress, continue drilling down
Data missing(no monitoring/no query path)	Acceptance not verifiable	L1 in-progress, and the first route must first establish the KPI data source(before any downstream route)

Key anti-pattern：status = approved ≠ L1 completion.approved indicates the decision has been approved, which only means the document has taken shape;done indicates acceptance has been achieved. Confusing the two will skip downstream traversal of the entire L1 subtree, causing scanning to start directly from the middle layers (M5/tasks) and losing the causal chain of "why this task matters".

No-objective scenario：strategic-goals.md is missing and mission.md is also missing → route define-mission（P0）；mission.md present but no strategic objective → route design-strategic-goals（P0）。

Roadmap not layered: The roadmap exists but has no Now/Next/Later layering → route promote-roadmap-items(P1), and do not continue evaluating downstream.

Traversal algorithm

对 每个战略目标 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）

Physical scanning method (L3-L5 existence detection)

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

The diagnostic basis must note the combination of physical signals the scan depends on (e.g., "slug + 2 manifests detected + no parent field").

Diagnostic step outputs

Step 3 consumes the following outputs:

• Per-objective traversal result: {objective name, current focus node, layer, parallelization suggestion, gap sub-label (G1/G2/G3), recommended skill}
• blocked node list: [(layer, node name, blocked reason (if any))]
• Secondary findings: other findings outside the focused objective
• Drift item list(output of step 2.2): [(artifact path, drift type, recommended skill)]
• Hygiene issue list(output of step 2.3): [(issue description, recommended skill)]

Step 2.2: Drift inspection

Compare the artifact's updated_at with the corresponding layer's change event time; if the threshold is exceeded, route to the dedicated skill.

Threshold (internal constant, not exposed to users)：

Parameter	Default value	Meaning
drift_staleness_days	30	Artifacts not updated for more than this many days are considered drifted
backlog_rescore_days	90	Backlog last rescored more than this many days ago is considered stale
doc_health_staleness_days	30	Document health reports older than this many days are considered expired (runtime / CI output)

Routing table：

Drift signal	Recommended skill
backlog last_rescored_at exceeds backlog_rescore_days	/prioritize-backlog
Architecture docs vs code drift (gap between ADR updated_at and most recent code commit exceeds threshold)	/review-architecture
Health signals such as documentation SSOT / code alignment / link rot	runtime / linter / CI tools detect according to rules/doc-health-criteria.md detection

Constraint: Drift items are forced into the "Also worth noting" section and do not occupy the top two spots of "What to do now" (unless the main route is idle and the drift priority reaches P1).

Step 2.3: Hygiene inspection

Check for chronically accumulated governance debt and output a list of hygiene issues.

Threshold (internal constant)：

Parameter	Default value	Meaning
milestone_archive_age_days	60	Milestones completed more than this many days ago are mature enough to archive
milestone_archive_lookback	2	A difference of ≥ N between the current in-progress milestone index and the slug is considered archivable

Check item：

Check	Judgment condition	Recommended skill
Completed milestones not archived	milestones/{slug}/tasks.md all done, and any maturity condition is met	/archive-milestone {slug}
ADR status closure violation	superseded / conflicting / no accepted conclusion	/review-architecture
Repository structure drift	_templates/ omissions / file naming violations	runtime / CI detect according to rules/repo-structure-hygiene.md detection
Document health detection backlog	Health report > doc_health_staleness_days days without update	runtime / CI runs a rules/doc-health-criteria.md full detection

Constraint: Hygiene items are forced into the "Also worth noting" section and do not occupy the top two spots of "What to do now".

Step 3: Recommend — route generation and layering

Source: Consume the output of Step 2 (see "Diagnosis step outputs").

3.1 Layering decision

Consume the per-goal traversal results produced in §2.1, and route all of them to "What to do now" (1-3 items):

• Main-chain route(the first gap of the highest-priority goal) must go into "What to do now"
• Parallel route(independent nodes triggered by blocked) if immediately executable, also go into "What to do now"
• When more than 3 items, truncate by priority; secondary gaps of other goals are not displayed

Parallel route: When the parallel decision recommendation is "parallel" or "converge", clearly state the parallel rationale or convergence goal in the routing basis; when "focus", route only the current node.

Sibling advancement rule: When a node is completed, automatically advance to the next sibling node at the same level without requiring the user to rerun; traversal stops at the first gap of the next sibling.

Multi-task multi-card rendering rule：

When L5 all pending triggers the "to be executed" branch and there are ≥2 independently startable tasks,Render multiple parallel cardsrather than merging into a single card. Each card focuses on 1 task. Maximum 3 cards; excess is truncated by §3.2 priority.

• ✅ Correct: 3 parallel cards, each with one task (action name, TL;DR, and completion marker are each independent)
• ❌ Prohibited: a single card topic uses enumeration commas / plus signs / verbs such as "parallel launch" to merge multiple tasks (e.g., T51 + T-SG5-002 并行启动）
• ❌ Prohibited: a single card's completion marker stacks KPIs from multiple tasks (e.g., T51 仪表盘可访问 + T52 日志可查 + T-SG5-002 后台可用）

For tasks with time differences such as ready tomorrow, ready later this week, use the 缓 tag + TL;DR to note the ready time; do not stuff it into the footnote of the current card.

3.2 Priority (governance urgency)

• Now (P0): foundational issues that block other governance progress (missing Rules layer or L1 has no objective)
• Next (P1): L2 roadmap missing or not aligned with objectives
• Later (P2): gaps at any level from L3-L5
• Ignorable (P3): other minor findings

3.3 Output format selection

The output format adapts to the scenario:

Scenario	Recommended format
Single recommendation, situation is clear	Prose: 1-3 sentences clearly stating what to do, why, and the completion marker
≥2 parallel recommendations, or a need for parallel / convergence judgment	Structured card(see format below)

Prose format (simple scenarios): express directly in natural language, including: what to do → why now → how completion is measured. No fields, tags, or card header needed.

Structured card format (complex scenarios, when there are ≥2 parallel recommendations)：

**N. [行动名称]** · `优先级标签`

> [TL;DR 卡片头：一句话答"做什么 → 立刻可见的收益"，≤30 字]

- 治理上下文：[多行短链，每行 ≤25 字，详见下方"治理上下文写法"]
- 推荐技能：`/skill-name [聚焦点 ≤40 字]`
- 依据：[文件路径或可观测信号 ≤20 字]
- 完成标志：[可观测结果 1 句话]
- [选填] 暂缓代价：[不做的影响 ≤30 字]
- [选填] 上手门槛：[前置知识 / 文档路径 ≤30 字]

Common constraints (applicable to both prose and cards): regardless of which format is used, each recommendation must include: what to do, why, and an observable completion marker. The first appearance of a project code name must be accompanied by a natural-language subtitle (see §3.3.1 + §3.7 for details).

How to write the TL;DR card header：

Blockquote (> ...) form, placed below the priority tag and above the field list. Answer "what to do → immediately visible benefit", ≤30 characters. It has the highest visual anchor, letting readers know the core action on the first screen.

• ✅ Good example:> 让 PM 实时看到覆盖率进度，填补 Goal 1 验收的可视化缺口。
• ❌ Bad example:> 启动并行任务以推进里程碑（与下方主题字段重复，无新信息）。

How to write governance context：

Show the traceability chain from strategic objective to current gap,and it must include the current status of the L1 acceptance KPI. Change to a multi-line short-chain format (each line ≤25 characters):

- 治理上下文：
  - 战略目标：[目标自然语言名 + 一句话核心 KPI]
  - 当前 KPI：[当前值 / 目标值 / 参考系；无数据写"数据缺失"]
  - 路线图：[里程碑自然语言名 + 当前阶段]
  - 当前位置：[卡口所在层 + 卡因，≤15 字]

Hard upper limit of ≤25 characters per line. Split overly long content onto the next line; nested parentheses must not exceed 1 level.

Mandatory constraint: each route must explicitly answer "how does this action return to the acceptance of the strategic objective?" If it cannot, it should be changed to a task to establish the route KPI data source, and must not directly route downstream execution.

Three expressions of KPI status(following the three-piece set, see §3.3 threshold annotation for details):

• Achieved:引用可见率 85% / 目标 ≥80% / 行业 75-85%（达成）
• Not achieved:引用可见率 62% / 目标 ≥80% / 行业 75-85%（未达） or 引用可见率 数据未测 / 目标 ≥80%（待测）
• Data missing:引用可见率 数据源缺失 / 目标 ≥80% / 参考系无（数据源待建）

Three-piece set for threshold annotation：

The first appearance of any KPI / threshold must use the three-piece set:

Format:[指标名（口语化解释）]：当前 X / 目标 Y / 参考系 Z

Example:采纳率（用户主动接受推荐占比）：当前 42% / 目标 ≥70% / 行业 50-65% 算良好

Reference frameReference: industry benchmark / project historical value / empirical threshold. When no reference exists, write "project-defined (no external benchmark)" to alert the reader. The reference frame may be omitted when the same metric appears a second time on the same card.

Recommended skill notation: slash command + completion prompt, format:

/skill-name [聚焦点：本次要做什么、范围、关键资产路径或任务 ID]

Prompt requirements: state the specific focus of this invocation, include key asset paths or task IDs, ≤40 characters, directly copyable for execution. For the L5 all-pending "to be executed" branch when no governance skill is available, write "(no governance skill; hand over to the development team for implementation per [路径] )".

Priority label(mapped from §3.2 internal priority; the "what to do now" section uses only labels, not codes):

Internal code	User label
P0	紧急
P1	重要
P2	缓
P3	可略
—	待执行(special: governance ready, awaiting execution; only used for the L5 all-pending branch)

Completion marker: an observable result, 1 sentence; if execution is blocked (strategic conflict, dependency cycle), append "when blocked, return to plan-next for reassessment". For multiple tasks,each card manages its own completion marker, do not stack them in the outer layer.

Cost of deferral (optional)：

Answer "what happens if this is not done", so the reader can judge "do this first vs do something else first". ≤30 characters.

• ✅ Good example:Goal 1 验收无可视化途径，PM 无法判断应交项收尾时机
• ❌ Placeholder filler (forbidden):待补充 / 详见任务 / 影响进度(same as anti-pattern · vague wording)

When information is insufficient,omit this field, fabrication is not allowed.

Onboarding threshold (optional)：

Answer "who should do this next, and is any preparation needed first". ≤30 characters. When pointing to a specific document, include its path.

• ✅ Good example:需了解 Grafana 数据源配置；不熟可参考 docs/runbooks/grafana-setup.md
• ❌ Placeholder filler (forbidden):需相关知识 / 参考文档

When information is insufficient,omit this field, fabrication is not allowed.

3.3.1 Forbidden words in the "what to do now" section output

In the "what to do now" section, the following wordsare strictly forbidden— including the codes themselves and their Chinese equivalents:

Forbidden	Allowed alternative
L1, L2, L3, L4, L5; goal layer, roadmap layer, requirements layer, design layer, task layer	Directly say "strategic goal", "roadmap", "requirements document", "design document", "task"
G1, asset missing	Describe exactly what is missing: "xxx.md does not exist"
G2, incomplete content	Describe exactly what content is missing: "missing X field / X section"
G3, truth drift, completion drift, tracking drift	Describe the specific inconsistency: "task status does not reflect code progress"
G4, misplacement	Describe the specific problem: "file naming does not conform to the standard"
P0, P1, P2, P3; now/next/later/ignorable (as priority labels)	Use 紧急 / 重要 / 缓 / 可略
pending, in-progress, done, blocked (for user output verbatim)	Say "not started", "in progress", "completed", "blocked"
Rules layer, Why layer, What layer, How layer, Is layer	Say "standards document", "strategic document", "plan document", "design document", "code implementation"
Project code name exposed bare：T\d+ / M\d+ / Goal \d+ / BL-\d+ / ADR-\d+ / commit hash and other internal IDs	In the header summary, the "What to do now" and "Also watch out for" sections, the first occurrence must be accompanied by a natural-language subtitle:T51（覆盖率仪表盘） / M5（混合检索成熟里程碑）; subsequent occurrences within the same card may use the bare code name; if the dictionary is missing, see §3.7 fallback
MoSCoW framework terms：Must Have / Should Have / Could Have / Won't Have	Replace with "Must-have / Should-have / Could-have / Won't do for now"
Governance process jargon: pre-gate / short-circuit / soft-blocked / sibling scan / focus node / all-pending branch / child node inference	Use plain descriptions: "Spec file missing, establish it first" / "waiting for developer execution" / "scan results of other nodes at the same level"
Bare threshold with no reference frame：≥70% / P95 ≤30s / 14 天连续窗口(only a number with no reference frame)	Replace with the three-piece set:[指标名（口语化解释）]：当前 X / 目标 Y / 参考系 Z(see §3.3 Threshold annotation for details)

Violating this table = the "What to do now" section output is unqualified; the violating fields must be rewritten and must not be kept.

3.4 User output structure

Format selection: a single recommendation may use prose instead of the card below. The following structured template applies to scenarios with ≥2 parallel recommendations.

# 下一步建议

> **现状**：[客观状态摘要，≤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 Terminology dictionary lookup

Purpose: automatically inject a natural-language subtitle for project code names, so the user output can be interpreted independently and readers do not have to consult an internal ID dictionary to understand it.Purpose: automatically inject a natural-language subtitle for project code names, so the user output can be interpreted independently and readers do not have to consult an internal ID dictionary to understand it.

Dictionary sources (in order of discovery)：

1. Input parameter glossary_path(if provided by the caller)
2. .ai-cortex/glossary.yaml
3. docs/glossary.md
4. Fallback: read the source artifact frontmatter title: field (e.g. docs/tasks/T51.md of title:); if there is no frontmatter, take the first H1 heading

Dictionary schema(in YAML form):

T51:
  full_name: 覆盖率仪表盘任务
  one_liner: 让 PM 实时看到覆盖率进度
M5:
  full_name: 第 5 个里程碑「混合检索成熟」
Goal 1:
  full_name: 需求澄清依赖知识库稳定跑通
  kpi: 采纳率 ≥70% 连续 14 天

Field descriptions：

• full_name(required): natural-language name, used to inject the subtitle
• one_liner(optional): one-sentence core value, can be used to assist generation of the TL;DR card header
• kpi(optional, strategic goals only): brief description of core KPIs

Output-layer lookup rules：

Scenario	Rendering strategy
Project code name appears for the first time, dictionary hit	Inject 代号（full_name）, e.g.:T51（覆盖率仪表盘任务）
Subsequent occurrences within the same card	Use only the bare code name
Dictionary missing the corresponding entry	Fallback: read the source artifact frontmatter title:, take the first ≤12 characters and inject
Both dictionary and Fallback missing	In the diagnostic basis section, mark "Dictionary missing: recommend adding docs/glossary.md to <代号>"，Do not show this code name in the user output section; use a generic description instead (e.g. "task to be executed")

Constraints：

• A missing dictionary does not error or block—degraded output is still usable
• Dictionary lookup injects only into the "What to do now" and "Also watch out for" sections; the diagnostic basis section may use bare code names
• Malformed dictionary source YAML → HALT and prompt the user to fix it (same as §0 spec parsing behavior)

---

Anti-patterns

On responsibility boundaries：

• ❌ Call any downstream skill (read-only hard boundary)
• ❌ Hide the skip reason (must be explicit when short-circuiting)
• ❌ Mixing in downstream execution details (do not write ADRs, do not fix code, do not restructure)

About routing itself：

• ❌ Vague wording ("may / perhaps / could consider")
• ❌ Omitting the completion marker
• ❌ One route mixing multiple gap types
• ❌ Assigning priority by number of gaps
• ❌ Tree traversal skipping levels in reporting (reporting L3 routes directly when L2 is missing)—violates "first gap first"
• ❌ Using git signals to judge "done"—L2-L5 completion determination looks at the status field;L1 completion must additionally include an acceptance KPI check
• ❌ Ignoring the explicit status: field and inferring only from child nodes—explicit takes precedence
• ❌ Using status = approved as the criterion for L1 done—approved = decision has been approved ≠ acceptance has been achieved; confusing them will skip the entire L1 subtree
• ❌ Bypassing L1 to directly report intermediate-layer (M5/task) status—must first answer "has the L1 acceptance KPI been achieved," then drill down
• ❌ Governance context field missing the current value of the L1 acceptance KPI—violates the "routing must return to strategic objective acceptance" constraint
• ❌ When the L1 acceptance KPI data source is missing, directly routing downstream execution tasks—the first route should first establish the KPI data source
• ❌ Forcing downstream skills when all L5 are pending—when tasks already exist, no governance skill is available, and a "to be executed" card should be output
• ❌ Not considering parallel startup when there are blocked nodes—blocked is a parallel signal
• ❌ Recommending continued parallel expansion when multiple in-progress nodes are not blocked—convergence should be suggested
• ❌ Merging routes for multiple objectives without noting the source of each objective in the rationale
• ❌ Skipping when the roadmap is not layered promote-roadmap-items and directly evaluating downstream
• ❌ Ignoring the depends_on: field and forcibly suggesting parallelism—dependencies require sequential order

About tree traversal and scanning：

• ❌ Reporting gaps for done nodes in the main route "what to do now" (the hygiene inspection's check of done nodes is an exception; output it under "also pay attention to")
• ❌ Reporting multiple layers of gaps for the same node at the same time (violates depth-first)
• ❌ Introducing a mode enum or configuration field (look directly at physical signals)
• ❌ Taking on checklist maintenance responsibility (plan-next is read-only; differences are output as G3 diagnostic entries, not fixed)

About internal terminology leakage：

• ❌ Codes appearing in the "what to do now" section: any form of L1-L5, G1-G4, P0-P3
• ❌ Chinese equivalents of codes appearing in the "what to do now" section: asset missing, incomplete content, truth drift, completion drift, tracking drift, position misalignment, objective layer, roadmap layer, requirements layer, design layer, task layer, Rules layer, Why layer, What layer, How layer, Is layer
• ❌ Priority using the old labels "now/next/later/ignorable" or P0-P3 numbering (switch to 紧急/重要/缓/可略）
• ❌ status values appearing verbatim in the "what to do now" section: pending/in-progress/done/blocked (switch to: 待开始/进行中/已完成/被阻塞)
• ❌ Diagnostic rationale using layer numbers as the subject (parenthetical traceability is allowed, but not as the subject)
• ❌ Example title written as "L2→L3 advancement" (use natural-language scenario descriptions)

About jargon and judgment scaffolding：

• ❌ Project code names appearing bare (T51 / M5 / Goal 1 / BL-001 / ADR-033 etc.) with no natural-language subtitle on first occurrence
• ❌ MoSCoW framework terms appear in the user output section (Must Have / Should Have / Could Have / Won't Have)
• ❌ Governance process jargon appears in the user output section (pre-gate, short-circuit, soft-blocked, sibling scan, focus node, all-pending branch, child node inference)
• ❌ Threshold has no reference frame (bare ≥70% / P95 ≤30s / 14 天连续窗口) — the trio is required: current value / target value / reference frame
• ❌ Multiple tasks merged into a single-card topic using enumeration commas / plus signs / "parallel start" (T51 + T-SG5-002 / T51、T52 并行) — multiple tasks render multiple cards
• ❌ A single card's completion marker stacks KPIs from multiple tasks (A 可访问 + B 可查 + C 可用) — each card manages its own completion marker
• ❌ Governance context nested parentheses exceed 1 level (目标X（验收: KPI A 当前 80%（达成）/ 目标 ≥70%（高线））) — split into multiple lines of short chains
• ❌ Governance context written as a single chain exceeding 60 characters — must be changed to multiple lines of short chains with each line ≤25 characters
• ❌ Deferral cost / onboarding threshold fields filled with placeholder text ("to be added" / "see task" / "affects progress" / "requires relevant knowledge") — insufficient information should be omitted
• ❌ TL;DR card header semantically duplicates the topic field ("start parallel tasks to advance the milestone" restates the topic) — must answer "immediately visible benefit"
• ❌ Dictionary-missing code names forced into the user output section (should be marked in the diagnostic basis section; use generic descriptions in the user section)

---

Self-check

Scan：

• Cache loaded or explicitly "no norms found"
• Asset 2 fields complete (path + status)
• Whether the roadmap is layered has been determined; when not layered, routed promote-roadmap-items

Diagnose：

• Strategic goals have been read; when there are no goals, L1 routing has been triggered
• L1 acceptance criteria KPIs have been parsed; each goal's KPI current status has been determined (achieved / not achieved / data missing)
• L1 status=approved is treated as in-progress, drill-down not skipped
• When the KPI data source is missing, the first route is to establish the data source, not directly route downstream
• Each node's status has been resolved according to "explicit priority > child node inference"
• Each level's sibling nodes have been fully scanned and classified (done / in-progress / blocked / pending)
• Parallel decision rules have been applied; recommendations (focus / parallel / converge / start) have been marked
• L3-L5 physical scan completed (glob + optional parent: + optional manifest)
• L3→L4 / L4→L5 G3 chain checks have been executed; depth-first (when an upper-layer G3 hits, lower layers are not reported further)
• The "complete" determination relies only on the status field and does not introduce git signals
• Drift inspection (step 2.2) has been executed; artifacts exceeding the threshold have been included in the drift item list
• Hygiene inspection (step 2.3) has been executed; completed but unarchived milestones, ADR status issues, and repository structure issues have all been scanned

Recommend：

• Each recommendation includes: what to do, why, and an observable completion marker (whether prose or card)
• Format selection is correct: a single recommendation uses prose; ≥2 parallel recommendations use structured cards
• KPI / threshold includes the trio on first occurrence(current value / target value / reference frame); when there is no reference, "project-defined (no external benchmark)" has been marked
• Depth-first (report only the first gap in the tree for each goal)
• Parallel suggestions have stated the parallelization rationale in the text
• Drift/hygiene items are all in the "Also Watch Out For" section and do not crowd out the first two positions of "What To Do Now"
• (when using structured cards) TL;DR quote block ≤30 characters and does not repeat the theme
• (when using structured cards) Governance context is multiple lines of short links (≤25 characters per line), including the current status of L1 acceptance KPIs
• (when using structured cards) Priority labels are mapped correctly (Urgent / Important / Later / Can Skip / To Do)
• (when using structured cards) L5 all-pending multi-task (≥2 independently startable) is rendered as multiple parallel cards, not merged
• (when using structured cards) Fields such as cost of deferral / onboarding threshold are omitted when information is insufficient and are not filled with placeholder text

Output：

• Header summary (current state/core conflict) ≤ character limit: current state ≤25 characters, core conflict ≤30 characters; no project code exposed bare (consistent with the rules for the "What To Do Now" section)
• The "What To Do Now" section has no codes: L1-L5, G1-G4, P0-P3
• The "What To Do Now" section has no coded Chinese equivalents: asset missing, content incomplete, truth drift, completion drift, tracking drift, position misalignment
• The "What To Do Now" section has no old priority labels: Now/Next/Later/Ignore; priorities are unified as 紧急/重要/缓/可略
• The "What To Do Now" section has no English status codes: pending, in-progress, done, blocked
• The "What To Do Now" and "Also Watch Out For" sections have no project code exposed bare（T\d+ / M\d+ / Goal \d+ / BL-\d+ / ADR-\d+) — each first occurrence is accompanied by a natural-language subtitle
• The "What To Do Now" section has no MoSCoW words（Must Have / Should Have / Could Have / Won't Have）
• The "What To Do Now" section has no governance process jargon(pre-gate / short-circuit / soft-blocked / sibling scan / focus node / all-pending branch / child node inference)
• Missing dictionary codes have been moved into the diagnostic basis sectionmarked, and not forcibly inserted in the user output section
• The diagnostic basis section uses a table for decision logic(4 columns: level / node / status / inference), not prose
• Read-only has been observed
• The diagnostic basis indicates the traversal position of each goal and blocked nodes

---

Example

Example 1: Strategic half-finished (normal path)

Scenario: the project has mission / vision; no strategic-goals; roadmap exists but cannot be traced back to strategic goals.

Output(example):

Next-step suggestions

Current state: has mission and vision, strategic goal document is missing Core conflict: roadmap nodes exist but there are no goals to trace them to, and governance traversal cannot begin

---

What To Do Now

1. Add the strategic goal document · 重要

Complete the missing strategic goal file so that roadmap nodes have a traceable source.

• Governance context:
  • Strategic goals: missing (mission and vision already exist)
  • Current KPI: data missing (strategic goals have not been established, no acceptance criteria)
  • Roadmap: exists, but nodes have no goals to trace to
  • Current position: strategic goals missing, traversal stopped
• Recommended skills:/design-strategic-goals 基于 mission.md 和 vision.md 生成 strategic-goals.md，包含可识别的目标项
• Basis:docs/project-overview/strategic-goals.md missing
• Completion criteria: strategic-goals.md is written and contains identifiable goal items; if blocked, return to plan-next for re-evaluation

Diagnostic basis

• Project situation: has mission and vision but no strategic goals; roadmap alignment is yet to be established

Decision logic：

Level	Node	Status	Inference
Strategic goals	strategic-goals.md	missing	L1 gap, traversal stops; route to design-strategic-goals
Roadmap	—	Not evaluated	Rerun after L1 is ready

• Drift inspection results: none
• Hygiene inspection results: none

Example 2: New project kickoff (short-circuit scenario)

Scenario: new project,docs/ARTIFACT_NORMS.md does not exist,specs/ is empty.

Output(example):

Next-step recommendations

Current state: new project, documentation standards file missing Core contradiction: no unified standards; all subsequent governance documents have no standard to follow, and goal tree traversal is skipped

---

What to do now

1. Establish the documentation standards foundation · 紧急

First establish documentation standards so that all subsequent governance files have a standard to follow.

• Governance context:
  • Strategic goals: not yet reachable (early stop due to missing standards file)
  • Current KPIs: data missing (governance standards not established)
  • Roadmap: not yet evaluated (rerun after standards file is ready)
  • Current position: standards file missing, goal tree traversal skipped
• Recommended skill:/define-docs-norms 基于项目结构生成 docs/ARTIFACT_NORMS.md
• Basis:docs/ARTIFACT_NORMS.md missing,specs/ is empty
• Completion criteria: rerun plan-next after ARTIFACT_NORMS.md is written to disk

Diagnostic basis

• Project situation: standards layer absent, goal tree traversal skipped

Decision logic：

Level	Node	Status	Inference
Standards layer	ARTIFACT_NORMS.md	missing	Missing standards trigger early stop, goal tree traversal skipped
Strategic goals	—	Not evaluated	Rerun plan-next after standards are ready

• Drift inspection results: none
• Hygiene inspection results: none

Example 3: Sibling node advancement + parallel decision

Scenario: goal A, roadmap node N1 (in-progress). Under N1 are requirement R1 (in-progress, inferred from children) and requirement R2 (pending). Under R1 are design D1a (done) and D1b (in-progress). Tasks under D1b have not yet been broken down.

Traversal path: N1 → R1 (in-progress, inferred from children) → sibling scan: D1a done, D1b in-progress → enter D1b → no tasks (L5 gap) → output "tasks pending breakdown" pending-execution card (task breakdown is handled by AgentFabric runtime).

Parallel decision: D1b is the only in-progress design, R2 pending. Recommendation:Focus D1b; once complete, R2 automatically becomes the next focus.

Output(Example):

Next-step recommendation

Current state: Goal A is in progress, design D1b is ready and awaiting task breakdown Core conflict: D1a is complete, D1b has no tasks, and the execution layer cannot proceed

---

What to do now

1. Break down executable tasks for design D1b · 缓

Design D1b is ready; after tasks are broken out, D1b can enter execution.

• Governance context:
  • Strategic goal: Goal A (in progress)
  • Current KPI: data missing (Goal A has no quantitative acceptance criteria)
  • Roadmap: roadmap node N1 (in progress)
  • Current position: design D1b is ready, task-layer gap
• Recommended skill: (no governance skill; task breakdown is handled by the AgentFabric runtime, executed at the same granularity as design D1b and D1a)
• Basis: the D1b design file exists, the task file is missing; D1a completion triggered advancement
• Completion marker: the D1b task list is created and has at least one task record

Diagnostic basis

• Project situation: Goal A is in the execution stage, N1→R1→D1b, task-layer gap

Decision logic：

Level	Node	Status	Inference
Strategic goal	Goal A	in-progress	Continue drilling down
Roadmap	N1	in-progress	Focus (the only in-progress node)
Requirement	R1	in-progress (sub-inference: D1b in-progress)	Continue drilling down
Design	D1a	done	D1a done triggers sibling advancement
Design	D1b	in-progress	No tasks (G1), output a "tasks pending breakdown" pending-execution card

• Drift inspection result: none
• Hygiene inspection result: none

Example 4: roadmap is not layered

Scenario: A strategic goal exists, and a roadmap exists, but its nodes have no Now/Next/Later layering and it is only a flat list.

Output(Example):

Next-step recommendation

Current state: A strategic goal exists, and the roadmap is a flat node list Core conflict: There is no Now/Next/Later layering, so the current execution focus cannot be determined

---

What to do now

1. Establish current/next/later layering for the roadmap · 重要

After layering, the current focus node can be locked, and downstream levels can continue to be evaluated.

• Governance context:
  • Strategic goal: exists
  • Current KPI: data missing (cannot be evaluated before the roadmap is layered)
  • Roadmap: exists, but has no Now/Next/Later layering
  • Current position: roadmap layer, missing priority layering
• Recommended skill:/promote-roadmap-items 将 roadmap.md 中的节点按 Now/Next/Later 优先级分层
• Basis:docs/requirements-planning/roadmap.md exists but has no layered structure
• Completion marker: rerun plan-next after the roadmap includes Now/Next/Later layering

Diagnostic basis

• Project situation：Roadmap exists but is not layered; traversal stops at L2

Decision logic：

Layer	Node	Status	Inference
Strategic goal	strategic-goals.md	present	Continue drilling down
Roadmap	roadmap.md	Not layered (flat list)	Roadmap-not-layered rule hit; route promote-roadmap-items; do not evaluate downstream

• Drift inspection result：None
• Hygiene inspection result：None

Example 5: blocked triggers parallel

Scenario：Goal A, roadmap node N1. Under N1, requirement R1 (blocked, waiting on external dependency) and R2 (pending, with no depends_on dependency on R1).

Parallel decision：R1 blocked, R2 pending and independent → Parallel：Recommend starting R2 at the same time.

Output(example):

Next-step recommendation

Current state：Goal A is in progress; under N1, R1 is blocked by an external dependency Core contradiction：Waiting for R1 to unblock will waste the window; R2 is independent and can safely proceed in parallel

---

What to do now

1. Start the solution design for requirement R2 · 缓

Advance R2 in parallel while R1 is blocked, avoiding wasted waiting.

• Governance context:
  • Strategic goal: Goal A (in progress)
  • Current KPI: data missing (Goal A has no quantitative acceptance criteria)
  • Roadmap: roadmap node N1 (in progress)
  • Current position: design layer; R1 being blocked triggers parallel
• Recommended skills: (no governance skills; the R2 design workflow is handled by the AgentFabric runtime, advancing in parallel while R1 is blocked)
• Basis: R1 is blocked by an external dependency; R2 has no depends_on dependency
• Completion marker: R2 design file created; if blocked (R2 has an implicit coupling with R1), return to plan-next for re-evaluation

Diagnostic basis

• Project situation：Goal A; under N1, R1 blocked, R2 pending

Decision logic：

Layer	Node	Status	Inference
Strategic goal	Goal A	in-progress	Continue drilling down
Roadmap	N1	in-progress	Focus
Requirement	R1	blocked	Blocked by an external dependency, triggering a parallel decision
Requirement	R2	pending	No depends_on dependency; can safely start in parallel

• Blocked node：R1 (waiting on external dependency, requires manual intervention to unblock)
• Drift inspection result：None
• Hygiene inspection result：None

---

Example 6: strategic goal status=approved but acceptance not met (most prone to misjudgment)

Scenario：strategic-goals.md In strategic-goals.md, goal G1 frontmatter status: approved, acceptance criterion is "citation visibility rate ≥ 80% for two consecutive iterations", with no monitoring data. Under M5 stage (the milestone carrying G1), all 17 tasks are pending, tasks are fully broken down, and design/ADR are complete.

Key determination：

• L1: G1 status=approved deemed as in-progress; acceptance KPI "citation visibility rate" data missing → the first route must establish the KPI data source
• L5: all tasks pending triggers the "to be executed" branch; the second route outputs a "to be executed" card marking the focus task

Output(example):

Next-step recommendations

Current status: G1 acceptance not achieved, citation visibility rate unmonitored; all M5 tasks pending start Core contradiction: KPI data source missing, acceptance not verifiable; task governance ready but awaiting development execution

---

What to do now

1. Establish the G1 (requirements clarification runs stably) acceptance KPI data source · 紧急

Establish citation visibility rate monitoring to determine whether G1 acceptance meets the threshold.

• Governance context:
  • Strategic goal: G1 requirements clarification depends on the knowledge base running stably
  • Current KPI: citation visibility rate (proportion of user documents recalled) data source missing / target ≥80% / project-defined (no external benchmark)
  • Roadmap: M5 (hybrid retrieval maturity milestone, in progress)
  • Current position: strategic goal acceptance, KPI data source not established
• Recommended skills: (no governance skills; citation visibility rate instrumentation + monitoring query path design handled by AgentFabric runtime, placed in docs/architecture/)
• Basis:strategic-goals.md acceptance field includes KPI but no data source reference
• Completion criteria: citation visibility rate can be retrieved via monitoring/query interface; data source reference written into strategic-goals.md

---

2. Start T47 (BM25 sparse retrieval integration) · 待执行

Task governance ready, awaiting developer execution; T47 is a key dependency for improving citation visibility rate.

• Governance context:
  • Strategic goal: G1 requirements clarification depends on the knowledge base running stably
  • Current KPI: citation visibility rate data source missing / target ≥80%
  • Roadmap: M5 (hybrid retrieval maturity milestone, in progress)
  • Current position: task layer, all pending start (governance ready, awaiting development execution)
• Recommended skills: (no governance skills; hand to development team to implement per m5/tasks.md T47)
• Basis: M4 T31 (QueryRouter) completed; T47 not started and no prerequisite blockers
• Completion criteria: T47 acceptance passed (BM25 recall improved by ≥15% over pure vector, hybrid retrieval P95 ≤1.5s); after completion, return to plan-next for re-evaluation

Diagnostic basis

• Project situation: G1 status=approved (design complete), acceptance not achieved, KPI data source missing; M5 in progress, all tasks pending

Determination logic：

Level	Node	Status	Inference
Strategic goal	G1	approved (deemed in-progress)	status=approved ≠ done; KPI data source missing → first route establishes data source
Roadmap	M5	in-progress	sole focus milestone, continue drilling down
Requirements	M5 requirements set	in-progress	design/ADR ready, drill down to task layer
Design	ADR-033/034	done	no task gaps
Task	T47 (17 items in total, all-pending)	all-pending	"Pending execution" branch, output the focus task card (label: pending execution)

• Drift inspection result: None
• Hygiene inspection result: None