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.
Inherits all available tools
Additional assets for this skill
This skill inherits all available tools. When active, it can use any tool Claude has access to.
assets/todo-template.mdThe 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:
Todo files follow this naming pattern:
{issue_id}-{status}-{priority}-{description}.md
Components:
pending (needs triage), ready (approved), complete (done)p1 (critical), p2 (important), p3 (nice-to-have)Examples:
001-pending-p1-mailer-test.md
002-ready-p1-fix-n-plus-1.md
005-complete-p2-refactor-csv.md
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:
Optional sections:
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
---
To create a new todo from findings or feedback:
ls todos/ | grep -o '^[0-9]\+' | sort -n | tail -1cp assets/todo-template.md todos/{NEXT_ID}-pending-{priority}-{description}.mdpending (needs triage) or ready (pre-approved)When to create a todo:
When to act immediately instead:
To triage pending todos:
ls todos/*-pending-*.mdmv {file}-pending-{pri}-{desc}.md {file}-ready-{pri}-{desc}.mdstatus: pending → status: readypending statusUse slash command: /triage for interactive approval workflow
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
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:
To mark a todo as complete:
mv {file}-ready-{pri}-{desc}.md {file}-complete-{pri}-{desc}.mdstatus: ready → status: completegrep -l 'dependencies:.*"002"' todos/*-ready-*.mdfeat: resolve issue 002| Trigger | Flow | Tool |
|---|---|---|
| Code review | /workflows: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 |
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/
File-todos system (this skill):
todos/ directoryRails Todo model:
app/models/todo.rbTodoWrite tool: