spec-kit-reconcile

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spec Kit Reconcile

Close specification drift by updating existing Spec Kit artifacts in-place.

通过就地更新现有Spec Kit工件来解决规格漂移问题。

When to Use

适用场景

You discover specification drift at any stage (specify, clarify, plan, tasks, analyze, or implement) and need artifacts realigned before continuing.
Code exists, but behavior still misses expected flows (routing/navigation wiring, integration handoff, validation UX, coverage gaps).
```
spec-kit-analyze
```
found issues that require coordinated edits across
```
spec.md
```
,
```
plan.md
```
, and
```
tasks.md
```
.
You need targeted remediation planning without creating a new feature branch.

在任何阶段（规格定义、澄清、规划、任务分解、分析或实施）发现规格漂移，需要先调整工件再继续推进工作。
代码已存在，但功能行为仍未达到预期流程（路由/导航连接、集成交接、验证UX、覆盖缺口）。
```
spec-kit-analyze
```
发现问题，需要跨
```
spec.md
```
、
```
plan.md
```
和
```
tasks.md
```
进行协同编辑。
需要针对性的修复规划，且无需创建新功能分支。

When Not to Use

不适用场景

You need a brand-new feature spec (
```
spec-kit-specify
```
first).
You need first-pass design decomposition from an approved spec (
```
spec-kit-plan
```
first).
You only need a read-only audit (
```
spec-kit-analyze
```
).
You are only executing already-correct tasks (
```
spec-kit-implement
```
).

需要全新的功能规格（应先使用
```
spec-kit-specify
```
）。
需要根据已批准的规格进行首次设计分解（应先使用
```
spec-kit-plan
```
）。
仅需要只读审计（应使用
```
spec-kit-analyze
```
）。
仅需执行已确认正确的任务（应使用
```
spec-kit-implement
```
）。

Router Fit

流程适配

First-class standalone remediation route when the developer identifies drift at any stage.
Also serves as the default remediation handoff from
```
spec-kit-analyze
```
and
```
spec-kit-implement
```
.
Produces reconciled artifacts and next-step routing based on the updated artifact state.

当开发人员在任何阶段发现漂移时，可作为独立的优先修复流程。
同时作为
```
spec-kit-analyze
```
和
```
spec-kit-implement
```
的默认修复交接流程。
生成协调后的工件，并根据更新后的工件状态推荐下一步流程。

Critical Constraints

关键约束

Never create a new feature branch and never run feature-creation scripts.
Keep edits targeted; preserve artifact structure and heading order.
Prefer append-only updates for
```
tasks.md
```
; do not renumber existing tasks.
Run at most one clarification round (maximum 5 questions).
Keep unresolved
```
NEEDS CLARIFICATION
```
markers to 3 or fewer.

绝不创建新功能分支，绝不运行功能创建脚本。
编辑需针对性，保留工件结构和标题顺序。
对
```
tasks.md
```
优先采用追加式更新；不得重新编号现有任务。
最多进行一轮澄清（最多5个问题）。
未解决的
```
NEEDS CLARIFICATION
```
标记不得超过3个。

Preconditions

前置条件

Run from repository root (or a subdirectory inside it).
Active feature context resolves to one
```
specs/<feature>/
```
directory.
User provides a concrete gap report (symptoms, mismatches, missing wiring, and/or scope hints like
```
plan-only
```
or
```
tasks-only
```
).

从仓库根目录（或其子目录）运行。
活跃功能上下文对应到一个
```
specs/<feature>/
```
目录。
用户提供具体的缺口报告（症状、不匹配项、缺失的连接，以及
```
plan-only
```
或
```
tasks-only
```
等范围提示）。

Workflow

工作流程

Validate reconcile input:
- If no gap report is provided, stop with
```
ERROR: No gap report provided
```
  .
- Parse user scope constraints (for example
```
spec-only
```
  ,
```
plan-only
```
  ,
```
tasks-only
```
  ) and preserve them throughout.

Resolve artifact paths exactly once:

Run

scripts/check-prerequisites.sh --json --paths-only --include-tasks

exactly once.

Parse:

```
REPO_ROOT
```
```
BRANCH
```
```
FEATURE_DIR
```
```
FEATURE_SPEC
```
```
IMPL_PLAN
```
```
TASKS
```

Validate required files:
- If
```
FEATURE_SPEC
```
  is missing, route to
```
spec-kit-specify
```
  .
- If
```
IMPL_PLAN
```
  is missing, route to
```
spec-kit-plan
```
  .

Load reconcile context:
- Required:
```
spec.md
```
  ,
```
plan.md
```
  .
- Optional (when present):
```
tasks.md
```
  ,
```
data-model.md
```
  ,
```
contracts/
```
  ,
```
research.md
```
  ,
```
quickstart.md
```
  .
- Load
```
memory/constitution.md
```
  and enforce its MUST-level constraints.
- If
```
memory/constitution.md
```
  is missing, stop and route to
```
spec-kit-constitution
```
  .

Normalize the gap report into actionable items:

For each gap, capture:

```
Title
```
```
Category
```
```
Evidence
```
```
Desired Outcome
```
```
Severity (HIGH|MEDIUM|LOW)
```

Preferred categories:

```
Navigation/Wiring
```
```
Integration/Contracts
```
```
Validation & UX
```
```
Authorization/Permissions
```
```
Test Coverage
```
```
Non-Functional
```
```
Docs
```

Clarify once when needed:
- Ask questions only when answers change scope, UX behavior, acceptance criteria, or remediation cost.
- Ask at most 5 total questions in one round, then proceed.
- If an
```
askQuestions
```
  -style tool exists in the current runtime, prefer it for this step to collect all multiple-choice answers in one fast interaction.
- When using
```
askQuestions
```
  , provide 2-5 mutually exclusive options per question, put the recommended option first, and allow a short custom response path.
- If no
```
askQuestions
```
  tool exists, fall back to the markdown prompt format below.
- Use this format for each question:

markdown

undefined

验证协调输入：
- 若未提供缺口报告，终止操作并提示
```
ERROR: No gap report provided
```
  。
- 解析用户的范围约束（例如
```
spec-only
```
  、
```
plan-only
```
  、
```
tasks-only
```
  ），并在全程保留这些约束。

一次性解析工件路径：

精确运行一次

scripts/check-prerequisites.sh --json --paths-only --include-tasks

。

解析以下内容：

```
REPO_ROOT
```
```
BRANCH
```
```
FEATURE_DIR
```
```
FEATURE_SPEC
```
```
IMPL_PLAN
```
```
TASKS
```

验证必需文件：
- 若
```
FEATURE_SPEC
```
  缺失，引导至
```
spec-kit-specify
```
  。
- 若
```
IMPL_PLAN
```
  缺失，引导至
```
spec-kit-plan
```
  。

加载协调上下文：
- 必需文件：
```
spec.md
```
  、
```
plan.md
```
  。
- 可选文件（若存在）：
```
tasks.md
```
  、
```
data-model.md
```
  、
```
contracts/
```
  、
```
research.md
```
  、
```
quickstart.md
```
  。
- 加载
```
memory/constitution.md
```
  并强制执行其MUST级约束。
- 若
```
memory/constitution.md
```
  缺失，终止操作并引导至
```
spec-kit-constitution
```
  。
将缺口报告规范化为可执行项：
- 针对每个缺口，记录：
  - ```
  Title
```
  （标题）
- ```
Category
```
    （类别）
  - ```
  Evidence
```
  （证据）
- ```
Desired Outcome
```
    （预期结果）
  - ```
  Severity (HIGH|MEDIUM|LOW)
```
  （严重程度：高/中/低）
- 推荐类别：
  - ```
  Navigation/Wiring
```
  （导航/连接）
- ```
Integration/Contracts
```
    （集成/契约）
  - ```
  Validation & UX
```
  （验证与用户体验）
- ```
Authorization/Permissions
```
    （授权/权限）
  - ```
  Test Coverage
```
  （测试覆盖）
- ```
Non-Functional
```
    （非功能性需求）
  - ```
  Docs
```
  （文档）
必要时进行一轮澄清：
- 仅当答案会改变范围、UX行为、验收标准或修复成本时才提问。
- 一轮最多提问5个问题，之后继续推进。
- 若当前运行环境中存在
```
askQuestions
```
  类工具，优先使用该工具一次性收集所有选择题答案。
- 使用
```
askQuestions
```
  时，每个问题提供2-5个互斥选项，将推荐选项放在首位，并允许自定义短回复。
- 若不存在
```
askQuestions
```
  工具，回退至以下markdown提示格式。
- 每个问题使用如下格式：

markdown

undefined

Question [N]: [Topic]

Context: [Relevant spec/plan/tasks excerpt or summary] Decision Needed: [Single-sentence decision] Suggested Answers:

Option	Answer	Implications
A	[Option A]	[Impact]
B	[Option B]	[Impact]
C	[Option C]	[Impact]
Custom	Provide your own	[How it changes scope]

Your choice: [Wait for user response]


6. Map impact per artifact:

   - `spec.md`: user stories, acceptance criteria, user-visible scenarios, edge behaviors.
   - `plan.md`: architecture/modules, routing/navigation, integration contracts, testing strategy.
   - `tasks.md`: remediation work with exact file paths and ordering.
   - Respect scope constraints and explicitly mark skipped artifacts.

7. Apply targeted edits:

   - `spec.md`:
     - Update only impacted sections.
     - Add a concise `Revisions` note (timestamp + reason).
   - `plan.md`:
     - Update only sections needed for reconciliation.
     - Keep design-level detail; do not add implementation patch instructions.
   - `tasks.md`:
     - If it exists, append remediation tasks using `NextID = max(T###) + 1`.
     - Preserve existing phases; add `Remediation: Gaps` phase when cross-cutting tasks are needed.
     - If it does not exist, create a minimal remediation-focused `tasks.md` from:
       1. `{REPO_ROOT}/templates/tasks-template.md`
       2. `{REPO_ROOT}/.specify/templates/tasks-template.md`
       3. fallback: `{REPO_ROOT}/skills/spec-kit-tasks/assets/tasks-template.md`
   - For wiring/flow gaps, always include integration test tasks.

8. Validate outputs:

   - No branch changes or feature-creation actions occurred.
   - Updated artifacts remain structurally valid and internally consistent.
   - Task formatting stays strict: `- [ ] T### [P?] [US#?] Action with exact file path`.

9. Report reconciliation result:

   - Provide a Sync Impact Report with:
     - changed files (absolute paths)
     - summary of edits by artifact
     - new task IDs
     - skipped artifacts due to scope constraints
     - outstanding `NEEDS CLARIFICATION` markers (maximum 3)
     - confirmation that constitution constraints were respected
   - Recommend next step based on gates (`spec-kit-plan`, `spec-kit-tasks`, or `spec-kit-implement`).

Context: [Relevant spec/plan/tasks excerpt or summary] Decision Needed: [Single-sentence decision] Suggested Answers:

Option	Answer	Implications
A	[Option A]	[Impact]
B	[Option B]	[Impact]
C	[Option C]	[Impact]
Custom	Provide your own	[How it changes scope]

Your choice: [Wait for user response]


6. 映射每个工件的影响范围：

   - `spec.md`：用户故事、验收标准、用户可见场景、边缘行为。
   - `plan.md`：架构/模块、路由/导航、集成契约、测试策略。
   - `tasks.md`：包含精确文件路径和执行顺序的修复工作。
   - 遵守范围约束，并明确标记跳过的工件。

7. 执行针对性编辑：

   - `spec.md`：
     - 仅更新受影响的章节。
     - 添加简洁的`Revisions`注释（时间戳 + 原因）。
   - `plan.md`：
     - 仅更新协调所需的章节。
     - 保留设计层面的细节；不要添加实现补丁说明。
   - `tasks.md`：
     - 若已存在，使用`NextID = max(T###) + 1`追加修复任务。
     - 保留现有阶段；当需要跨领域任务时，添加`Remediation: Gaps`（修复：缺口）阶段。
     - 若不存在，从以下位置创建一个以修复为核心的极简`tasks.md`：
       1. `{REPO_ROOT}/templates/tasks-template.md`
       2. `{REPO_ROOT}/.specify/templates/tasks-template.md`
       3. 备选：`{REPO_ROOT}/skills/spec-kit-tasks/assets/tasks-template.md`
   - 对于连接/流程缺口，务必包含集成测试任务。

8. 验证输出结果：

   - 未发生分支变更或功能创建操作。
   - 更新后的工件结构有效且内部一致。
   - 任务格式保持严格：`- [ ] T### [P?] [US#?] Action with exact file path`。

9. 报告协调结果：

   - 提供同步影响报告，包含：
     - 已修改文件（绝对路径）
     - 按工件分类的编辑摘要
     - 新任务ID
     - 因范围约束而跳过的工件
     - 未解决的`NEEDS CLARIFICATION`标记（最多3个）
     - 确认已遵守规约约束
   - 根据阶段门推荐下一步操作（`spec-kit-plan`、`spec-kit-tasks`或`spec-kit-implement`）。

Output

输出结果

Updated reconciliation artifacts (
```
spec.md
```
,
```
plan.md
```
, and/or
```
tasks.md
```
) in the active feature directory.
New remediation tasks ready for execution.
Sync Impact Report for traceability.

活跃功能目录中已更新的协调工件（
```
spec.md
```
、
```
plan.md
```
和/或
```
tasks.md
```
）。
可执行的新修复任务。
用于追溯的同步影响报告。

Key Rules

核心规则

Keep reconciliation incremental and focused on stated gaps.
Prefer appending over rewriting existing artifacts.
Never reorder existing task IDs.
Do not silently expand feature scope beyond the gap report and answered clarifications.

保持协调工作的增量性，聚焦于已明确的缺口。
优先追加内容而非重写现有工件。
绝不重新排序现有任务ID。
不得在缺口报告和已澄清内容之外，擅自扩大功能范围。

Common Mistakes

常见错误

Running reconcile without a concrete gap report.
Rewriting whole artifacts instead of targeted updates.
Creating a new feature branch for remediation work.
Adding vague remediation tasks without exact file paths or acceptance intent.
Ignoring constitution MUST constraints while patching artifacts.

未提供具体缺口报告就运行协调功能。
重写整个工件而非进行针对性更新。
为修复工作创建新功能分支。
添加模糊的修复任务，未包含精确文件路径或验收意图。
在修补工件时忽略规约的MUST级约束。

References

参考资料

```
scripts/check-prerequisites.sh
```
```
references/spec-kit-workflow.dot
```

https://github.com/github/spec-kit/issues/1063

https://github.com/user-attachments/files/23166782/reconcile.md

```
scripts/check-prerequisites.sh
```
```
references/spec-kit-workflow.dot
```

https://github.com/github/spec-kit/issues/1063

https://github.com/user-attachments/files/23166782/reconcile.md