spec-update

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spec Update

核心原则

Core Principles

同目录原则：update 文档必须放在原 plan.md 的同一目录下，禁止创建新目录
不归档原则：更新完成后不归档，保留在原目录以便后续更新
编号递增：update-001.md → update-002.md → update-003.md（三位数，不跳号）
严格遵循方案：只实现 update-xxx.md 定义的修改，不添加方案之外的内容
回归测试必须通过：新增测试 + 修改测试 + 原有功能回归测试全部通过

Same Directory Principle: Update documents must be placed in the same directory as the original plan.md; creating new directories is prohibited
Non-Archiving Principle: Do not archive after the update is completed; keep it in the original directory for future updates
Incremental Numbering: update-001.md → update-002.md → update-003.md (three digits, no skipping numbers)
Strictly Follow the Plan: Only implement the modifications defined in update-xxx.md; do not add content beyond the plan
Regression Tests Must Pass: All new tests + modified tests + regression tests for original features must pass

用户确认（必须执行）

User Confirmation (Mandatory)

在以下两个节点必须使用

AskUserQuestion

工具：

节点 1 — 更新方案确认（创建 update-xxx.md 后）：

python

AskUserQuestion(
    questions=[{
        "question": "update-xxx.md 已创建完成，更新方案是否可以开始执行？",
        "header": "确认方案",
        "multiSelect": false,
        "options": [
            {
                "label": "确认，开始执行",
                "description": "更新方案正确，可以开始实现"
            },
            {
                "label": "需要修改",
                "description": "更新方案需要调整，请说明修改要求"
            }
        ]
    }]
)

节点 2 — 审查报告确认（生成 update-xxx-review.md 后）：

python

AskUserQuestion(
    questions=[{
        "question": "update-xxx-review.md 已创建完成，审查结果是否通过？",
        "header": "确认审查",
        "multiSelect": false,
        "options": [
            {
                "label": "审查通过",
                "description": "更新实现符合要求，审查通过"
            },
            {
                "label": "需要修复",
                "description": "存在问题需要修复，请说明问题"
            }
        ]
    }]
)

响应处理：选择确认选项 → 继续；选择修改/修复或"Other" → 根据用户反馈调整后重新确认。

Use the

AskUserQuestion

tool must be used at the following two nodes:

Node 1 — Update Plan Confirmation (after creating update-xxx.md):

python

AskUserQuestion(
    questions=[{
        "question": "update-xxx.md has been created, can we start executing the update plan?",
        "header": "Confirm Plan",
        "multiSelect": false,
        "options": [
            {
                "label": "Confirm, start execution",
                "description": "The update plan is correct, can start implementation"
            },
            {
                "label": "Need modification",
                "description": "The update plan needs adjustment, please specify modification requirements"
            }
        ]
    }]
)

Node 2 — Review Report Confirmation (after generating update-xxx-review.md):

python

AskUserQuestion(
    questions=[{
        "question": "update-xxx-review.md has been created, is the review result approved?",
        "header": "Confirm Review",
        "multiSelect": false,
        "options": [
            {
                "label": "Review approved",
                "description": "The update implementation meets requirements, review passed"
            },
            {
                "label": "Need fixes",
                "description": "There are issues that need to be fixed, please specify the problems"
            }
        ]
    }]
)

Response handling: Select the confirmation option → proceed; select modification/fix or "Other" → adjust according to user feedback and re-confirm.

文档模板

Document Templates

update-xxx.md 模板：见 references/update-template.md（含 frontmatter 字段说明）
update-xxx-summary.md 模板：见 references/summary-template.md（含 frontmatter 字段说明）

update-xxx.md template: See references/update-template.md (includes frontmatter field descriptions)
update-xxx-summary.md template: See references/summary-template.md (includes frontmatter field descriptions)

工作流程

Workflow

确认原 Spec 目录：找到目录，确认
```
plan.md
```
和
```
summary.md
```
都存在。若缺少 summary.md，先用 spec-execute 完成原功能
确定更新编号：检查目录下已有的
```
update-*.md
```
，确定下一个编号
创建 update-xxx.md：参照 references/update-template.md，在同一目录创建
等待用户确认：使用
```
AskUserQuestion
```
工具（节点 1）
检索历史经验：调用
```
/exp-search <关键词>
```
创建任务清单：根据 update-xxx.md 的"实现步骤"章节创建
按方案实现更新：严格遵循方案，不修改方案之外的代码
编写/更新测试：新增测试 + 修改测试 + 回归测试
运行测试验证：全部通过才能继续
创建 update-xxx-summary.md：参照 references/summary-template.md，应用 Obsidian 格式：
```
[[plan|设计方案]]
```
双链、
```
> [!success]
```
/
```
> [!warning]
```
Callout、
```
#spec/更新
```
标签
使用 spec-review 审查：生成 update-xxx-review.md
等待用户确认审查报告：使用
```
AskUserQuestion
```
工具（节点 2），完成后不归档

Confirm Original Spec Directory: Locate the directory and confirm that both
```
plan.md
```
and
```
summary.md
```
exist. If summary.md is missing, first complete the original feature using spec-execute
Determine Update Number: Check existing
```
update-*.md
```
in the directory to determine the next number
Create update-xxx.md: Refer to references/update-template.md and create it in the same directory
Wait for User Confirmation: Use the
```
AskUserQuestion
```
tool (Node 1)
Retrieve Historical Experience: Call
```
/exp-search <keywords>
```
Create Task List: Create based on the "Implementation Steps" section of update-xxx.md
Implement Update According to Plan: Strictly follow the plan; do not modify code beyond the plan
Write/Update Tests: New tests + modified tests + regression tests
Run Test Verification: Proceed only after all tests pass
Create update-xxx-summary.md: Refer to references/summary-template.md, apply Obsidian format:
```
[[plan|Design Plan]]
```
double links,
```
> [!success]
```
/
```
> [!warning]
```
Callout,
```
#spec/更新
```
tag
Review with spec-review: Generate update-xxx-review.md
Wait for User Confirmation on Review Report: Use the
```
AskUserQuestion
```
tool (Node 2), do not archive after completion

错误处理

Error Handling

场景	解决方案
原 Spec 目录不存在	确认路径；若为新功能，用 spec-write + spec-execute
缺少 summary.md	先用 spec-execute 完成原功能
回归测试失败	分析原因 → 修复回归代码 → 重新测试 → 全部通过后才能继续

Scenario	Solution
Original Spec directory does not exist	Confirm the path; if it is a new feature, use spec-write + spec-execute
Missing summary.md	First complete the original feature using spec-execute
Regression test fails	Analyze the cause → fix the regression code → retest → proceed only after all tests pass

后续动作

Follow-up Actions

完成更新后：

调用
```
/exp-reflect
```
进行经验反思
如有经验沉淀，更新 summary 添加经验引用
不归档，保留在原目录

After completing the update:

Call
```
/exp-reflect
```
for experience reflection
If there is experience precipitation, update the summary to add experience references
Do not archive, keep it in the original directory