Skip to main content

​
Overview

The /sdd-archive command finalizes a completed change by merging delta specs into the main specs (source of truth) and moving the change folder to the archive. This closes the SDD cycle.
Only run this command after successful verification. The change should be code-complete and tested.

​
Usage

/sdd-archive [change-name]
​
change-name
string
Optional. The change to archive. If omitted, archives the most recent verified change.

​
What It Does

​
1. Validates Readiness

Checks prerequisites:
  • ✓ Verification report exists?
  • ✓ Verification status is PASS or PASS WITH WARNINGS?
  • ✓ No CRITICAL issues?
  • ✓ All MUST/SHALL requirements met?

​
2. Merges Delta Specs

Syncs change specs into main specs:
Copies new spec files to main specs directory:
changes/add-csv-export/specs/api/csv-export.md
                             ↓
specs/api/csv-export.md

​
3. Moves to Archive

Relocates the change folder with timestamp: 
openspec/changes/add-dark-mode/
              ↓
openspec/changes/archive/2024-03-04-add-dark-mode/
Archive preserves:
  • Proposal
  • Exploration
  • Specs (delta)
  • Design
  • Tasks
  • Verification report

​
4. Generates Archive Report

Creates a summary:
  • Change name and date
  • Specs merged
  • Files affected
  • Audit trail reference

​
Example Output

​
Successful Archive

/sdd-archive
Output: 
## Archiving change: add-dark-mode

### Pre-Archive Validation
✓ Verification report exists
✓ Status: PASS WITH WARNINGS
✓ No CRITICAL issues
✓ All MUST/SHALL requirements met
✓ Ready to archive

---

## Merging Delta Specs

### ADDED Specs

Copying new spec files to main specs...

✓ specs/ui/theme-toggle.md
  - 3 requirements added
  - 7 scenarios added
  
✓ specs/core/theme-system.md
  - 4 requirements added
  - 9 scenarios added

### MODIFIED Specs

Updating existing spec files...

✓ specs/ui/layout.md
  - Updated requirement: "Layout SHOULD support theme variants"
  - Added scenario: "Layout applies theme class to root element"

### REMOVED Specs
None

---

## Moving to Archive

Relocating change folder...
openspec/changes/add-dark-mode/ ↓ openspec/changes/archive/2024-03-04-add-dark-mode/ 

✓ Moved successfully

---

## Archive Summary

**Change**: add-dark-mode
**Completed**: 2024-03-04
**Specs Merged**: 3 files (2 added, 1 modified)
**Files Affected**: 5 implementation files

### Source of Truth Updated
Main specs now reflect the current system state including dark mode support.

### Audit Trail
Full change history preserved in:
`openspec/changes/archive/2024-03-04-add-dark-mode/`

Includes:
- proposal.md - Original intent and scope
- exploration.md - Codebase analysis
- specs/ - Delta specifications
- design.md - Technical approach
- tasks.md - Implementation checklist
- verification-report.md - Quality validation

---

✅ Archive complete. Change closed successfully.

The specs directory is now the source of truth for the current system.

​
Archive with Warnings

## Archiving change: refactor-auth

### Pre-Archive Validation
✓ Verification report exists
⚠️  Status: PASS WITH WARNINGS
✓ No CRITICAL issues
⚠️  1 WARNING: TODO comment in auth-service.ts
✓ All MUST/SHALL requirements met

---

⚠️  Warning Found

The verification report contains 1 WARNING:
- TODO comment: "Add rate limiting to login endpoint"

This doesn't block archiving, but consider:
1. Creating a follow-up issue/change for this TODO
2. Or removing the TODO if not planned

Proceed with archive? (yes/no)
User types: yes 
---

## Merging Delta Specs

### REMOVED Specs

⚠️  Destructive changes detected!

The following specs will be REMOVED:
- specs/auth/session-cookies.md (replaced by JWT approach)

This will DELETE 237 lines including:
- 5 requirements
- 12 scenarios

Confirm deletion? (yes/no)
User types: yes 
✓ Removed specs/auth/session-cookies.md

### ADDED Specs

✓ specs/auth/jwt-tokens.md
  - 6 requirements added
  - 14 scenarios added

---

## Moving to Archive

✓ Moved to openspec/changes/archive/2024-03-04-refactor-auth/

---

✅ Archive complete with warnings addressed.

​
Archive Structure

The archive preserves complete change history: 
openspec/changes/archive/
├── 2024-03-04-add-dark-mode/
│   ├── proposal.md
│   ├── exploration.md
│   ├── specs/
│   │   ├── ui/theme-toggle.md
│   │   └── core/theme-system.md
│   ├── design.md
│   ├── tasks.md
│   └── verification-report.md
├── 2024-03-01-fix-auth-bug/
│   └── ...
└── 2024-02-28-add-csv-export/
    └── ...

​
Delta Spec Merging

The archiver intelligently merges specs:

​
ADDED Requirements

Change spec: 
## ADDED Requirements

### Requirement: CSV Export
The system SHALL support exporting data to CSV format.
Main spec after merge: 
## Requirements

### Requirement: JSON Export
{existing content}

### Requirement: CSV Export
The system SHALL support exporting data to CSV format.

​
MODIFIED Requirements

Change spec: 
## MODIFIED Requirements

### Requirement: Data Export
The system SHALL support multiple export formats.
(Previously: The system SHALL support JSON export.)
Main spec after merge: 
### Requirement: Data Export
The system SHALL support multiple export formats.

​
REMOVED Requirements

Change spec: 
## REMOVED Requirements

### Requirement: CSV Email Delivery
{content that's being removed}
Main spec after merge: 
{Section deleted, asks for confirmation first}

​
When to Use

After Verification

Run after /sdd-verify passes successfully

Change Complete

All code written, tested, and reviewed

Before Deployment

Close the change before deploying to production

Cycle Completion

Final step in the SDD workflow
Don’t archive if:
  • Verification has CRITICAL issues
  • Tests are failing
  • MUST/SHALL requirements not met
  • Code review pending

​
Archive Checklist

Before archiving, confirm:
  • /sdd-verify run successfully
  • Status is PASS or PASS WITH WARNINGS
  • No CRITICAL issues
  • All tests passing
  • All tasks marked done
  • Code reviewed (if team process)
  • No TODOs (or documented as follow-up)
  • Ready to deploy
  • Delta specs reflect actual changes
  • No placeholder content
  • Scenarios match implementation
  • README updated if needed
  • API docs updated if needed
  • Migration guide written if needed

​
Rollback After Archive

If you need to revert an archived change:
1

Find archive

cd openspec/changes/archive/2024-03-04-add-dark-mode/
2

Read rollback plan

cat proposal.md
# See "Rollback Plan" section
3

Revert code changes

Use git to revert commits or manually undo changes
4

Revert spec changes

Manually undo spec merges (ADDED → delete, MODIFIED → restore previous)

​
Spec Sync Behavior

How specs are synced:
Change SpecMain SpecAction
ADDED new fileDoesn’t existCopy file to main specs
ADDED sectionFile existsAppend section to file
MODIFIED sectionExistsReplace section in file
REMOVED sectionExistsDelete section (with warning)
REMOVED fileExistsDelete file (with confirmation)

​
Archive Reports

The archive report includes: 
# Archive Report: add-dark-mode

Date: 2024-03-04

## Change Summary
- **Intent**: Add user-toggleable dark mode
- **Complexity**: Medium (2-3 days)
- **Risk Level**: Medium

## Implementation
- **Tasks Completed**: 9/9
- **Files Modified**: 5
- **Tests Added**: 5
- **Lines Changed**: +387 / -12

## Specs Synced
- **Added**: 2 files (11 requirements, 16 scenarios)
- **Modified**: 1 file (1 requirement updated)
- **Removed**: 0 files

## Verification
- **Status**: PASS WITH WARNINGS
- **Tests**: 52 passing
- **Coverage**: 89%
- **Warnings**: 1 (TODO comment)

## Archive Location
openspec/changes/archive/2024-03-04-add-dark-mode/

## Next Steps
Specs now reflect current system state. Archive preserved for audit trail.

Build docs developers (and LLMs) love

Get started for freeTalk to us