Back to Details

openspec-archiving

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Specification Archiving

规范归档

Archives completed change proposals and merges their spec deltas into the living specification documentation.
归档已完成的变更提案，并将其规范增量合并到现行规范文档中。

Quick Start

快速入门

Archiving involves two main operations:
  1. Move change folder to archive with timestamp
  2. Merge spec deltas into living specs (ADDED/MODIFIED/REMOVED operations)
Critical rule: Verify all tasks are complete before archiving. Archiving signifies deployment and completion.
归档包含两个主要操作：
  1. 将变更文件夹移动到带时间戳的归档目录
  2. 将规范增量合并到现行规范中（包含ADDED/MODIFIED/REMOVED操作）
重要规则：归档前需验证所有任务已完成。归档意味着变更已部署并全部完成。

Workflow

工作流程

Copy this checklist and track progress:
Archive Progress:
- [ ] Step 1: Verify implementation is complete
- [ ] Step 2: Review spec deltas to merge
- [ ] Step 3: Create timestamped archive directory
- [ ] Step 4: Merge ADDED requirements into living specs
- [ ] Step 5: Merge MODIFIED requirements into living specs
- [ ] Step 6: Merge REMOVED requirements into living specs
- [ ] Step 7: Move change folder to archive
- [ ] Step 8: Validate living spec structure
复制以下检查清单并跟踪进度：
Archive Progress:
- [ ] Step 1: Verify implementation is complete
- [ ] Step 2: Review spec deltas to merge
- [ ] Step 3: Create timestamped archive directory
- [ ] Step 4: Merge ADDED requirements into living specs
- [ ] Step 5: Merge MODIFIED requirements into living specs
- [ ] Step 6: Merge REMOVED requirements into living specs
- [ ] Step 7: Move change folder to archive
- [ ] Step 8: Validate living spec structure

Step 1: Verify implementation is complete

步骤1：验证实施已完成

Before archiving, confirm all work is done:
bash
undefined
归档前，确认所有工作已完成：
bash
undefined

Check for IMPLEMENTED marker

Check for IMPLEMENTED marker

test -f spec/changes/{change-id}/IMPLEMENTED && echo "✓ Implemented" || echo "✗ Not implemented"
test -f spec/changes/{change-id}/IMPLEMENTED && echo "✓ Implemented" || echo "✗ Not implemented"

Review tasks

Review tasks

cat spec/changes/{change-id}/tasks.md
cat spec/changes/{change-id}/tasks.md

Check git status for uncommitted work

Check git status for uncommitted work

git status

**Ask the user**:
```markdown
Are all tasks complete and tested?
Has this change been deployed to production?
Should I proceed with archiving?
git status

**询问用户**：
```markdown
Are all tasks complete and tested?
Has this change been deployed to production?
Should I proceed with archiving?

Step 2: Review spec deltas to merge

步骤2：查看待合并的规范增量

Understand what will be merged:
bash
undefined
了解将要合并的内容：
bash
undefined

List all spec delta files

List all spec delta files

find spec/changes/{change-id}/specs -name "*.md" -type f
find spec/changes/{change-id}/specs -name "*.md" -type f

Read each delta

Read each delta

for file in spec/changes/{change-id}/specs/**/*.md; do echo "=== $file ===" cat "$file" done

**Identify**:
- Which capabilities are affected
- How many requirements are ADDED/MODIFIED/REMOVED
- Where in living specs these changes belong
for file in spec/changes/{change-id}/specs/**/*.md; do echo "=== $file ===" cat "$file" done

**确认内容**：
- 哪些功能模块会受影响
- 有多少需求会被新增/修改/移除
- 这些变更在现行规范中的对应位置

Step 3: Create timestamped archive directory

步骤3：创建带时间戳的归档目录

bash
undefined
bash
undefined

Create archive with today's date

Create archive with today's date

TIMESTAMP=$(date +%Y-%m-%d) mkdir -p spec/archive/${TIMESTAMP}-{change-id}

**Example**:
```bash
TIMESTAMP=$(date +%Y-%m-%d) mkdir -p spec/archive/${TIMESTAMP}-{change-id}

**示例**：
```bash

For change "add-user-auth" archived on Oct 26, 2025

For change "add-user-auth" archived on Oct 26, 2025

mkdir -p spec/archive/2025-10-26-add-user-auth
undefined
mkdir -p spec/archive/2025-10-26-add-user-auth
undefined

Step 4: Merge ADDED requirements into living specs

步骤4：将新增需求合并到现行规范

For each 
## ADDED Requirements
section:
Process:
  1. Locate the target living spec file
  2. Append the new requirements to the end of the file
  3. Maintain proper markdown formatting
Example:
Source (
spec/changes/add-user-auth/specs/authentication/spec-delta.md
):
markdown
undefined
针对每个
## ADDED Requirements
部分：
操作流程：
  1. 定位目标现行规范文件
  2. 将新需求追加到文件末尾
  3. 保持原有的Markdown格式
示例：
源文件 (
spec/changes/add-user-auth/specs/authentication/spec-delta.md
):
markdown
undefined

ADDED Requirements

ADDED Requirements

Requirement: User Login

Requirement: User Login

WHEN a user submits valid credentials, the system SHALL authenticate the user and create a session.
WHEN a user submits valid credentials, the system SHALL authenticate the user and create a session.

Scenario: Successful Login

Scenario: Successful Login

GIVEN valid credentials WHEN user submits login form THEN system creates session

**Target** (`spec/specs/authentication/spec.md`):
```bash
GIVEN valid credentials WHEN user submits login form THEN system creates session

**目标文件** (`spec/specs/authentication/spec.md`):
```bash

Append to living spec

Append to living spec

cat >> spec/specs/authentication/spec.md << 'EOF'
cat >> spec/specs/authentication/spec.md << 'EOF'

Requirement: User Login

Requirement: User Login

WHEN a user submits valid credentials, the system SHALL authenticate the user and create a session.
WHEN a user submits valid credentials, the system SHALL authenticate the user and create a session.

Scenario: Successful Login

Scenario: Successful Login

GIVEN valid credentials WHEN user submits login form THEN system creates session EOF
undefined
GIVEN valid credentials WHEN user submits login form THEN system creates session EOF
undefined

Step 5: Merge MODIFIED requirements into living specs

步骤5：将修改后的需求合并到现行规范

For each 
## MODIFIED Requirements
section:
Process:
  1. Locate the existing requirement in the living spec
  2. Replace the ENTIRE requirement block (including all scenarios)
  3. Use the complete updated text from the delta
Example using sed:
bash
undefined
针对每个
## MODIFIED Requirements
部分：
操作流程：
  1. 在现行规范中找到对应的现有需求
  2. 替换整个需求块（包括所有场景）
  3. 使用增量文件中的完整更新文本
使用sed的示例：
bash
undefined

Find and replace requirement block

Find and replace requirement block

This is conceptual - actual implementation depends on structure

This is conceptual - actual implementation depends on structure

First, identify the line range of the old requirement

First, identify the line range of the old requirement

START_LINE=$(grep -n "### Requirement: User Login" spec/specs/authentication/spec.md | cut -d: -f1)
START_LINE=$(grep -n "### Requirement: User Login" spec/specs/authentication/spec.md | cut -d: -f1)

Find the end (next requirement or end of file)

Find the end (next requirement or end of file)

END_LINE=$(tail -n +$((START_LINE + 1)) spec/specs/authentication/spec.md |
grep -n "^### Requirement:" | head -1 | cut -d: -f1)
END_LINE=$(tail -n +$((START_LINE + 1)) spec/specs/authentication/spec.md |
grep -n "^### Requirement:" | head -1 | cut -d: -f1)

Delete old requirement

Delete old requirement

sed -i "${START_LINE},${END_LINE}d" spec/specs/authentication/spec.md
sed -i "${START_LINE},${END_LINE}d" spec/specs/authentication/spec.md

Insert new requirement at same position

Insert new requirement at same position

(Extract from delta and insert)

(Extract from delta and insert)


**Manual approach** (recommended for safety):
```markdown
1. Open living spec in editor
2. Find the requirement by name
3. Delete entire block (requirement + all scenarios)
4. Paste updated requirement from delta
5. Save

**手动方法**（推荐用于确保安全）：
```markdown
1. 在编辑器中打开现行规范
2. 通过名称找到对应的需求
3. 删除整个需求块（需求+所有场景）
4. 粘贴增量文件中的更新后需求
5. 保存文件

Step 6: Merge REMOVED requirements into living specs

步骤6：将移除的需求合并到现行规范

For each 
## REMOVED Requirements
section:
Process:
  1. Locate the requirement in the living spec
  2. Delete the entire requirement block
  3. Add a comment documenting the removal
Example:
bash
undefined
针对每个
## REMOVED Requirements
部分：
操作流程：
  1. 在现行规范中找到对应的需求
  2. 删除整个需求块
  3. 添加一条注释记录移除信息
示例：
bash
undefined

Option 1: Delete with comment

Option 1: Delete with comment

Manually edit spec/specs/authentication/spec.md

Manually edit spec/specs/authentication/spec.md

Add deprecation comment

Add deprecation comment

echo "<!-- Requirement 'Legacy Password Reset' removed $(date +%Y-%m-%d) -->" >> spec/specs/authentication/spec.md
echo "<!-- Requirement 'Legacy Password Reset' removed $(date +%Y-%m-%d) -->" >> spec/specs/authentication/spec.md

Delete the requirement block manually or with sed

Delete the requirement block manually or with sed


**Pattern**:
```markdown
<!-- Removed 2025-10-26: User must use email-based password reset -->
~~### Requirement: SMS Password Reset~~

**格式示例**：
```markdown
<!-- Removed 2025-10-26: User must use email-based password reset -->
~~### Requirement: SMS Password Reset~~

Step 7: Move change folder to archive

步骤7：将变更文件夹移动到归档目录

After all deltas are merged:
bash
undefined
所有增量合并完成后：
bash
undefined

Move entire change folder to archive

Move entire change folder to archive

mv spec/changes/{change-id} spec/archive/${TIMESTAMP}-{change-id}

**Verify move succeeded**:
```bash
mv spec/changes/{change-id} spec/archive/${TIMESTAMP}-{change-id}

**验证移动是否成功**：
```bash

Check archive exists

Check archive exists

ls -la spec/archive/${TIMESTAMP}-{change-id}
ls -la spec/archive/${TIMESTAMP}-{change-id}

Check changes directory is clean

Check changes directory is clean

ls spec/changes/ | grep "{change-id}" # Should return nothing
undefined
ls spec/changes/ | grep "{change-id}" # Should return nothing
undefined

Step 8: Validate living spec structure

步骤8：验证现行规范结构

After merging, validate the living specs are well-formed:
bash
undefined
合并完成后，验证现行规范格式是否正确：
bash
undefined

Check requirement format

Check requirement format

grep -n "### Requirement:" spec/specs/**/*.md
grep -n "### Requirement:" spec/specs/**/*.md

Check scenario format

Check scenario format

grep -n "#### Scenario:" spec/specs/**/*.md
grep -n "#### Scenario:" spec/specs/**/*.md

Count requirements per spec

Count requirements per spec

for spec in spec/specs/**/spec.md; do count=$(grep -c "### Requirement:" "$spec") echo "$spec: $count requirements" done

**Manual review**:
- Open each modified spec file
- Verify markdown formatting is correct
- Check requirements flow logically
- Ensure no duplicate requirements exist
for spec in spec/specs/**/spec.md; do count=$(grep -c "### Requirement:" "$spec") echo "$spec: $count requirements" done

**手动检查**：
- 打开每个被修改的规范文件
- 验证Markdown格式是否正确
- 检查需求逻辑是否连贯
- 确保没有重复的需求

Merge Logic Reference

合并逻辑参考

ADDED Operation

新增操作

Action: Append to living spec
Location: End of file (before any footer/appendix)
Format: Copy requirement + all scenarios exactly as written
Action: Append to living spec
Location: End of file (before any footer/appendix)
Format: Copy requirement + all scenarios exactly as written

MODIFIED Operation

修改操作

Action: Replace existing requirement
Location: Find by requirement name, replace entire block
Format: Use complete updated text from delta (don't merge, replace)
Note: Old version is preserved in archive
Action: Replace existing requirement
Location: Find by requirement name, replace entire block
Format: Use complete updated text from delta (don't merge, replace)
Note: Old version is preserved in archive

REMOVED Operation

移除操作

Action: Delete requirement, add deprecation comment
Location: Find by requirement name
Format: Delete entire block, optionally add <!-- Removed YYYY-MM-DD: reason -->
Action: Delete requirement, add deprecation comment
Location: Find by requirement name
Format: Delete entire block, optionally add <!-- Removed YYYY-MM-DD: reason -->

RENAMED Operation (uncommon)

重命名操作（不常见）

Action: Update requirement name, keep content
Location: Find by old name, update to new name
Format: Just change the header: ### Requirement: NewName
Note: Typically use MODIFIED instead
Action: Update requirement name, keep content
Location: Find by old name, update to new name
Format: Just change the header: ### Requirement: NewName
Note: Typically use MODIFIED instead

Best Practices

最佳实践

Pattern 1: Verify Before Moving

模式1：移动前验证

Always verify delta merges before moving to archive:
bash
undefined
务必在移动到归档目录前验证增量合并结果：
bash
undefined

After merging, check diff

After merging, check diff

git diff spec/specs/
git diff spec/specs/

Review changes

Review changes

git diff spec/specs/authentication/spec.md
git diff spec/specs/authentication/spec.md

If correct, commit

If correct, commit

git add spec/specs/ git commit -m "Merge spec deltas from add-user-auth"
git add spec/specs/ git commit -m "Merge spec deltas from add-user-auth"

Then archive

Then archive

mv spec/changes/add-user-auth spec/archive/2025-10-26-add-user-auth
undefined
mv spec/changes/add-user-auth spec/archive/2025-10-26-add-user-auth
undefined

Pattern 2: Atomic Archiving

模式2：原子化归档

Archive entire changes, not individual files:
Good:
bash
undefined
归档完整的变更文件夹，而非单个文件：
正确做法：
bash
undefined

Move complete change folder

Move complete change folder

mv spec/changes/add-user-auth spec/archive/2025-10-26-add-user-auth

**Bad**:
```bash
mv spec/changes/add-user-auth spec/archive/2025-10-26-add-user-auth

**错误做法**：
```bash

Don't cherry-pick files

Don't cherry-pick files

mv spec/changes/add-user-auth/proposal.md spec/archive/
mv spec/changes/add-user-auth/proposal.md spec/archive/

(leaves orphaned files)

(leaves orphaned files)

undefined
undefined

Pattern 3: Archive Preservation

模式3：归档保存

The archive is a historical record. Never modify archived files:
markdown
❌ Don't: Edit files in spec/archive/
✓ Do: Treat archive as read-only history
归档是历史记录，切勿修改归档文件：
markdown
❌ 禁止：编辑spec/archive/中的文件
✓ 正确：将归档视为只读历史

Pattern 4: Git Commit Strategy

模式4：Git提交策略

Recommended commit workflow:
bash
undefined
推荐的提交流程：
bash
undefined

Commit 1: Merge deltas

Commit 1: Merge deltas

git add spec/specs/ git commit -m "Merge spec deltas from add-user-auth
  • Added User Login requirement
  • Modified Password Policy requirement
  • Removed Legacy Auth requirement"
git add spec/specs/ git commit -m "Merge spec deltas from add-user-auth
  • Added User Login requirement
  • Modified Password Policy requirement
  • Removed Legacy Auth requirement"

Commit 2: Archive change

Commit 2: Archive change

git add spec/archive/ spec/changes/ git commit -m "Archive add-user-auth change"
undefined
git add spec/archive/ spec/changes/ git commit -m "Archive add-user-auth change"
undefined

Advanced Topics

进阶主题

For complex deltas: See reference/MERGE_LOGIC.md
Conflict resolution: If multiple changes modified the same requirement, manual merge is required.
Rollback strategy: To rollback an archive, reverse the process (move from archive back to changes, remove merged content from living specs).
针对复杂增量：参考reference/MERGE_LOGIC.md
冲突解决：如果多个变更修改了同一个需求，需要手动合并。
回滚策略：要回滚归档，逆向执行流程即可（将文件从归档移回变更目录，从现行规范中移除已合并的内容）。

Common Patterns

常见模式

Pattern 1: Simple Addition

模式1：简单新增

markdown
Change adds 1 new requirement → Append to spec → Archive
markdown
Change adds 1 new requirement → Append to spec → Archive

Pattern 2: Behavioral Change

模式2：行为变更

markdown
Change modifies 1 requirement → Replace in spec → Archive
markdown
Change modifies 1 requirement → Replace in spec → Archive

Pattern 3: Deprecation

模式3：废弃

markdown
Change removes 1 requirement → Delete from spec with comment → Archive
markdown
Change removes 1 requirement → Delete from spec with comment → Archive

Pattern 4: Feature with Multiple Requirements

模式4：包含多个需求的功能

markdown
Change adds 5 requirements across 2 specs
→ Append each to respective spec
→ Verify all are merged
→ Archive
markdown
Change adds 5 requirements across 2 specs
→ Append each to respective spec
→ Verify all are merged
→ Archive

Anti-Patterns to Avoid

需避免的反模式

Don't:
  • Archive incomplete implementations
  • Merge deltas before deployment
  • Modify archived files
  • Skip validation after merging
  • Forget to git commit merged specs
Do:
  • Verify all tasks complete before archiving
  • Merge deltas carefully and completely
  • Treat archive as immutable history
  • Validate merged specs structure
  • Commit merged specs before archiving move
禁止：
  • 归档未完成的实现
  • 部署前合并增量
  • 修改归档文件
  • 合并后跳过验证
  • 忘记提交合并后的规范到Git
推荐：
  • 归档前验证所有任务已完成
  • 仔细完整地合并增量
  • 将归档视为不可变的历史
  • 验证合并后的规范结构
  • 移动归档前提交合并后的规范

Troubleshooting

故障排除

Issue: Merge conflict (requirement exists in living spec)

问题：合并冲突（现行规范中已存在该需求）

Solution:
markdown
1. If names match but content differs → Use MODIFIED pattern
2. If truly different requirements → Rename one
3. If duplicate by mistake → Use whichever is correct
解决方案：
markdown
1. 如果名称匹配但内容不同 → 使用修改模式
2. 如果确实是不同的需求 → 重命名其中一个
3. 如果是误重复的需求 → 使用正确的版本

Issue: Can't find requirement to modify/remove

问题：找不到要修改/移除的需求

Solution:
markdown
1. Search by partial name: grep -i "login" spec/specs/**/*.md
2. Check if already removed
3. Check if in different capability file
解决方案：
markdown
1. 按部分名称搜索：grep -i "login" spec/specs/**/*.md
2. 检查该需求是否已被移除
3. 检查是否在不同的功能文件中

Issue: Living spec has formatting errors after merge

问题：合并后现行规范出现格式错误

Solution:
markdown
1. Fix formatting manually
2. Re-run validation: grep -n "###" spec/specs/**/*.md
3. Ensure consistent heading levels
解决方案：
markdown
1. 手动修复格式
2. 重新运行验证：grep -n "###" spec/specs/**/*.md
3. 确保标题层级一致

Reference Materials

参考资料

  • MERGE_LOGIC.md - Detailed merge operation rules
Token budget: This SKILL.md is approximately 480 lines, under the 500-line recommended limit.
  • MERGE_LOGIC.md - 详细的合并操作规则
Token预算：本SKILL.md约480行，低于推荐的500行限制。