spec-driven-resync-code-mapping

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

You are helping the user retrofit or repair spec-code mapping frontmatter in

.spec-driven/specs/

files.

你需要帮助用户改造或修复

.spec-driven/specs/

目录下文件中的spec-代码映射frontmatter。

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

操作步骤

Choose the remapping scope — determine whether the user wants to remap:
- all main spec files
- one spec category or file
- only specs reported by
```
verify-spec-mappings
```
  as malformed or stale
If the user already gave a scope, use it. If not, ask which scope to repair.
Read spec context first — before proposing mapping edits, read:
- ```
.spec-driven/config.yaml
```
- ```
.spec-driven/specs/INDEX.md
```
- every main spec file in the selected scope
- any existing mapping frontmatter in those spec files
Run mapping validation — run:
```
node {{SKILL_DIR}}/scripts/spec-driven.js verify-spec-mappings
```
Use the JSON result to identify missing frontmatter, malformed mapping fields, non-string entries, and missing mapped files.
Inspect repository evidence — infer mappings by converging on the current repository evidence, not by trying to list every related file. Keep implementation files separate from test files.
- Derive search terms from the spec path, filename, requirement titles, scenario titles, and distinctive command names, skill names, config keys, or domain terms in the spec body.
- Search likely implementation and test locations for exact terms first, then obvious variants such as
```
kebab-case
```
  ,
```
snake_case
```
  ,
```
camelCase
```
  , and singular/plural forms.
- Keep files that directly implement, expose, validate, or verify the behavior. Exclude generic helpers unless the behavior is primarily implemented there or the entrypoint would otherwise be misleading without it.
- Follow at most one level of structural evidence when needed: imports, exports, command registries, dispatch tables, and tests that directly execute or assert the behavior.
- ```
mapping.implementation
```
  should contain primary implementation files, feature entrypoints, and thin orchestrators that materially wire the behavior together.
- ```
mapping.tests
```
  should contain tests that directly verify the behavior.
- If behavior spans multiple primary files, include all of them. If evidence is weak or conflicting, keep the smaller confident set and report the ambiguity.
- Stop once the mapping covers the main files a maintainer would inspect first. Do not chase every transitive helper.
- For framework or meta-specs, start with files named directly in the spec, then add workflow artifacts that define or enforce the behavior, such as relevant
```
skills/*/SKILL.md
```
  ,
```
scripts/spec-driven.ts
```
  ,
```
install.sh
```
  , test files, and top-level docs.
- Use repo structure as evidence: installation specs map to installer code, installation tests, and shipped skills; mapping-validation specs map to validator code, spec-format docs, and validator tests.
- Treat the mapping as complete when each requirement is covered by at least one primary implementation file and one test or verification path where such evidence exists.
- If a requirement still has no confident mapping, mark it ambiguous and ask the user instead of inventing coverage.
Classify findings — sort findings into:
- missing mapping frontmatter that can be confidently added
- malformed mapping frontmatter that can be repaired without changing requirement behavior
- stale paths that can be replaced with current implementation or test files
- behavior/spec drift that requires
```
/spec-driven-sync-specs
```
  ,
```
/spec-driven-spec-edit
```
  , or a normal change workflow
- ambiguous mappings that require human input
For each target spec with a confident candidate mapping, run:
```
node {{SKILL_DIR}}/scripts/spec-driven.js audit-spec-mapping-coverage <spec-path> [--implementation <repo-path> ...] [--tests <repo-path> ...]
```
Use the candidate implementation and test sets as the explicit evidence inputs. Use the
```
node {{SKILL_DIR}}/scripts/spec-driven.js audit-spec-mapping-coverage ...
```
output to identify missing and extra mapping entries before presenting the edit.
Also run:
```
node {{SKILL_DIR}}/scripts/spec-driven.js audit-unmapped-spec-evidence [--implementation <repo-path> ...] [--tests <repo-path> ...]
```
Use the same candidate evidence set to check whether some files are not mapped by any main spec at all. If that happens, decide whether the likely next step is mapping repair for another spec, spec synchronization, direct spec editing, or a normal change workflow.
Present proposed mapping edits — before editing any file, show the user:
- each spec file whose frontmatter will change
- the proposed
```
mapping.implementation
```
  paths
- the proposed
```
mapping.tests
```
  paths
- any behavior/spec drift or ambiguous mapping that will not be edited by this skill
Wait for explicit confirmation before writing files.
Apply confirmed mapping repairs — after confirmation, edit only mapping frontmatter in the selected main spec files. Do not change implementation files. Do not rewrite requirement bodies unless the user switches to
```
/spec-driven-sync-specs
```
,
```
/spec-driven-spec-edit
```
, or a normal change workflow.
Validate after editing — rerun:
```
node {{SKILL_DIR}}/scripts/spec-driven.js verify-spec-mappings
```
Fix safe frontmatter format issues immediately and rerun
```
node {{SKILL_DIR}}/scripts/spec-driven.js verify-spec-mappings
```
. If any remaining error needs human judgment, report it clearly.
Report final result — summarize:
- which spec files had mapping frontmatter added or repaired
- which stale paths were replaced
- whether mapping validation now passes
- any behavior/spec drift or ambiguity left for another workflow

选择重映射范围 —— 确定用户想要重映射的范围：
- 所有主spec文件
- 单个spec分类或文件
- 仅
```
verify-spec-mappings
```
  报告的格式错误或过期的spec
如果用户已经指定了范围，直接使用即可；如果没有，请询问用户需要修复的范围。
优先读取spec上下文 —— 在提出映射编辑建议前，请先读取以下内容：
- ```
.spec-driven/config.yaml
```
- ```
.spec-driven/specs/INDEX.md
```
- 所选范围内的所有主spec文件
- 这些spec文件中已存在的所有映射frontmatter
运行映射校验 —— 执行命令：
```
node {{SKILL_DIR}}/scripts/spec-driven.js verify-spec-mappings
```
利用返回的JSON结果识别缺失的frontmatter、格式错误的映射字段、非字符串类型的条目，以及缺失的映射文件。
检查仓库证据 —— 基于当前仓库的现有证据推导映射，不要尝试列出所有相关文件，需将实现文件和测试文件分开。
- 从spec路径、文件名、需求标题、场景标题，以及spec正文中独特的命令名、skill名称、配置键或领域术语中提取搜索词。
- 优先在可能的实现和测试位置搜索精确匹配的术语，再搜索明显的变体形式，比如
```
kebab-case
```
  、
```
snake_case
```
  、
```
camelCase
```
  以及单复数形式。
- 保留直接实现、暴露、校验或验证对应行为的文件；排除通用工具函数，除非相关行为主要在这些文件中实现，或者缺少这些文件会导致入口点产生误导。
- 必要时最多只追溯一层结构证据：导入、导出、命令注册中心、调度表，以及直接执行或断言对应行为的测试。
- ```
mapping.implementation
```
  应包含核心实现文件、功能入口点，以及将相关行为实质性串联起来的轻量编排文件。
- ```
mapping.tests
```
  应包含直接验证对应行为的测试文件。
- 如果行为涉及多个核心文件，将全部文件都纳入；如果证据不足或存在冲突，保留范围更小的可确认集合，并上报歧义。
- 当映射覆盖了维护者会优先检查的核心文件后即可停止，不要追溯所有传递依赖的工具函数。
- 对于框架或元spec，先从spec中直接命名的文件开始，再添加定义或强制执行对应行为的工作流产物，比如相关的
```
skills/*/SKILL.md
```
  、
```
scripts/spec-driven.ts
```
  、
```
install.sh
```
  、测试文件和顶层文档。
- 将仓库结构作为证据：安装类spec对应安装器代码、安装测试和发布的skill；映射校验类spec对应校验器代码、spec格式文档和校验器测试。
- 当每个需求都至少被一个核心实现文件和一条存在对应证据的测试/验证路径覆盖时，即可认为映射已完成。
- 如果某个需求仍然没有可确认的映射，将其标记为歧义并询问用户，不要虚构覆盖范围。
对发现的问题分类 —— 将发现的问题归类为：
- 可以确定添加的缺失映射frontmatter
- 无需修改需求行为即可修复的格式错误的映射frontmatter
- 可以替换为当前实现或测试文件的过期路径
- 需要执行
```
/spec-driven-sync-specs
```
  、
```
/spec-driven-spec-edit
```
  或走常规变更流程的行为/spec偏移
- 需要人工输入的歧义映射
对于每个有明确候选映射的目标spec，执行命令：
```
node {{SKILL_DIR}}/scripts/spec-driven.js audit-spec-mapping-coverage <spec-path> [--implementation <repo-path> ...] [--tests <repo-path> ...]
```
将候选的实现和测试集合作为明确的证据输入，在展示编辑内容前，使用
```
node {{SKILL_DIR}}/scripts/spec-driven.js audit-spec-mapping-coverage ...
```
的输出识别缺失和多余的映射条目。
同时运行：
```
node {{SKILL_DIR}}/scripts/spec-driven.js audit-unmapped-spec-evidence [--implementation <repo-path> ...] [--tests <repo-path> ...]
```
使用相同的候选证据集合检查是否存在未被任何主spec映射的文件，如果存在，判断下一步应该是修复其他spec的映射、spec同步、直接编辑spec还是走常规变更流程。
展示映射编辑提案 —— 在编辑任何文件前，向用户展示：
- 每个frontmatter会发生变更的spec文件
- 提案的
```
mapping.implementation
```
  路径
- 提案的
```
mapping.tests
```
  路径
- 所有不会被本skill编辑的行为/spec偏移或歧义映射
写入文件前请等待用户明确确认。
应用已确认的映射修复 —— 获得确认后，仅编辑所选主spec文件中的映射frontmatter，不要修改实现文件，不要重写需求正文，除非用户切换到
```
/spec-driven-sync-specs
```
、
```
/spec-driven-spec-edit
```
或常规变更流程。
编辑后校验 —— 重新运行：
```
node {{SKILL_DIR}}/scripts/spec-driven.js verify-spec-mappings
```
立即修复安全的frontmatter格式问题，然后重新运行
```
node {{SKILL_DIR}}/scripts/spec-driven.js verify-spec-mappings
```
。如果仍有需要人工判断的错误，清晰上报。
上报最终结果 —— 总结以下内容：
- 哪些spec文件的映射frontmatter被添加或修复
- 哪些过期路径被替换
- 映射校验当前是否通过
- 所有留给其他流程处理的行为/spec偏移或歧义问题

Rules

规则

This is a planning/documentation skill only — do not change implementation code or tests
Do not create, modify, archive, or cancel entries under
```
.spec-driven/changes/
```
Do not rewrite requirement behavior while repairing mappings
Keep
```
mapping.implementation
```
and
```
mapping.tests
```
separate
Use repo-relative file paths only
Keep mappings at file granularity; do not use line numbers, ranges, or symbols

Always run

node {{SKILL_DIR}}/scripts/spec-driven.js verify-spec-mappings

before and after confirmed edits

Get explicit user confirmation before editing any spec file
If mapping repair reveals behavior/spec drift, recommend the appropriate spec synchronization or change workflow instead of silently changing requirements

这是一个仅用于规划/文档的skill —— 不要修改实现代码或测试
不要创建、修改、归档或取消
```
.spec-driven/changes/
```
目录下的条目
修复映射时不要重写需求行为
保持
```
mapping.implementation
```
和
```
mapping.tests
```
分开
仅使用仓库相对文件路径
保持映射为文件粒度，不要使用行号、范围或符号

在确认编辑前后都必须运行

node {{SKILL_DIR}}/scripts/spec-driven.js verify-spec-mappings

编辑任何spec文件前必须获得用户明确确认
如果映射修复发现了行为/spec偏移，推荐合适的spec同步或变更流程，不要静默修改需求