Back to Details

roadmap-sync

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
You are helping the user synchronize 
.spec-driven/roadmap/
with the current change history.
你需要帮助用户将
.spec-driven/roadmap/
与当前变更历史同步。

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.
If 
.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

操作步骤

  1. Read roadmap state first — before changing anything, read:
    • .spec-driven/config.yaml
    • .spec-driven/roadmap/INDEX.md
    • every milestone file listed in the roadmap index
    • run 
      node {{SKILL_DIR}}/scripts/spec-driven.js roadmap-status
    • inspect the returned milestone and planned change state summary
  2. Compare roadmap to repository reality — use the 
    roadmap-status
    output as the source of deterministic comparison. For each milestone in scope, identify:
    • planned changes that are archived
    • planned changes that still exist as active work
    • planned changes that are missing or renamed
    • milestone statuses that no longer match the derived status
    • any ambiguity the script cannot resolve, such as likely renames or roadmap prose that still needs human judgment
  3. Update roadmap files — reconcile milestone status and listed change state based on the repository evidence you found.
  4. Preserve roadmap rules — during sync:
    • do not mark a milestone complete unless every listed planned change is archived
    • keep the roadmap as planning state, not an implementation log
  5. Validate roadmap size before finish — run:
    node {{SKILL_DIR}}/scripts/spec-driven.js verify-roadmap
    If validation reports that any milestone is too large, stop and tell the user to split it instead of presenting roadmap sync as complete.
  6. Report the sync result — summarize:
    • milestones updated
    • planned changes whose state changed
    • missing or ambiguous references that still need human cleanup
  1. 优先读取路线图状态 —— 在做出任何修改前，请先读取以下内容：
    • .spec-driven/config.yaml
    • .spec-driven/roadmap/INDEX.md
    • 路线图索引中列出的所有里程碑文件
    • 运行
      node {{SKILL_DIR}}/scripts/spec-driven.js roadmap-status
    • 检查返回的里程碑和计划变更状态汇总
  2. 将路线图与仓库实际情况对比 —— 以
    roadmap-status
    的输出作为确定性对比的数据源。针对每个涉及的里程碑，识别：
    • 已归档的计划变更
    • 仍处于活跃工作状态的计划变更
    • 缺失或已重命名的计划变更
    • 与推导状态不再匹配的里程碑状态
    • 脚本无法解决的任何歧义，例如可能的重命名，或仍需人工判断的路线图文本
  3. 更新路线图文件 —— 根据你找到的仓库证据，核对里程碑状态和列出的变更状态
  4. 遵守路线图规则 —— 同步过程中：
    • 除非所有列出的计划变更都已归档，否则不要将里程碑标记为已完成
    • 保留路线图作为规划状态，而非实现日志
  5. 完成前验证路线图规模 —— 运行：
    node {{SKILL_DIR}}/scripts/spec-driven.js verify-roadmap
    如果验证报告显示任何里程碑过大，请停止操作并告知用户需要拆分里程碑，而非直接返回路线图同步已完成。
  6. 上报同步结果 —— 汇总以下内容：
    • 已更新的里程碑
    • 状态发生变化的计划变更
    • 仍需人工清理的缺失或歧义引用

Rules

规则

  • This is a planning/documentation skill only — do not change product code
  • Use 
    roadmap-status
    plus roadmap files as the source of truth for deterministic status comparison
  • Do not preserve stale manual labels that conflict with actual archive state
  • Surface ambiguity explicitly when a roadmap entry no longer matches any change
  • 这仅属于规划/文档类技能 —— 不要修改产品代码
  • 以
    roadmap-status
    输出加路线图文件作为确定性状态对比的可信数据源
  • 不要保留与实际归档状态冲突的陈旧手动标签
  • 当路线图条目与任何变更都不匹配时，明确指出歧义