Skip to main content

TODO.md Management Guide

Purpose: This guide explains how to maintain TODO.md and keep it clean and focused.

Core Principles​

Keep TODO.md Clean​

TODO.md contains ONLY:

  • ✅ Pending / in-progress tasks
  • ✅ Important notes and instructions
  • ✅ Technical debt items
  • ✅ Testing requirements (open items only)
  • ✅ Known issues (open only)

TODO.md does NOT contain:

  • ❌ Completed features (these live in docs/features/)
  • ❌ Detailed implementation history
  • ❌ Completed task checklists

Instructions for Working with TODO.md​

This file contains ONLY:

  • ✅ Pending / in-progress tasks
  • ✅ Important notes and instructions
  • ✅ Technical debt items (open only)
  • ✅ Testing requirements (open items only)
  • ✅ Known issues (open only)

This file does NOT contain:

  • ❌ Completed features (these live in docs/features/)
  • ❌ Detailed implementation history
  • ❌ Completed task checklists
  • ❌ Introductory/instructional text (see docs/developer/README.md for development guidelines)

When Completing a Task​

  1. Check off the item: [ ] → [x]
  2. If it's a major feature completion:
    • Move implementation details to the corresponding feature doc in docs/features/
    • Remove the detailed task list from TODO.md
    • Keep only a status reference (e.g., "Status: ✅ Complete — See docs/features/feature-name.md")
  3. Update "Last Updated" date at the top

When an Entire Category is Complete​

  1. Move the category to docs/features/ as a new feature doc
  2. Remove it from TODO.md entirely
  3. Keep only a status reference if needed for context

When Adding New Tasks​

  1. Add to appropriate section:
    • Testing → Testing section
    • Technical debt → Technical Debt section
    • New features → Appropriate feature section
  2. Use clear, actionable descriptions
  3. Link to related docs when helpful

When Updating Feature Status​

  • Completed features: Remove detailed task lists, keep only status reference
  • In-progress features: Keep open items, remove completed sub-items
  • Future features: Keep planning items, remove completed implementation details

File Organization​

Completed Features​

All completed features are documented in docs/features/:

  • Each feature has its own markdown file
  • Files include: implementation details, API endpoints, frontend components, testing approach
  • Status is clearly marked (✅ Complete, 🟡 Partial, etc.)

TODO.md Structure​

# TODO.md
- Instructions (keep this section)
- Frontend-Backend Synchronization (mandatory rules)
- Testing (open items only)
- Technical Debt (open items only)
- Feature sections (only open/in-progress items)
- Known Issues (open only)
- Future considerations

Examples​

✅ Good: Clean TODO Entry​

## Feature Name
**Status:** ✅ Complete — See `docs/features/feature-name.md` for full documentation

### Open Items
- [ ] Future enhancement: Add X feature
- [ ] Future: Improve Y performance

❌ Bad: Cluttered TODO Entry​

## Feature Name
- [x] Task 1 - Complete: Did X, Y, Z
- [x] Task 2 - Complete: Implemented A, B, C
- [x] Task 3 - Complete: Added tests for D, E, F
- [x] Task 4 - Complete: Frontend UI for G, H, I
- [ ] Future: Add J feature

✅ Good: Moved to Feature Doc​

The detailed implementation is in docs/features/feature-name.md:

  • Implementation details
  • API endpoints
  • Frontend components
  • Test coverage
  • All completed tasks

TODO.md only has:

## Feature Name
**Status:** ✅ Complete — See `docs/features/feature-name.md`
- [ ] Future: Enhancement X

Maintenance Checklist​

When updating TODO.md:

  • Remove all completed detailed task lists
  • Move completed feature details to docs/features/
  • Keep only open/in-progress items
  • Update "Last Updated" date
  • Ensure status references point to feature docs
  • Remove redundant information
  • Keep instructions section at the top
  • Feature Documentation: docs/features/ - All completed features
  • Project Planning: docs/project/ - Planning and management docs
  • Main README: README.md - Project overview and coding standards

Remember: TODO.md is a working document for what's left to do, not a history of what's been done. Keep it focused and actionable.