Back to Details

spec-driven-sync-specs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
You are helping the user synchronize 
.spec-driven/specs/
with behavior that already exists in the repository.
你需要帮助用户同步
.spec-driven/specs/
目录与代码仓库中已存在的行为。

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/
目录必须存在于项目根目录下。在继续操作前，请先验证：
ls .spec-driven/
如果该命令执行失败，说明项目未初始化，请先运行 
/spec-driven-init
。

Steps

操作步骤

  1. Choose the scan scope — determine whether the user wants:
    • a repository-wide scan
    • a scoped scan for a specific directory, module, or feature area
    If the user already gave a scope, use it. If not, ask whether to scan the whole repository or a narrower target.
  2. Read spec context first — before deciding that any drift exists, read:
    • .spec-driven/config.yaml
    • .spec-driven/specs/INDEX.md
    • every main spec file that appears relevant to the chosen scan scope
  3. Read repository evidence in the chosen scope — inspect the code, tests, and nearby documentation that define current observable behavior in that scope.
    • Prefer files that expose behavior directly: CLI commands, handlers, user-facing flows, tests, and docs
    • Do not treat internal implementation details as requirements
  4. Classify drift findings — compare the repository evidence to the current specs and sort findings into:
    • confirmed behavior that exists in code but is missing from specs
    • existing requirements that appear outdated or incomplete
    • ambiguous findings that need human confirmation before they become specs
    • areas with no meaningful drift in the scanned scope
  5. Report drift summary in chat — present a concise summary covering:
    • the scan scope that was analyzed
    • confirmed gaps or outdated spec areas, with specific file references
    • ambiguous findings that need human input
    • areas in scope where no meaningful drift was found
  6. Get user confirmation — before editing any spec file, ask the user to confirm the proposed changes. List each spec file that will be added, modified, or removed. Do not proceed until the user explicitly approves.
  7. Edit spec files directly — for each confirmed gap:
    • edit the corresponding file under 
      .spec-driven/specs/
    • add, modify, or remove 
      ### Requirement:
      blocks as appropriate
    • preserve or update 
      mapping.implementation
      and 
      mapping.tests
      frontmatter to match the repository evidence used for the sync
    • describe observable behavior only
    • if no existing category or file fits, create the new file under 
      .spec-driven/specs/
      with the correct relative path
  8. Refresh INDEX.md — after all spec edits are complete, run:
    node {{SKILL_DIR}}/scripts/spec-driven.js init
    This regenerates 
    .spec-driven/specs/INDEX.md
    to reflect the current file state.
    If mapping frontmatter changed, also run:
    node {{SKILL_DIR}}/scripts/spec-driven.js verify-spec-mappings
  9. Report final changes — summarize what was done:
    • which spec files were added, modified, or removed
    • a brief description of the drift that was fixed in each file
    • any ambiguous findings that were left unresolved and why
  1. 选择扫描范围——确定用户想要的扫描范围：
    • 全仓库扫描
    • 针对特定目录、模块或功能区域的范围扫描
    如果用户已经给出了范围，请直接使用。如果没有，询问用户是要扫描整个仓库还是更小的目标范围。
  2. 优先读取spec上下文——在判定存在任何偏差之前，先读取以下内容：
    • .spec-driven/config.yaml
    • .spec-driven/specs/INDEX.md
    • 所有与所选扫描范围相关的主要spec文件
  3. 读取所选范围内的仓库凭证——检查该范围内定义当前可观测行为的代码、测试和周边文档：
    • 优先选择直接暴露行为的文件：CLI命令、处理器、面向用户的流程、测试和文档
    • 不要将内部实现细节视为需求
  4. 对偏差发现结果进行分类——将仓库凭证与当前spec进行对比，将发现结果分为以下几类：
    • 代码中已存在但spec中缺失的已确认行为
    • 看起来已过时或不完整的现有需求
    • 在纳入spec前需要人工确认的歧义发现
    • 扫描范围内无明显偏差的区域
  5. 在聊天中报告偏差摘要——提交简洁的摘要，内容包括：
    • 已分析的扫描范围
    • 已确认的缺口或过时的spec区域，附带具体的文件引用
    • 需要人工输入的歧义发现
    • 扫描范围内无明显偏差的区域
  6. 获取用户确认——在编辑任何spec文件前，请先请求用户确认拟议的变更。列出所有将要新增、修改或删除的spec文件，在用户明确批准前不要继续操作。
  7. 直接编辑spec文件——针对每个已确认的缺口：
    • 编辑
      .spec-driven/specs/
      目录下对应的文件
    • 根据情况新增、修改或删除
      ### Requirement:
      块
    • 保留或更新frontmatter中的
      mapping.implementation
      和
      mapping.tests
      ，使其与用于同步的仓库凭证匹配
    • 仅描述可观测的行为
    • 如果没有匹配的现有分类或文件，在
      .spec-driven/specs/
      目录下创建对应相对路径的新文件
  8. 刷新INDEX.md——所有spec编辑完成后，运行：
    node {{SKILL_DIR}}/scripts/spec-driven.js init
    该命令会重新生成
    .spec-driven/specs/INDEX.md
    以反映当前的文件状态。
    如果mapping的frontmatter发生了变更，还需要运行：
    node {{SKILL_DIR}}/scripts/spec-driven.js verify-spec-mappings
  9. 报告最终变更——总结已完成的操作：
    • 哪些spec文件被新增、修改或删除
    • 每个文件中修复的偏差的简要描述
    • 任何未解决的歧义发现以及未解决的原因

Rules

规则

  • This is a documentation skill only — do not change product code
  • Read spec context before judging drift
  • Respect the user-selected scope; do not imply full-repository coverage after a scoped scan
  • Use code, tests, and nearby docs as evidence, but write only observable behavior into the specs
  • Do not create a change — edit 
    .spec-driven/specs/
    files directly
  • Do not write a standalone report file; the summary belongs in chat
  • Get explicit user confirmation before editing any spec file
  • Keep implementation and test mappings in frontmatter, not in requirement prose
  • 这是一个仅用于文档的skill——不要修改产品代码
  • 在判定偏差前先读取spec上下文
  • 遵守用户选择的扫描范围；在范围扫描完成后不要暗示覆盖了全仓库
  • 使用代码、测试和周边文档作为凭证，但仅将可观测行为写入spec
  • 不要生成变更记录——直接编辑
    .spec-driven/specs/
    目录下的文件
  • 不要生成独立的报告文件；摘要需放在聊天中
  • 编辑任何spec文件前需获得用户的明确确认
  • 将实现和测试映射放在frontmatter中，不要放在需求正文里