file-todos

SKILL.md

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 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
/ce: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