gh-slamb2k-mad-skills-dev-flow/skills/cyberarian/references/archiving-criteria.md

Document Archiving Criteria

Documents are automatically archived based on their category, status, and age. This ensures the active workspace remains focused on current, relevant documentation.

Archiving Philosophy

Goals:

• Keep active directories focused on current work
• Preserve historical context in archive
• Automate routine maintenance while allowing manual control where needed
• Make archiving decisions deterministic and transparent

Non-goals:

• Deleting documents (everything is preserved)
• Aggressive archiving that loses important context
• One-size-fits-all rules (categories have different lifecycles)

Category-Specific Rules

specs/ - Specifications

Auto-archive: Yes
Criteria: Status is complete AND >90 days since last_updated

Rationale: Specs are valuable reference material even after implementation. 90 days allows for iteration, rollout, and bug fixes before archiving.

Manual override: Set archivable_after date in frontmatter to defer archiving.

Example scenarios:

• ✅ Archive: Feature spec marked complete 100 days ago
• ❌ Skip: Active spec being refined
• ❌ Skip: Complete spec only 30 days old (still in rollout phase)

analysis/ - Investigation Outputs

Auto-archive: Yes
Criteria: Status is complete AND >60 days since last_updated

Rationale: Analysis documents are point-in-time investigations. Once the work is done and changes are implemented, they have less ongoing value. 60 days allows for follow-up work.

Manual override: Set archivable_after to keep important analyses active longer.

Example scenarios:

• ✅ Archive: Bug investigation completed 70 days ago
• ✅ Archive: Performance analysis from 2 months ago
• ❌ Skip: Ongoing investigation (status: active or draft)

plans/ - Implementation Plans

Auto-archive: Yes
Criteria: Status is complete AND >30 days since last_updated

Rationale: Plans become stale quickly. Once implementation is done, plans are primarily historical. 30 days accounts for plan execution and retrospective.

Manual override: Set archivable_after for long-running initiatives.

Example scenarios:

• ✅ Archive: Migration plan completed 45 days ago
• ✅ Archive: Sprint plan from last month (status: complete)
• ❌ Skip: Ongoing multi-phase plan (status: active)
• ❌ Skip: Just-completed plan (20 days old)

ai_docs/ - Reference Materials

Auto-archive: No
Manual archiving only

Rationale: Reference materials (SDKs, API docs, repo context) are meant to be persistent. These inform Claude Code's understanding and should only be archived manually when truly obsolete.

When to manually archive:

• SDK documentation for deprecated versions
• API references for sunset APIs
• Repository context for archived projects

Example scenarios:

• ❌ Auto-archive: Never, regardless of age or status
• ✅ Manual: Move OAuth 1.0 docs when OAuth 2.0 is fully adopted
• ✅ Manual: Archive legacy API docs after migration complete

templates/ - Reusable Templates

Auto-archive: No
Templates never auto-archive

Rationale: Templates are meant to be reused indefinitely. They don't have a lifecycle in the same way as other documents.

When to manually archive:

• Deprecated templates that should no longer be used
• Templates replaced by improved versions

Best practice: Instead of archiving, update templates in place or clearly mark as deprecated in the template itself.

Archive Structure

Archived documents are moved to archive/ while preserving their category:

archive/
├── specs/
│   └── oauth2-migration-spec.md
├── analysis/
│   └── auth-perf-analysis.md
└── plans/
    └── q3-migration-plan.md

This structure:

• Maintains categorical organization
• Allows easy browsing of archived content
• Prevents mixing of categories in archive

Manual Archiving

To manually archive a document:

1. Move it to archive/<category>/
2. Update metadata:

   status: archived
   archived_date: YYYY-MM-DD
   archive_reason: "Manual archiving: <reason>"
   

3. Run scripts/index_docs.py to update the index

Preventing Auto-Archiving

To prevent a document from being auto-archived:

Option 1: Keep status as active or draft
Option 2: Set explicit archivable_after date in frontmatter:

archivable_after: 2025-12-31  # Don't archive until after this date

This is useful for:

• Long-running projects
• Reference specs that should remain active
• Documents with ongoing relevance despite completion

Running the Archiving Script

# Dry run to see what would be archived
python scripts/archive_docs.py --dry-run

# Actually archive documents
python scripts/archive_docs.py

# Archive and update index
python scripts/archive_docs.py && python scripts/index_docs.py

Best practice: Run archiving periodically (weekly or monthly) as part of documentation maintenance.

Retrieval from Archive

Archived documents are not deleted and can be retrieved by:

1. Browsing: Navigate to archive/<category>/
2. Search: Use grep or file search tools
3. Index: Check INDEX.md which includes archived documents
4. Unarchiving: Move document back to its category and update status

To unarchive a document:

# Move file back
mv archive/specs/old-spec.md specs/

# Update metadata
# Change status from 'archived' to 'active' or appropriate status
# Remove archived_date and archive_reason fields

Monitoring

The archiving script provides a summary:

Archive Summary:
  Documents scanned: 45
  Documents archived: 3
  Documents skipped: 42
  Errors: 0

Keep an eye on:

• Unexpected archives: Documents archived sooner than expected
• Errors: Failed archiving operations
• Zero archives: May indicate metadata issues (e.g., status never set to complete)