File Todos

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:

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. Edit and fill required sections:

• Problem Statement
• Findings (if from investigation)
• Proposed Solutions (multiple options)
• Acceptance Criteria
• Add initial Work Log entry

4. Determine status: pending (needs triage) or ready (pre-approved) 5. 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:

1. List pending items: ls todos/*-pending-*.md 2. For each todo:

• Read Problem Statement and Findings
• Review Proposed Solutions
• Make decision: approve, defer, or modify priority

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

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

1. Verify all acceptance criteria checked off 2. Update Work Log with final session and results 3. Rename file: mv {file}-ready-{pri}-{desc}.md {file}-complete-{pri}-{desc}.md 4. Update frontmatter: status: ready → status: complete 5. Check for unblocked work: grep -l 'dependencies:.*"002"' todos/*-ready-*.md 6. Commit with issue reference: feat: resolve issue 002

Integration with Development Workflows

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

Brief Task Title

Replace with a concise title describing what needs to be done.

Problem Statement

What is broken, missing, or needs improvement? Provide clear context about why this matters.

Example:

• Template system lacks comprehensive test coverage for edge cases discovered during PR review
• Email service is missing proper error handling for rate-limit scenarios
• Documentation doesn't cover the new authentication flow

Findings

Investigation results, root cause analysis, and key discoveries.

• Finding 1 (with specifics: file, line number if applicable)
• Finding 2
• Key discovery with impact assessment
• Related issues or patterns discovered

Example format:

• Identified 12 missing test scenarios in app/models/user_test.rb
• Current coverage: 60% of code paths
• Missing: empty inputs, special characters, large payloads
• Similar issues exist in app/models/post_test.rb (~8 scenarios)

Proposed Solutions

Present multiple options with pros, cons, effort estimates, and risk assessment.

Option 1: [Solution Name]

Approach: Describe the solution clearly.

Pros:

• Benefit 1
• Benefit 2

Cons:

• Drawback 1
• Drawback 2

Effort: 2-3 hours

Risk: Low / Medium / High

---

Option 2: [Solution Name]

Approach: Describe the solution clearly.

Pros:

• Benefit 1
• Benefit 2

Cons:

• Drawback 1
• Drawback 2

Effort: 4-6 hours

Risk: Low / Medium / High

---

Option 3: [Solution Name]

(Include if you have alternatives)

Recommended Action

To be filled during triage. Clear, actionable plan for resolving this todo.

Example: "Implement both unit tests (covering each scenario) and integration tests (full pipeline) before merging. Estimated 4 hours total effort. Target coverage > 85% for this module."

Technical Details

Affected files, related components, database changes, or architectural considerations.

Affected files:

• app/models/user.rb:45 - full_name method
• app/services/user_service.rb:12 - validation logic
• test/models/user_test.rb - existing tests

Related components:

• UserMailer (depends on user validation)
• AccountPolicy (authorization checks)

Database changes (if any):

• Migration needed? Yes / No
• New columns/tables? Describe here

Resources

Links to errors, tests, PRs, documentation, similar issues.

• PR: #1287
• Related issue: #456
• Error log: [link to AppSignal incident]
• Documentation: [relevant docs]
• Similar patterns: Issue #200 (completed, ref for approach)

Acceptance Criteria

Testable checklist items for verifying completion.

• [ ] All acceptance criteria checked
• [ ] Tests pass (unit + integration if applicable)
• [ ] Code reviewed and approved
• [ ] (Example) Test coverage > 85%
• [ ] (Example) Performance metrics acceptable
• [ ] (Example) Documentation updated

Work Log

Chronological record of work sessions, actions taken, and learnings.

2025-11-12 - Initial Discovery

By: Claude Code

Actions:

• Identified 12 missing test scenarios
• Analyzed existing test coverage (file:line references)
• Reviewed similar patterns in codebase
• Drafted 3 solution approaches

Learnings:

• Similar issues exist in related modules
• Current test setup supports both unit and integration tests
• Performance testing would be valuable addition

---

(Add more entries as work progresses)

Notes

Additional context, decisions, or reminders.

• Decision: Include both unit and integration tests for comprehensive coverage
• Blocker: Depends on completion of issue #001
• Timeline: Priority for sprint due to blocking other work