File-Based Todo Tracking

Overview

The todos/ directory contains a file-based tracking system for managing code review feedback, technical debt, feature requests, and work items. Each todo is a markdown file with YAML frontmatter and structured sections.

File Naming Convention

{issue_id}-{status}-{priority}-{description}.md

• issue_id: Sequential number (001, 002, 003...) -- never reused
• status: pending (needs triage), ready (approved), complete (done)
• priority: p1 (critical), p2 (important), p3 (nice-to-have)
• description: kebab-case, brief description

File Structure

Each todo is a markdown file with YAML frontmatter and structured sections. Use the template at todo-template.md as a starting point.

Required sections: Problem Statement, Findings, Proposed Solutions, Recommended Action, Acceptance Criteria, Work Log

Optional sections: Technical Details, Resources, Notes

YAML frontmatter fields:

---
status: ready              # pending | ready | complete
priority: p1              # p1 | p2 | p3
issue_id: "002"
tags: [rails, performance, database]
dependencies: ["001"]     # Issue IDs this is blocked by
---

Common Workflows

Creating a New Todo

1. Determine next issue ID: ls todos/ | grep -o '^[0-9]\+' | sort -n | tail -1
2. Copy template: cp assets/todo-template.md todos/{NEXT_ID}-pending-{priority}-{description}.md
3. Fill required sections: Problem Statement, Findings, Proposed Solutions, Acceptance Criteria, initial Work Log entry
4. Determine status: pending (needs triage) or ready (pre-approved)
5. Add relevant tags for filtering

Create a todo when: work requires >15 minutes, needs research/planning, has dependencies, requires approval, or is part of a larger effort.

Act immediately when: issue is trivial (<15 min), complete context is available, no planning needed, or user requests immediate action.

Triaging Pending Items

1. List pending items: ls todos/*-pending-*.md
2. For each: read Problem Statement and Findings, review Proposed Solutions, decide (approve, defer, or modify priority)
3. Update approved todos: rename file status to ready, update frontmatter, fill "Recommended Action" section

Use /triage for interactive approval workflow.

Managing Dependencies

dependencies: ["002", "005"]  # Blocked by issues 002 and 005
dependencies: []               # No blockers

Check blockers: grep "^dependencies:" todos/003-*.md Find dependents: grep -l 'dependencies:.*"002"' todos/*.md

Updating Work Logs

Always add a work log entry when working on a todo:

### YYYY-MM-DD - Session Title

**By:** Claude Code / Developer Name

**Actions:**
- Specific changes made (include file:line references)
- Commands executed, tests run, investigation results

**Learnings:**
- What worked / what didn't, patterns discovered

Completing a Todo

1. Verify all acceptance criteria checked off
2. Update Work Log with final session and results
3. Rename file status to complete, update frontmatter
4. Check for unblocked work: grep -l 'dependencies:.*"002"' todos/*-ready-*.md

Integration with Development Workflows

Key Distinctions

Recommended combination: File-todos for detailed documentation, TaskList for execution tracking.