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

• Checking or managing dependencies

• Converting PR comments or code findings into tracked work

• Updating work logs during todo execution

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-mailer-test.md 002-ready-p1-fix-n-plus-1.md 005-complete-p2-refactor-csv.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 - Multiple options with pros/cons, effort, risk

• Recommended Action - Clear plan (filled during triage)

• Acceptance Criteria - Testable checklist items

• Work Log - Chronological record with date, actions, learnings

Optional sections:

• Technical Details - Affected files, related components, DB changes

• Resources - Links to errors, tests, PRs, documentation

• Notes - Additional context or decisions

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

To create a new todo from findings or feedback:

• Determine next issue ID: ls todos/ | grep -o '^[0-9]+' | sort -n | tail -1

• Copy template: cp assets/todo-template.md todos/{NEXT_ID}-pending-{priority}-{description}.md

• Edit and fill required sections:

• Problem Statement

• Findings (if from investigation)

• Proposed Solutions (multiple options)

• Acceptance Criteria

• Add initial Work Log entry

• Determine status: pending (needs triage) or ready (pre-approved)

• Add relevant tags for filtering

When to create a todo:

• Requires more than 15-20 minutes of work

• Needs research, planning, or multiple approaches considered

• Has dependencies on other work

• Requires manager approval or prioritization

• Part of larger feature or refactor

• Technical debt needing documentation

When to act immediately instead:

• Issue is trivial (< 15 minutes)

• Complete context available now

• No planning needed

• User explicitly requests immediate action

• Simple bug fix with obvious solution

Triaging Pending Items

To triage pending todos:

• List pending items: ls todos/-pending-.md

• For each todo:

• Read Problem Statement and Findings

• Review Proposed Solutions

• Make decision: approve, defer, or modify priority

• Update approved todos:

• Rename file: mv {file}-pending-{pri}-{desc}.md {file}-ready-{pri}-{desc}.md

• Update frontmatter: status: pending → status: ready

• Fill "Recommended Action" section with clear plan

• Adjust priority if different from initial assessment

• Deferred todos stay in pending status

Use slash command: /triage for interactive approval workflow

Managing Dependencies

To track dependencies:

dependencies: ["002", "005"] # This todo blocked by issues 002 and 005 dependencies: [] # No blockers - can work immediately

To check what blocks a todo:

grep "^dependencies:" todos/003-*.md

To find what a todo blocks:

grep -l 'dependencies:."002"' todos/.md

To verify blockers are complete before starting:

for dep in 001 002 003; do [ -f "todos/${dep}-complete-*.md" ] || echo "Issue $dep not complete" done

Updating Work Logs

When working on a todo, always add a work log entry:

YYYY-MM-DD - Session Title

By: Claude Code / Developer Name

Actions:

• Specific changes made (include file:line references)
• Commands executed
• Tests run
• Results of investigation

Learnings:

• What worked / what didn't
• Patterns discovered
• Key insights for future work

Work logs serve as:

• Historical record of investigation

• Documentation of approaches attempted

• Knowledge sharing for team

• Context for future similar work

Completing a Todo

To mark a todo as complete:

• Verify all acceptance criteria checked off

• Update Work Log with final session and results

• Rename file: mv {file}-ready-{pri}-{desc}.md {file}-complete-{pri}-{desc}.md

• Update frontmatter: status: ready → status: complete

• Check for unblocked work: grep -l 'dependencies:."002"' todos/-ready-*.md

• Commit with issue reference: feat: resolve issue 002

Integration with Development Workflows

Trigger Flow Tool

Code review /review → Findings → /triage → Todos Review agent + skill

PR comments /resolve_pr_parallel → Individual fixes → Todos gh CLI + skill

Code TODOs /resolve_todo_parallel → Fixes + Complex todos Agent + skill

Planning Brainstorm → Create todo → Work → Complete Skill

Feedback Discussion → Create todo → Triage → Work Skill + slash

Quick Reference Commands

Finding work:

List highest priority unblocked work

grep -l 'dependencies: []' todos/-ready-p1-.md

List all pending items needing triage

ls todos/-pending-.md

Find next issue ID

ls todos/ | grep -o '^[0-9]+' | sort -n | tail -1 | awk '{printf "%03d", $1+1}'

Count by status

for status in pending ready complete; do echo "$status: $(ls -1 todos/-$status-.md 2>/dev/null | wc -l)" done

Dependency management:

What blocks this todo?

grep "^dependencies:" todos/003-*.md

What does this todo block?

grep -l 'dependencies:."002"' todos/.md

Searching:

Search by tag

grep -l "tags:.rails" todos/.md

Search by priority

ls todos/-p1-.md

Full-text search

grep -r "payment" todos/

Key Distinctions

File-todos system (this skill):

• Markdown files in todos/ directory

• Development/project tracking

• Standalone markdown files with YAML frontmatter

• Used by humans and agents

Rails Todo model:

• Database model in app/models/todo.rb

• User-facing feature in the application

• Active Record CRUD operations

• Different from this file-based system

TodoWrite tool:

• In-memory task tracking during agent sessions

• Temporary tracking for single conversation

• Not persisted to disk

• Different from both systems above