File-Based TODO Tracking Skill

Overview

The todos/ directory contains a file-based tracking system for managing code review feedback, technical debt, feature requests, and work items. TODOs are organized by branch, with each branch having its own subdirectory. Each TODO is a markdown file with YAML frontmatter and structured sections.

This skill should be used when:

• •Creating new TODOs from findings or feedback
• •Managing TODO lifecycle (pending → ready → complete)
• •Triaging pending items for approval
• •Converting PR comments or code findings into tracked work
• •Updating work logs during TODO execution

Directory Structure

TODOs are organized by git branch:

todos/
├── feature-auth/           # Branch: alice/feature-auth
│   ├── 001-pending-p1-fix-login.md
│   └── 002-ready-p2-add-tests.md
└── bugfix-query/           # Branch: bob/bugfix-query
    └── 001-ready-p1-optimize-sql.md

Branch suffix extraction:

• •alice/feature-auth → feature-auth/
• •bugfix-query → bugfix-query/
• •main → Warns user to create a feature branch

Key principle: Each branch is an isolated unit of work with its own sequential issue IDs (001, 002, 003...).

File Naming Convention

TODO files follow this naming pattern:

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

Components:

• •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

Examples:

001-pending-p1-fix-auth-bug.md
002-ready-p2-optimize-database-query.md
005-complete-p3-add-type-hints.md

File Structure

Each TODO is a markdown file with YAML frontmatter and structured sections. Use the template at assets/todo-template.md as a starting point when creating new TODOs.

Required sections:

• •Problem Statement - What is broken, missing, or needs improvement?
• •Findings - Investigation results, root cause, key discoveries
• •Proposed Solutions - Options with pros/cons, effort, risk
• •Acceptance Criteria - Testable checklist items
• •Work Log - Chronological record with date, actions, learnings

YAML frontmatter fields:

---
status: ready # pending | ready | complete
priority: p1 # p1 | p2 | p3
issue_id: "002"
tags: [security, api, code-review]
dependencies: ["001"] # Issue IDs this is blocked by
---

Common Workflows

Branch Detection

Before any TODO operation, detect the current branch and set up the TODO directory:

# Get branch suffix (alice/feature-auth → feature-auth)
branch_suffix=$(git branch --show-current | sed 's|.*/||')
todo_dir="todos/$branch_suffix"

# Warn if on main branch
if [ "$branch_suffix" = "main" ] || [ "$branch_suffix" = "master" ]; then
    echo "⚠️ Warning: You're on the $branch_suffix branch."
    echo "TODOs should typically be associated with feature branches."
    # Offer to create a new branch or continue anyway
fi

# Ensure directory exists
mkdir -p "$todo_dir"

Creating a New TODO

1. •

   Set up branch directory and determine next issue ID:

   bash

   branch_suffix=$(git branch --show-current | sed 's|.*/||')
   todo_dir="todos/$branch_suffix"
   mkdir -p "$todo_dir"
   next_id=$(ls "$todo_dir"/ 2>/dev/null | grep -o '^[0-9]\+' | sort -n | tail -1 | awk '{printf "%03d", $1+1}')
   [ -z "$next_id" ] && next_id="001"
   

2. •

   Copy template:

   bash

   cp ~/.claude/skills/file-todos/assets/todo-template.md "$todo_dir/{NEXT_ID}-pending-{priority}-{description}.md"
   

3. •

   Fill required sections:

   • •Problem Statement
   • •Findings (if from investigation)
   • •Proposed Solutions
   • •Acceptance Criteria
   • •Initial Work Log entry
4. •

   Add relevant tags for filtering

When to create a TODO:

• •Requires more than 15-20 minutes of work
• •Needs research, planning, or multiple approaches
• •Has dependencies on other work
• •Requires approval or prioritization
• •Part of larger feature or refactor

When to act immediately instead:

• •Issue is trivial (< 15 minutes)
• •Complete context available now
• •No planning needed
• •Simple fix with obvious solution

Triaging Pending Items

Use /triage command or manually:

1. •Set up branch directory:
   bash

   branch_suffix=$(git branch --show-current | sed 's|.*/||')
   todo_dir="todos/$branch_suffix"
   

2. •List pending items: ls "$todo_dir"/*-pending-*.md
3. •For each TODO:
   • •Read Problem Statement and Findings
   • •Review Proposed Solutions
   • •Make decision: approve, defer, or modify priority
4. •Update approved TODOs:
   • •Rename file: pending → ready
   • •Update frontmatter: status: ready
   • •Fill "Recommended Action" section
5. •Deferred TODOs stay in pending status

Managing Dependencies

Dependencies are tracked within the same branch only (no cross-branch dependencies).

Track dependencies:

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

Check what blocks a TODO:

branch_suffix=$(git branch --show-current | sed 's|.*/||')
grep "^dependencies:" "todos/$branch_suffix"/003-*.md

Find what a TODO blocks:

branch_suffix=$(git branch --show-current | sed 's|.*/||')
grep -l 'dependencies:.*"002"' "todos/$branch_suffix"/*.md

Completing a TODO

1. •Verify all acceptance criteria checked off
2. •Update Work Log with final session
3. •Rename file: ready → complete
4. •Update frontmatter: status: complete
5. •Check for unblocked work
6. •Commit with issue reference

Integration with Commands

Quick Reference

Setup (run before any TODO operation):

branch_suffix=$(git branch --show-current | sed 's|.*/||')
todo_dir="todos/$branch_suffix"
mkdir -p "$todo_dir"

Finding work (current branch):

# List highest priority unblocked work
ls "$todo_dir"/*-ready-p1-*.md

# List pending items needing triage
ls "$todo_dir"/*-pending-*.md

# Find next issue ID for this branch
next_id=$(ls "$todo_dir"/ 2>/dev/null | grep -o '^[0-9]\+' | sort -n | tail -1 | awk '{printf "%03d", $1+1}')
[ -z "$next_id" ] && next_id="001"

# Count by status (current branch)
for status in pending ready complete; do
  echo "$status: $(ls -1 "$todo_dir"/*-$status-*.md 2>/dev/null | wc -l)"
done

Searching (current branch):

# Search by tag
grep -l "tags:.*security" "$todo_dir"/*.md

# Search by priority
ls "$todo_dir"/*-p1-*.md

# Full-text search
grep -r "user_id" "$todo_dir"/

Searching (all branches):

# Find all pending TODOs across branches
find todos -name "*-pending-*.md"

# Search all branches by tag
grep -r "tags:.*security" todos/

# List all branch directories
ls -d todos/*/

Key Distinctions

File-todos system (this skill):

• •Markdown files in todos/<branch>/ directories
• •Branch-based organization (one directory per feature branch)
• •Development/project tracking
• •Standalone markdown files with YAML frontmatter
• •Used by humans and Claude Code agents

TodoWrite tool:

• •In-memory task tracking during agent sessions
• •Temporary tracking for single conversation
• •Not persisted to disk
• •Different from this file-based system