Initial commit
This commit is contained in:
Zhongwei Li
184
skills/cyberarian/references/archiving-criteria.md
Normal file
184
skills/cyberarian/references/archiving-criteria.md
Normal file
@@ -0,0 +1,184 @@
|
||||
# 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:
|
||||
```yaml
|
||||
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:
|
||||
|
||||
```yaml
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
# 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`)
|
||||
Reference in New Issue
Block a user