Design Document Archival

Design Document Archival

Archives design documentation that is no longer relevant or has been superseded by newer documentation.

Overview

This skill safely archives design documents by updating their status, adding archival metadata and notices, updating cross-references, and optionally moving files to an archive directory. It ensures proper documentation lifecycle management and maintains documentation integrity.

Quick Start

Basic archival:

/​design-archive effect-type-registry old-cache-design.md

With replacement:

/​design-archive effect-type-registry cache-v1.md --replacement=cache-optimization.md

Move to archive directory:

/​design-archive design-doc-system obsolete-patterns.md --move

Parameters

Required

• module: Module name
• doc: Document filename to archive

Optional

• reason: Archival reason (superseded, deprecated, obsolete, completed)
• replacement: Path to replacement doc (required if superseded)
• move: Move to _archive directory (default: false)

Workflow

High-level archival process:

1. Parse parameters to identify document and archival reason
2. Load design.config.json to verify module and get paths
3. Validate archival (doc exists, not already archived, replacement exists if superseded)
4. Update frontmatter to set status="archived" and add archival metadata
5. Add archival notice prominently at top of document
6. Update cross-references in other docs (frontmatter, content links, CLAUDE.md)
7. Optionally move to _archive directory if --move specified
8. Report summary of all actions taken

For detailed implementation steps, see supporting documentation below.

Supporting Documentation

When you need detailed information, load the appropriate supporting file:

For Detailed Workflow

See instructions.md for:

• Complete step-by-step archival workflow
• Frontmatter update algorithms for each archival reason
• Archive notice templates and insertion logic
• Cross-reference finding and updating procedures
• Archive directory structure and file moving
• Validation requirements and error handling
• Advanced features (batch archival, audit, restoration)

Load when: Performing archival or need implementation details

For Archival Reasons

See archival-reasons.md for:

• Superseded: When to use, requirements, best practices
• Deprecated: Deprecation timelines, transition period handling
• Obsolete: Historical preservation guidelines
• Completed: Outcome types and final documentation links
• Choosing the right reason for different scenarios

Load when: Need to determine appropriate archival reason or understand requirements

For Reference Updates

See reference-updates.md for:

• Finding references (design docs, CLAUDE.md, indirect)
• Update strategies (replace, note, remove, move)
• Batch update procedures
• Validation checklist

Load when: Working with cross-references or batch archival

For Usage Examples

See examples.md for:

• Superseded by new doc
• Deprecated feature with timeline
• Move to archive directory
• Completed project
• Multiple references to update
• Error scenarios (already archived, replacement not found)

Load when: User needs examples or clarification

Error Handling

Document Not Found

ERROR: Design document not found
Module: {module}, Document: {doc}
Expected: .claude/​design/​{module}/​{doc}

Already Archived

INFO: Document is already archived ({date})
Reason: {reason}
No action needed.

Replacement Not Found

ERROR: Replacement document not found
Specified: {replacement}
Fix: Create replacement doc first or correct the path

Integration

Works well with:

• /​design-review - Identify candidates for archival
• /​design-validate - Validate before and after archival
• /​design-update - Update replacement docs
• /​design-init - Create replacement before archiving

Success Criteria

A successful archival:

• ✅ Document status changed to "archived"
• ✅ Archival notice added to document
• ✅ Archival metadata complete and accurate
• ✅ All cross-references updated
• ✅ CLAUDE.md references handled
• ✅ Clear summary provided
• ✅ Replacement exists and is adequate (if superseded)