Specification Archiving

Archives completed change proposals and merges their spec deltas into the living specification documentation.

Quick Start

Archiving involves two main operations:

• Move change folder to archive with timestamp

• Merge spec deltas into living specs (ADDED/MODIFIED/REMOVED operations)

Critical rule: Verify all tasks are complete before archiving. Archiving signifies deployment and completion.

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

Step 1: Verify implementation is complete

Before archiving, confirm all work is done:

# Check for IMPLEMENTED marker

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

# Review tasks

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

# Check git status for uncommitted work

git status

Ask the user:

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

Understand what will be merged:

# List all spec delta files

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

# 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

Step 3: Create timestamped archive directory

# Create archive with today's date

TIMESTAMP=$(date +%Y-%m-%d)

mkdir -p spec/archive/${TIMESTAMP}-{change-id}

Example:

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

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

Step 4: Merge ADDED requirements into living specs

For each ## ADDED Requirements section:

Process:

• Locate the target living spec file

• Append the new requirements to the end of the file

• Maintain proper markdown formatting

Example:

Source (spec/changes/add-user-auth/specs/authentication/spec-delta.md):

## 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 user submits login form

THEN system creates session

Target (spec/specs/authentication/spec.md):

# Append to living spec

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 user submits login form

THEN system creates session

EOF

Step 5: Merge MODIFIED requirements into living specs

For each ## MODIFIED Requirements section:

Process:

• Locate the existing requirement in the living spec

• Replace the ENTIRE requirement block (including all scenarios)

• Use the complete updated text from the delta

Example using sed:

# Find and replace requirement block

# This is conceptual - actual implementation depends on structure

# First, identify the line range of the old requirement

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

# 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)

# Delete old requirement

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

# Insert new requirement at same position

# (Extract from delta and insert)

Manual approach (recommended for safety):

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

Step 6: Merge REMOVED requirements into living specs

For each ## REMOVED Requirements section:

Process:

• Locate the requirement in the living spec

• Delete the entire requirement block

• Add a comment documenting the removal

Example:

# 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 with sed

Pattern:

<!-- Removed 2025-10-26: User must use email-based password reset -->

~~### Requirement: SMS Password Reset~~

Step 7: Move change folder to archive

After all deltas are merged:

# Move entire change folder to archive

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

Verify move succeeded:

# Check archive exists

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

# Check changes directory is clean

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

Step 8: Validate living spec structure

After merging, validate the living specs are well-formed:

# Check requirement format

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

# Check scenario format

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

# 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

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

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

REMOVED Operation

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

Best Practices

Pattern 1: Verify Before Moving

Always verify delta merges before moving to archive:

# After merging, check diff

git diff spec/specs/

# Review changes

git diff spec/specs/authentication/spec.md

# If correct, commit

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 entire changes, not individual files:

Good:

# Move complete change folder

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

Bad:

# Don't cherry-pick files

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

# (leaves orphaned files)

Pattern 3: Archive Preservation

The archive is a historical record. Never modify archived files:

❌ Don't: Edit files in spec/archive/

✓ Do: Treat archive as read-only history

Pattern 4: Git Commit Strategy

Recommended commit workflow:

# 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"

# Commit 2: Archive change

git add spec/archive/ spec/changes/

git commit -m "Archive add-user-auth change"

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).

Common Patterns

Pattern 1: Simple Addition

Change adds 1 new requirement → Append to spec → Archive

Pattern 2: Behavioral Change

Change modifies 1 requirement → Replace in spec → Archive

Pattern 3: Deprecation

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

Pattern 4: Feature with Multiple Requirements

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

Troubleshooting

Issue: Merge conflict (requirement exists in living spec)

Solution:

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

Issue: Can't find requirement to modify/remove

Solution:

1. Search by partial name: grep -i "login" spec/specs/**/*.md

2. Check if already removed

3. Check if in different capability file

Issue: Living spec has formatting errors after merge

Solution:

1. Fix formatting manually

2. Re-run validation: grep -n "###" spec/specs/**/*.md

3. Ensure consistent heading levels

Reference Materials

• MERGE_LOGIC.md - Detailed merge operation rules

Token budget: This SKILL.md is approximately 480 lines, under the 500-line recommended limit.