Docs Cleanup

Documentation Cleanup

This skill focuses on finalizing documentation after large implementations, following the project's documentation protocol and archive rules.

When to Use

Use this skill for large changes (Size >= M) or when documentation was created during implementation:

• Features with draft/plan/intent documents
• Breaking changes with migration documentation
• Architecture decisions recorded in intent/
• Research findings in survey/

For small changes (Size < M), use post-implementation alone and skip this skill.

Documentation Cleanup Workflow

1. Review Documentation State

Check what documentation exists:

_docs/
├── draft/(feature)/          # May exist from pre-implementation
├── plan/(feature)/           # Should exist for Size >= M
├── intent/(feature)/         # Should exist for design decisions
├── survey/(feature)/         # May exist for research-heavy features
├── guide/(feature)/          # Need to create for implemented features
└── reference/(feature)/      # Need to create for API docs

2. Update or Create Guide Documentation

Location: _docs/guide/(feature-name)/

Create user-facing documentation:

---
title: "Feature X Usage Guide"
status: active
draft_status: n/a
created_at: YYYY-MM-DD
updated_at: YYYY-MM-DD
references: ["../../intent/feature-x/decision.md"]
related_issues: []
related_prs: []
---

## Overview
What this feature does and when to use it.

## Quick Start
Basic usage examples.

## Configuration
How to configure the feature.

## Best Practices
Project-specific recommendations.

## Troubleshooting
Common issues and solutions.

Key Points:

• Focus on "how to use" not "how it works"
• Link to reference/ for detailed specs
• Include practical examples

3. Update or Create Reference Documentation

Location: _docs/reference/(feature-name)/

Create API/technical documentation:

---
title: "Feature X API Reference"
status: active
draft_status: n/a
created_at: YYYY-MM-DD
updated_at: YYYY-MM-DD
references: ["../../guide/feature-x/usage.md"]
related_issues: []
related_prs: []
---

## API Overview
High-level API description.

## Classes/Methods
Detailed specifications:
- Parameters
- Return values
- Exceptions

## Data Models
Schema definitions.

## Examples
Code examples with explanations.

Key Points:

• Dictionary-style reference
• Only document implemented features
• Link to guide/ for usage examples

4. Archive Temporary Documents

Important: Follow the strict archive rules:

Archive Checklist

• Intent document is approved/merged
• Archive target has valid front-matter
• Source directory cleanup completed
• References updated in intent document

Archive Process

1. Verify intent approval

   • Check PR status
   • Link to approved intent in PR description

2. Move to archives

   # Move draft, plan, survey (if intent is approved)
   _docs/draft/(feature)/     → _docs/archives/draft-(feature)/
   _docs/plan/(feature)/      → _docs/archives/plan-(feature)/
   _docs/survey/(feature)/    → _docs/archives/survey-(feature)/
   

3. Keep front-matter intact

   • Preserve all metadata
   • Update status: superseded if applicable

4. Clean up source directories

   • Remove from original locations
   • No duplicates allowed

5. Update references

   # In intent document, add:
   references: [
     "../../archives/draft-feature-x/",
     "../../archives/plan-feature-x/"
   ]
   

Forbidden Actions

• ❌ Archive draft/plan/survey without intent approval
• ❌ Keep originals after archiving
• ❌ Archive without updating references

5. Update TODO.md

• Mark documentation tasks as completed
• Add links to created/updated documents
• Note any follow-up documentation debt

6. Final Verification

Run documentation checks:

# If available, run linting
npm run lint:docs

# Verify all links
npm run check-links

# Validate front-matter
npm run validate-frontmatter

Document Type-Specific Cleanup

Draft Cleanup

• Review content for value
• Either: Archive (if intent approved) or Delete (if obsolete)
• Update updated_at if keeping for future reference

Plan Cleanup

• Ensure plan matches final implementation
• Mark status: superseded if outdated
• Move to archives after intent approval

Intent Cleanup

• Verify all design decisions are recorded
• Add consequences and lessons learned
• Keep active (don't archive intent documents)

Survey Cleanup

• Archive after research is incorporated
• Link from intent or plan documents
• Mark status: superseded when no longer needed

Lifecycle Summary

Implementation Complete
        ↓
   [Create/Update]
   guide/(feature)/
   reference/(feature)/
        ↓
   [Verify Intent]
   Is intent approved?
        ↓
    Yes      No
     ↓        ↓
   [Archive]  [Keep/Update]
   draft/     draft/plan/
   plan/      until approved
   survey/
        ↓
   [Finalize]
   Update TODO.md
   Run validation

Deliverables

After implementation:

• Guide document created/updated in _docs/guide/(feature)/
• Reference document created/updated in _docs/reference/(feature)/
• Temporary documents archived (if intent approved)
• Source directories cleaned up
• References cross-linked between documents
• TODO.md updated with document links
• Validation passed (lint, links, front-matter)

Integration with Post-Implementation

Use both skills together:

1. post-implementation: Update TODO.md, communicate changes
2. docs-cleanup: Finalize documentation hierarchy and archives

References

• _docs/standards/documentation_guidelines.md - Full documentation guidelines
• _docs/standards/documentation_operations.md - Archive rules and lifecycle
• .codex/skills/docs-prep/SKILL.md - Pre-implementation documentation

Converted and distributed by TomeVault — claim your Tome and manage your conversions.