vt-c-file-todos¶

[SUPERSEDED by Beads] This skill should be used when managing the file-based todo tracking system in the todos/ directory. It provides workflows for creating todos, managing status and dependencies, conducting triage, and integrating with slash commands and code review processes.

Plugin: core-standards
Category: Tooling
Command: /vt-c-file-todos

SUPERSEDED: This skill has been superseded by Beads, the distributed git-backed issue tracker. Use bd create, bd ready, bd close instead. See docs/guides/beads-integration.md for the full workflow. This file is retained for historical reference only.

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: /vt-c-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	`/vt-c-wf-review` → Findings → `/vt-c-triage` → Todos	Review agent + skill
PR comments	`/vt-c-resolve-pr-parallel` → Individual fixes → Todos	gh CLI + skill
Code TODOs	`/vt-c-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