Back to Details

sdd-archive

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

sdd-archive

sdd-archive

Closes a completed SDD change and persists an archive report.
Triggers: 
/sdd-archive <change-name>
, archive change, finalize sdd cycle, close change, sdd archive
关闭已完成的SDD变更并持久化归档报告。
触发方式：
/sdd-archive <变更名称>
、archive change、finalize sdd cycle、close change、sdd archive

Purpose

目的

Archiving is the final step of the SDD cycle. It validates completeness, saves a closure record, and updates the project memory layer. It is irreversible — I confirm with the user before executing.
归档是SDD周期的最终步骤。它会验证完整性、保存关闭记录并更新项目内存层。此操作不可逆——执行前我会与用户确认。

Process

流程

Skill Resolution

Skill解析

When the orchestrator launches this sub-agent, it resolves the skill path using:
1. .claude/skills/sdd-archive/SKILL.md     (project-local — highest priority)
2. ~/.claude/skills/sdd-archive/SKILL.md   (global catalog — fallback)
Project-local skills override the global catalog. See 
docs/SKILL-RESOLUTION.md
for the full algorithm.
当编排器（orchestrator）启动此子代理（sub-agent）时，它会通过以下路径解析Skill：
1. .claude/skills/sdd-archive/SKILL.md     （项目本地——优先级最高）
2. ~/.claude/skills/sdd-archive/SKILL.md   （全局目录——备用）
项目本地Skill会覆盖全局目录。完整算法请参阅
docs/SKILL-RESOLUTION.md
。

Step 1 — Verify it is archivable

步骤1——验证是否可归档

Completeness Check

完整性检查

Before reading the verify report, I check for required SDD artifacts in engram. Artifact exists if 
mem_search
returns results.
CRITICAL artifacts (block with no proceed option): proposal, tasks
WARNING artifacts (present two-option prompt): design, specs
Check order:
  1. Check CRITICAL artifacts first. If any are absent:
CRITICAL — Cannot archive "[change-name]"

The following artifacts are required for a valid SDD cycle but are missing:
  - proposal   (required — CRITICAL)
  - tasks      (required — CRITICAL)

Return and complete the missing phases before archiving.
No proceed option is available.
List only the artifacts that are actually absent. Halt immediately. Do NOT evaluate WARNING artifacts.
  1. If CRITICAL passes, check WARNING artifacts. If any are absent:
WARNING — Incomplete cycle detected for "[change-name]"

The following artifacts are missing:
  - design     (recommended — WARNING)
  - specs      (recommended — WARNING)

Choose:
  1. Return and complete the missing phases (/sdd-spec, /sdd-design)
  2. Archive anyway — I acknowledge these phases were intentionally skipped

Reply 1 or 2:
List only the artifacts that are actually absent. Wait for the user to reply:
  • Option 1 selected: halt. The user returns to complete the missing phases.
  • Option 2 selected: record the skipped phases (for use in Step 4 closure) and continue.
  1. If all CRITICAL and WARNING artifacts are present: produce no output and continue immediately.
Note: exploration is explicitly excluded from this check. Its absence MUST NOT trigger any CRITICAL or WARNING output.
I read the verify report artifact if it exists:
  • mem_search(query: "sdd/{change-name}/verify-report")
    → 
    mem_get_observation(id)
    .
If there are unresolved CRITICAL issues:
No archiving allowed.

The verification report has [N] critical issues:
- [issue 1]
- [issue 2]

Resolve the issues and run /sdd-verify again before archiving.
If there is no verification report, I inform the user and ask whether to proceed anyway.
User-docs review checkbox (non-blocking):
After reading the verify-report (if it exists), surface the user-docs review item status:
User docs review checkbox: [CHECKED / UNCHECKED / ABSENT]
  • CHECKED: verify-report contains 
    [x] Review user docs
    — good
  • UNCHECKED: verify-report contains 
    [ ] Review user docs
    — remind the user to check if this change affects user-facing docs
  • ABSENT: the checkbox is not in the verify-report — no action needed (older changes pre-date this requirement)
This check is non-blocking — the archive operation continues regardless of the checkbox state.
在读取验证报告之前，我会检查engram中是否存在所需的SDD工件。若
mem_search
返回结果，则表示工件存在。
关键工件（无继续选项，直接阻止）：proposal、tasks
警告工件（提供双选项提示）：design、specs
检查顺序：
  1. 首先检查关键工件。若有缺失：
CRITICAL — 无法归档"[变更名称]"

以下是有效SDD周期所需但缺失的工件：
  - proposal  （必填——CRITICAL）
  - tasks     （必填——CRITICAL）

请返回并完成缺失阶段后再进行归档。
无继续选项。
仅列出实际缺失的工件。立即终止流程。不要评估警告工件。
  1. 若关键工件检查通过，检查警告工件。若有缺失：
WARNING — 检测到"[变更名称]"的周期不完整

以下工件缺失：
  - design    （推荐——WARNING）
  - specs     （推荐——WARNING）

请选择：
  1. 返回并完成缺失阶段（/sdd-spec、/sdd-design）
  2. 仍进行归档——我确认已有意跳过这些阶段

请回复1或2：
仅列出实际缺失的工件。等待用户回复：
  • 选择选项1：终止流程。用户返回完成缺失阶段。
  • 选择选项2：记录跳过的阶段（用于步骤4的关闭记录）并继续。
  1. 若所有关键和警告工件均存在：不输出任何内容，立即继续。
注意：探索阶段明确排除在此检查之外。其缺失不得触发任何CRITICAL或WARNING输出。
若验证报告工件存在，我会读取它：
  • mem_search(query: "sdd/{change-name}/verify-report")
    → 
    mem_get_observation(id)
    。
若存在未解决的CRITICAL问题：
不允许归档。

验证报告存在[N]个关键问题：
- [问题1]
- [问题2]

请解决这些问题并重新运行/sdd-verify后再进行归档。
若不存在验证报告，我会告知用户并询问是否仍要继续。
用户文档审核复选框（非阻塞）：
读取验证报告（若存在）后，显示用户文档审核项的状态：
用户文档审核复选框：[已勾选/未勾选/不存在]
  • 已勾选：验证报告包含
    [x] Review user docs
    ——状态良好
  • 未勾选：验证报告包含
    [ ] Review user docs
    ——提醒用户若此变更影响面向用户的文档，请进行审核
  • 不存在：验证报告中无此复选框——无需操作（旧变更早于此要求）
此检查为非阻塞——无论复选框状态如何，归档操作都会继续。

Step 2 — Confirm with the user

步骤2——与用户确认

Do you confirm archiving the change "[change-name]"?

This will perform the following actions:
1. Save an archive closure report to engram
2. Update ai-context/ with decisions from this change

[PASS WITH WARNINGS — warnings were left unresolved]
[or: Verification: PASS]

Continue? [y/n]
您确认要归档变更"[变更名称]"吗？

此操作将执行以下动作：
1. 将归档关闭报告保存至engram
2. 使用此变更的决策更新ai-context/

[带警告通过——警告未解决]
[或：验证：通过]

是否继续？[y/n]

Step 3 — Update feature files (optional)

步骤3——更新功能文件（可选）

If 
ai-context/features/
exists and any domain specs were produced for this change, check whether the delta specs introduced new business rules, invariants, or gotchas that should be reflected in the permanent feature files.
For each affected domain:
  • If a matching feature file exists: append new business rules or invariants to the appropriate sections
  • If no matching feature file exists: skip — feature files are created by 
    /codebase-teach
    or 
    /memory-init
    , not by archive
This step is non-blocking. If 
ai-context/features/
does not exist, skip entirely.
若
ai-context/features/
存在且为此变更生成了任何领域规范，检查增量规范是否引入了应反映在永久功能文件中的新业务规则、不变量或注意事项。
对于每个受影响的领域：
  • 若存在匹配的功能文件：将新业务规则或不变量追加至相应章节
  • 若不存在匹配的功能文件：跳过——功能文件由
    /codebase-teach
    或
    /memory-init
    创建，而非归档流程
此步骤为非阻塞。若
ai-context/features/
不存在，则完全跳过。

Step 4 — Save closure to engram

步骤4——将关闭记录保存至engram

Call 
mem_save
with 
topic_key: sdd/{change-name}/archive-report
, 
type: architecture
, content = compact summary:
Archived: {change-name}. Dates: {start} -> {close}. Summary: {1-2 sentences}.
Specs domains: {domain list}. Skipped phases: {list or "none"}.
If Engram MCP is not reachable: skip persistence. Return closure content inline only.
调用
mem_save
，参数
topic_key: sdd/{change-name}/archive-report
，
type: architecture
，内容为精简摘要：
已归档：{变更名称}。日期：{开始时间} -> {结束时间}。摘要：{1-2句话}。
规范领域：{领域列表}。跳过阶段：{列表或"无"}。
若无法连接Engram MCP：跳过持久化操作。仅返回内联关闭内容。

Step 5 — Auto-update memory

步骤5——自动更新内存

After the archive is complete, I automatically update 
ai-context/
with the decisions and changes from this cycle.
Process:
  1. Read 
    ~/.claude/skills/memory-manage/SKILL.md
  2. Execute the 
    /memory-manage
    process in "update" mode inline, using the archived change as session context:
    • Change name: 
      <change-name>
    • Artifacts: proposal, specs, design, tasks (from engram)
  3. Report the result
Non-blocking error handling:
  • On success: report in the output: 
    Memory updated: ai-context/ files refreshed with decisions from "[change-name]".
  • On failure (skill not found, write error, any other issue): report a warning and continue: 
    Warning: Memory update failed — [reason]. Archive completed successfully.
Suggestion: Run /memory-manage (update mode) manually to update ai-context/.
The archive is always considered successful regardless of the memory-update outcome.
Final output:
Change "[change-name]" successfully archived.

Memory: [updated | failed — reason]
归档完成后，我会自动使用此周期的决策和变更更新
ai-context/
。
流程：
  1. 读取
    ~/.claude/skills/memory-manage/SKILL.md
  2. 以内联方式在"更新"模式下执行
    /memory-manage
    流程，使用已归档的变更作为会话上下文：
    • 变更名称：
      <变更名称>
    • 工件：proposal、specs、design、tasks（来自engram）
  3. 报告结果
非阻塞错误处理：
  • 成功时：在输出中报告： 
    内存已更新：ai-context/ 文件已使用"[变更名称]"的决策刷新。
  • 失败时（未找到Skill、写入错误或其他问题）：报告警告并继续： 
    警告：内存更新失败——[原因]。归档已成功完成。
建议：手动运行/memory-manage（更新模式）以更新ai-context/。
无论内存更新结果如何，归档均视为成功。
最终输出：
变更"[变更名称]"已成功归档。

内存状态：[已更新 | 失败——原因]

Output to Orchestrator

向编排器输出

json
{
  "status": "ok|warning|failed",
  "summary": "Change [name] archived. Memory: [updated|failed|skipped].",
  "artifacts": ["engram:sdd/{change-name}/archive-report"],
  "next_recommended": [],
  "risks": []
}
json
{
  "status": "ok|warning|failed",
  "summary": "变更[name]已归档。内存状态：[已更新|失败|跳过]。",
  "artifacts": ["engram:sdd/{change-name}/archive-report"],
  "next_recommended": [],
  "risks": []
}

Rules

规则

  • NEVER archive with unresolved CRITICAL issues
  • ALWAYS confirm with the user before executing (it is irreversible)
  • CRITICAL artifacts (
    proposal
    , 
    tasks
    ) MUST block with no proceed option — the completeness check MUST run before the verify-report is read
  • WARNING artifacts (
    design
    , 
    specs
    ) MUST always offer option 2 (acknowledge and proceed) — they MUST NOT silently block
  • 绝不要在存在未解决CRITICAL问题时进行归档
  • 执行前必须与用户确认（操作不可逆）
  • 关键工件（
    proposal
    、
    tasks
    ）必须直接阻止，无继续选项——完整性检查必须在读取验证报告前执行
  • 警告工件（
    design
    、
    specs
    ）必须始终提供选项2（确认并继续）——不得静默阻止