roadmap-recommend

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

You are helping the user choose the next change from the roadmap and turn the accepted recommendation into a normal spec-driven change.

你需要帮助用户从路线图中选择下一个变更，并将获得认可的推荐转化为标准的spec-driven变更。

Prerequisites

前置条件

The

.spec-driven/

directory must exist at the project root. Before proceeding, verify:

ls .spec-driven/

If this fails, the project is not initialized. Run

/spec-driven-init

first.

.spec-driven/roadmap/

is missing, repair the scaffold first:

node {{SKILL_DIR}}/scripts/spec-driven.js init

.spec-driven/

目录必须存在于项目根目录下。在继续操作前，请验证：

ls .spec-driven/

如果执行失败，说明项目未初始化，请先运行

/spec-driven-init

。

如果

.spec-driven/roadmap/

缺失，请先修复脚手架：

node {{SKILL_DIR}}/scripts/spec-driven.js init

Steps

步骤

Read roadmap context first — before recommending anything, read:
- ```
.spec-driven/config.yaml
```
- ```
.spec-driven/roadmap/INDEX.md
```
- the milestone files relevant to the current phase
- ```
.spec-driven/specs/INDEX.md
```
- the relevant main spec files the recommended change is likely to touch
- ```
node {{SKILL_DIR}}/scripts/spec-driven.js roadmap-status
```
- the planned change entries for the candidates you are considering as single-line roadmap items in the canonical format
```
- \
```
  <change-name>` - Declared: <status> - <summary>`
- treat milestone declared statuses as limited to
```
proposed
```
  ,
```
active
```
  ,
```
blocked
```
  , or
```
complete
```
- treat planned change declared statuses as limited to
```
planned
```
  or
```
complete
```
You MAY delegate bounded analysis-only work such as candidate comparison, roadmap-context summarization, or likely spec-path discovery to a sub-agent. The parent agent MUST keep the final recommendation, the user confirmation checkpoint, and all proposal artifact writes.
Understand what the user wants optimized — determine whether the user wants the next change chosen for impact, urgency, dependency order, risk reduction, or some other planning goal.
Recommend one candidate change — propose:
- a kebab-case change name
- which milestone it comes from
- why it is the best next candidate
- what alternatives were not chosen yet The recommended candidate MUST already appear under a milestone
```
## Planned Changes
```
  section.
Present a proposal checkpoint — before creating any files, summarize:
- the proposed change name
- which milestone it comes from
- the goal and scope of the recommended change
- the main spec areas expected to change
- why this item is the best next step
- any unresolved questions that would go into
```
questions.md
```
Then ask for explicit confirmation. If the user wants revisions, continue the recommendation discussion and re-summarize until confirmed.
Resolve open questions before scaffolding — if any unresolved questions remain after the recommendation summary:
- present each open question as a structured block with:
  - ```
  Question
```
- ```
Explanation
```
  - ```
  Impact
```
- ```
Recommendation
```
- ask the user to answer or confirm the decision needed
- ```
Explanation
```
  must clarify why the issue is unresolved or what decision is still blocking the proposal
- ```
Impact
```
  must describe what part of the proposal depends on the answer
- ```
Recommendation
```
  may suggest a preferred answer, but only as a suggestion
- do not treat your recommendation as the resolved answer
- do not continue until the user has given an exact answer or explicit confirmation

Scaffold the change after confirmation — run:

node {{SKILL_DIR}}/scripts/spec-driven.js propose <name>

This creates

.spec-driven/changes/<name>/

with the seeded templates.

Fill the five proposal artifacts — after scaffolding, complete the same proposal workflow used by
```
/roadmap-propose
```
:
- write
```
proposal.md
```
  with What, Why, Scope, and Unchanged Behavior
- write
```
design.md
```
  with Approach, Key Decisions, and Alternatives Considered
- populate
```
changes/<name>/specs/
```
  with delta spec files aligned by path with the main
```
.spec-driven/specs/
```
  structure
- include mapping frontmatter in delta spec files when implementation and test paths are knowable from repository context
- write
```
tasks.md
```
  with atomic checklist items under
```
## Implementation
```
  ,
```
## Testing
```
  , and
```
## Verification
```
- make
```
## Testing
```
  include at least one explicit lint or validation command task and one explicit unit test command task when those commands are knowable from repository context
- write
```
questions.md
```
  , recording every unresolved point under
```
## Open
```
  , or leave
```

```
  if nothing is unclear
Use the recommended milestone context as planning input, but treat the selected planned change itself as a single-line roadmap item.
Validate before presenting the proposal — run:
```
node {{SKILL_DIR}}/scripts/spec-driven.js verify <name>
```
- Fix any safe artifact-format issues immediately and rerun
```
verify
```
- If only open questions remain, treat that as expected at proposal time and surface those questions clearly
- If any non-question error remains, stop and report it instead of presenting the proposal as ready
Offer the execution handoff — show the user the generated artifacts, summarize the final proposed scope, list any open questions that must be answered before implementation, and ask whether they want to:
- enter
```
/spec-driven-apply <name>
```
  for the stepwise execution path
- enter
```
/spec-driven-auto
```
  for the end-to-end execution path Do not auto-enter either execution path without the user's explicit choice.

首先读取路线图上下文 —— 在推荐任何内容前，请读取：
- ```
.spec-driven/config.yaml
```
- ```
.spec-driven/roadmap/INDEX.md
```
- 和当前阶段相关的里程碑文件
- ```
.spec-driven/specs/INDEX.md
```
- 推荐变更可能涉及的相关主规范文件
- ```
node {{SKILL_DIR}}/scripts/spec-driven.js roadmap-status
```
- 你考虑的候选变更条目，需为标准格式的单行路线图项：
```
- \
```
  <change-name>` - Declared: <status> - <summary>`
- 里程碑声明状态仅限
```
proposed
```
  、
```
active
```
  、
```
blocked
```
  或
```
complete
```
- 规划变更的声明状态仅限
```
planned
```
  或
```
complete
```
你可以将有限的仅分析类工作委派给sub-agent，比如候选对比、路线图上下文总结、可能的规范路径发现等。parent-agent必须保留最终推荐权、用户确认检查点，以及所有提案产物的写入权限。
明确用户的优化目标 —— 确定用户选择下一个变更的优先级维度是影响度、紧急度、依赖顺序、风险降低还是其他规划目标。
推荐一个候选变更 —— 提案应包含：
- kebab-case格式的变更名称
- 该变更所属的里程碑
- 它成为最佳下一个候选的原因
- 暂未选择的其他替代选项推荐的候选必须已经出现在某个里程碑的
```
## Planned Changes
```
  章节下。
提供提案检查点 —— 在创建任何文件前，总结以下内容：
- 提议的变更名称
- 该变更所属的里程碑
- 推荐变更的目标和范围
- 预计会变更的主要规范领域
- 该事项成为最佳下一步的原因
- 所有会被写入
```
questions.md
```
  的未解决问题
随后请求用户明确确认。如果用户需要修改，继续讨论推荐内容并重新总结，直到获得确认。
脚手架搭建前解决未解决问题 —— 如果推荐总结后仍有未解决问题：
- 将每个未解决问题展示为结构化块，包含：
  - ```
  Question
```
- ```
Explanation
```
  - ```
  Impact
```
- ```
Recommendation
```
- 请求用户回答或确认所需的决策
- ```
Explanation
```
  必须说明问题未解决的原因，或者什么决策仍在阻塞提案
- ```
Impact
```
  必须描述提案的哪一部分依赖该问题的答案
- ```
Recommendation
```
  可以提出偏好答案，但仅作为建议
- 不要将你的推荐视为已解决的答案
- 在用户给出明确答案或明确确认前不要继续操作
确认后搭建变更脚手架 —— 运行：
```
node {{SKILL_DIR}}/scripts/spec-driven.js propose <name>
```
该命令会创建
```
.spec-driven/changes/<name>/
```
目录并填充种子模板。
填充五个提案产物 —— 脚手架搭建完成后，完成和
```
/roadmap-propose
```
相同的提案工作流：
- 编写
```
proposal.md
```
  ，包含What、Why、Scope和Unchanged Behavior部分
- 编写
```
design.md
```
  ，包含Approach、Key Decisions和Alternatives Considered部分
- 在
```
changes/<name>/specs/
```
  目录下填充增量规范文件，路径和主
```
.spec-driven/specs/
```
  结构对齐
- 如果可以从仓库上下文得知实现和测试路径，在增量规范文件的前置元数据中添加映射
- 编写
```
tasks.md
```
  ，在
```
## Implementation
```
  、
```
## Testing
```
  和
```
## Verification
```
  章节下填写原子检查项
- 如果可以从仓库上下文得知相关命令，
```
## Testing
```
  章节需至少包含一个明确的lint或校验命令任务，以及一个明确的单元测试命令任务
- 编写
```
questions.md
```
  ，在
```
## Open
```
  下记录所有未解决的点，如果没有未明确的内容则写入
```

```
使用推荐的里程碑上下文作为规划输入，但将选中的规划变更本身视为单行路线图项。
展示提案前校验 —— 运行：
```
node {{SKILL_DIR}}/scripts/spec-driven.js verify <name>
```
- 立即修复所有可安全处理的产物格式问题，并重跑
```
verify
```
- 如果仅剩下未解决问题，视为提案阶段的正常情况，清晰展示这些问题即可
- 如果存在非问题类的剩余错误，停止操作并报告错误，不要将提案作为就绪状态展示
提供执行交接选项 —— 向用户展示生成的产物，总结最终提案范围，列出所有实现前必须回答的未解决问题，并询问用户是否想要：
- 输入
```
/spec-driven-apply <name>
```
  选择分步执行路径
- 输入
```
/spec-driven-auto
```
  选择端到端执行路径没有用户明确选择的情况下，不要自动进入任何执行路径。

Rules

规则

Do not implement code — this skill is planning only
Use roadmap context and roadmap-status output as the basis for recommendation
Explain why the recommended change should come next
Recommend only work that already exists under
```
Planned Changes
```
Do not scaffold proposal artifacts until the user explicitly confirms the recommendation summary and change name
If open questions remain, ask the user to resolve them before scaffolding
For each open question, provide
```
Question
```
,
```
Explanation
```
,
```
Impact
```
, and
```
Recommendation
```
If testing commands are not knowable from repository context, record that as an open question instead of inventing commands
Recommended answers do not count as question resolution without explicit user confirmation
After confirmation, follow the same artifact-writing and validation standard as
```
/roadmap-propose
```
Do not let a sub-agent scaffold the change or own the recommendation checkpoint
Keep implementation and test mappings in spec frontmatter, not in requirement prose

不要实现代码 —— 本技能仅用于规划
以路线图上下文和roadmap-status输出作为推荐基础
解释为什么推荐的变更应该排在下一位
仅推荐已经存在于
```
Planned Changes
```
下的工作
在用户明确确认推荐总结和变更名称前，不要搭建提案产物脚手架
如果仍有未解决问题，在搭建脚手架前请求用户解决
每个未解决问题都需要提供
```
Question
```
、
```
Explanation
```
、
```
Impact
```
和
```
Recommendation
```
如果无法从仓库上下文得知测试命令，将其记录为未解决问题，不要虚构命令
没有用户明确确认的情况下，推荐答案不算问题已解决
确认后，遵循和
```
/roadmap-propose
```
相同的产物编写和校验标准
不要让sub-agent搭建变更脚手架或持有推荐检查点权限
将实现和测试映射存放在规范前置元数据中，不要写在需求正文中