Specification Archiving

Archive completed change proposals and merge their specification differences into permanent specification documents.

Quick Start

Archiving includes two main operations:

Move the change directory to a timestamped archive location
Merge specification differences into permanent specifications (ADDED/MODIFIED/REMOVED)

Key Rule: Verify all tasks are completed before archiving. Archiving means the change has been deployed and completed.

Workflow

Copy this checklist to track progress:

Archiving Progress:
- [ ] Step 1: Verify implementation completion
- [ ] Step 2: Review specification differences to be merged
- [ ] Step 3: Create a timestamped archive directory
- [ ] Step 4: Merge ADDED requirements into permanent specifications
- [ ] Step 5: Merge MODIFIED requirements into permanent specifications
- [ ] Step 6: Merge REMOVED requirements into permanent specifications
- [ ] Step 7: Move the change directory to archive
- [ ] Step 8: Verify permanent specification structure

Step 1: Verify Implementation Completion

Confirm all work is completed before archiving:

bash

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

# View tasks
cat spec/changes/{change-id}/tasks.json

# Check uncommitted work using git
git status

Ask User:

markdown

Have all tasks been completed and passed testing?
Has this change been deployed to production?
Proceed with archiving?

Step 2: Review Specification Differences to Be Merged

Understand what needs to be merged:

bash

# List all specification difference files
find spec/changes/{change-id}/specs -name "*.md" -type f

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

Identify:

Which capabilities are affected
Number of ADDED/MODIFIED/REMOVED requirements
Where these changes belong in the permanent specifications

Step 3: Create a Timestamped Archive Directory

bash

# Create archive directory with today's date
TIMESTAMP=$(date +%Y-%m-%d)
mkdir -p spec/archive/${TIMESTAMP}-{change-id}

Example:

bash

# For "add-user-auth" change archived on 2025-10-26
mkdir -p spec/archive/2025-10-26-add-user-auth

Step 4: Merge ADDED Requirements into Permanent Specifications

For each

## ADDED Requirements

section:

Process:

Locate the target permanent specification file
Append the new requirements to the end of the file
Maintain correct Markdown formatting

Example:

Source (

spec/changes/add-user-auth/specs/authentication/spec-delta.md

markdown

## ADDED Requirements

### Requirement: User Login
WHEN a user submits valid credentials,
the system SHALL authenticate the user and create a session.

#### Scenario: Successful Login
GIVEN valid credentials
WHEN the user submits the login form
THEN the system creates a session

Target (

spec/specs/authentication/spec.md

bash

# Append to permanent specification
cat >> spec/specs/authentication/spec.md << 'EOF'

### Requirement: User Login
WHEN a user submits valid credentials,
the system SHALL authenticate the user and create a session.

#### Scenario: Successful Login
GIVEN valid credentials
WHEN the user submits the login form
THEN the system creates a session
EOF

Step 5: Merge MODIFIED Requirements into Permanent Specifications

For each

## MODIFIED Requirements

section:

Process:

Locate the existing requirement in the permanent specification
Replace the entire requirement block (including all scenarios)
Use the complete updated text from the difference file

Example (using sed):

bash

# Find and replace requirement block
# This is a conceptual example - actual implementation depends on structure

# First, determine the start line of the old requirement
START_LINE=$(grep -n "### Requirement: User Login" spec/specs/authentication/spec.md | cut -d: -f1)

# Find the end position (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)

# Delete the old requirement
sed -i "${START_LINE},${END_LINE}d" spec/specs/authentication/spec.md

# Insert the new requirement at the same position
# (Extract from difference file and insert)

Manual Method (recommended for safety):

markdown

1. Open the permanent specification in an editor
2. Locate the target requirement by name
3. Delete the entire block (requirement + all scenarios)
4. Paste the updated requirement from the difference file in its place
5. Save

Step 6: Merge REMOVED Requirements into Permanent Specifications

For each

## REMOVED Requirements

section:

Process:

Locate the requirement in the permanent specification
Delete the entire requirement block
Add a comment to record the removal

Example:

bash

# Option 1: Delete with comment
# Manually edit spec/specs/authentication/spec.md

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

# Delete the requirement block manually or via sed

Pattern:

markdown

<!-- Removed 2025-10-26: Users must use email-based password reset -->
~~### Requirement: SMS Password Reset~~

Step 7: Move the Change Directory to Archive

After merging all differences:

bash

# Move the complete change directory to archive
mv spec/changes/{change-id} spec/archive/${TIMESTAMP}-{change-id}

Verify Successful Move:

bash

# Check if archive exists
ls -la spec/archive/${TIMESTAMP}-{change-id}

# Check if changes directory is clean
ls spec/changes/ | grep "{change-id}"  # Should return no results

Step 8: Verify Permanent Specification Structure

After merging, verify the integrity of the permanent specifications:

bash

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

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

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

Manual Review:

Open each modified specification file
Verify correct Markdown formatting
Check that requirement logic is consistent
Ensure no duplicate requirements exist

Merge Logic Reference

ADDED Operation

Action: Append to permanent specification
Location: End of file (before any footnotes/appendices)
Format: Copy requirements and all scenarios exactly as written

MODIFIED Operation

Action: Replace existing requirement
Location: Locate by requirement name, replace entire block
Format: Use complete updated text from difference file (no splicing, direct replacement)
Note: Old version is preserved in archive

REMOVED Operation

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

RENAMED Operation (Uncommon)

Action: Update requirement name, retain content
Location: Locate by old name, update to new name
Format: Only modify the title: ### Requirement: New Name
Note: MODIFIED is typically used more often

Best Practices

Pattern 1: Validate Before Moving

Always verify difference merging before moving to archive:

bash

# View differences after merging
git diff spec/specs/

# Review changes
git diff spec/specs/authentication/spec.md

# Commit if correct
git add spec/specs/
git commit -m "Merge spec deltas from add-user-auth"

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

Pattern 2: Atomic Archiving

Archive the entire change, not individual files:

Good:

bash

# Move complete change directory
mv spec/changes/add-user-auth spec/archive/2025-10-26-add-user-auth

Bad:

bash

# Don't pick individual files
mv spec/changes/add-user-auth/proposal.md spec/archive/
# (Leaves orphaned files)

Pattern 3: Archive Preservation

Archives are historical records. Never modify archived files:

markdown

❌ Don't: Edit spec/archive/
✓ Do: Treat archives as read-only history

Pattern 4: Git Commit Strategy

Recommended commit flow:

bash

# Commit 1: Merge differences
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
git add spec/archive/ spec/changes/
git commit -m "Archive add-user-auth change"

Advanced Topics

Complex Differences: See reference/MERGE_LOGIC.md

Conflict Resolution: If multiple changes modify the same requirement, manual merging is required.

Rollback Strategy: If archiving needs to be rolled back, reverse the process (move from archive back to changes, and remove merged content from permanent specifications).

Common Patterns

Pattern 1: Simple Addition

markdown

Change adds 1 requirement → Append to specification → Archive

Pattern 2: Behavior Change

markdown

Change modifies 1 requirement → Replace in specification → Archive

Pattern 3: Deprecation

markdown

Change removes 1 requirement → Delete and add comment → Archive

Pattern 4: Multi-Requirement Feature

markdown

Change adds 5 requirements across 2 specifications
→ Append to respective specifications
→ Verify all are merged
→ Archive

Anti-Patterns to Avoid

Don't:

Archive incomplete implementations
Merge differences before deployment
Modify archived files
Skip post-merge verification
Forget to git commit after merging specifications

Do:

Verify all tasks are completed before archiving
Merge differences carefully and completely
Treat archives as immutable history
Verify merged specification structure
Commit merged specifications before moving to archive

Troubleshooting

Issue: Merge Conflict (Requirement already exists in permanent specification)

Solution:

markdown

1. If same name but different content → Use MODIFIED mode
2. If truly different requirements → Rename one of them
3. If it's a duplication error → Select the correct version

Issue: Cannot find requirement to modify/remove

Solution:

markdown

1. Search by partial name: grep -i "login" spec/specs/**/*.md
2. Check if it was already removed
3. Check if it's located in another capability file

Issue: Permanent specification formatting is incorrect after merging

Solution:

markdown

1. Fix formatting manually
2. Re-run verification: grep -n "###" spec/specs/**/*.md
3. Ensure consistent heading levels

References

MERGE_LOGIC.md - Detailed merge operation rules

Token Budget: This SKILL.md is approximately 430 lines, below the recommended 500-line limit.

openspec-archiving-cn

NPX Install

Tags

SKILL.md Content (Chinese)

Specification Archiving

Quick Start

Workflow

Step 1: Verify Implementation Completion

Step 2: Review Specification Differences to Be Merged

Step 3: Create a Timestamped Archive Directory

Step 4: Merge ADDED Requirements into Permanent Specifications

Step 5: Merge MODIFIED Requirements into Permanent Specifications

Step 6: Merge REMOVED Requirements into Permanent Specifications

Step 7: Move the Change Directory to Archive

Step 8: Verify Permanent Specification Structure

Merge Logic Reference

ADDED Operation

MODIFIED Operation

REMOVED Operation

RENAMED Operation (Uncommon)

Best Practices

Pattern 1: Validate Before Moving

Pattern 2: Atomic Archiving

Pattern 3: Archive Preservation

Pattern 4: Git Commit Strategy

Advanced Topics

Common Patterns

Pattern 1: Simple Addition

Pattern 2: Behavior Change

Pattern 3: Deprecation

Pattern 4: Multi-Requirement Feature

Anti-Patterns to Avoid

Troubleshooting

Issue: Merge Conflict (Requirement already exists in permanent specification)

Issue: Cannot find requirement to modify/remove

Issue: Permanent specification formatting is incorrect after merging

References