File-based todo tracking
File naming convention
{issue_id}-{status}-{priority}-{description}.md
- 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). Mapping from the ia-code-review severity scale: Critical→p1, Important→p2, Medium→p3, Minor→p3.
- 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
Use todo-template.md as a starting point. YAML frontmatter:
---
status: ready # pending | ready | complete
priority: p1 # p1 | p2 | p3
issue_id: "002"
tags: [typescript, performance, database]
dependencies: ["001"] # Issue IDs this is blocked by
---
Required sections: Problem Statement, Findings, Proposed Solutions, Recommended Action, Acceptance Criteria, Work Log
Optional sections: Technical Details, Resources, Notes
Key Distinctions
File-todos system (this skill): Markdown files in todos/ directory for development/project tracking. Used by humans and agents.
Application Todo model: Database model for user-facing task management. Different from this file-based system.
TodoWrite tool: In-memory task tracking during agent sessions. Temporary, not persisted to disk.
Verify
Before considering a todo file correctly written, confirm:
issue_id is unique and sequentially the next number in todos/ (never reused).- All required frontmatter fields are present:
status, priority, issue_id.
status and priority values match the filename and their enums (pending|ready|complete, p1|p2|p3).
References
1---2name: file-todos3description: File-based todo and task tracking in the todos/ directory. Use when creating, triaging, listing, or managing todo files, tracking work items, managing the backlog, converting PR comments to tracked tasks, or checking todo status and dependencies.4---56# File-based todo tracking78## File naming convention910```11{issue_id}-{status}-{priority}-{description}.md12```1314- **issue_id**: Sequential number (001, 002, 003...) -- never reused15- **status**: `pending` (needs triage), `ready` (approved), `complete` (done)16- **priority**: `p1` (critical), `p2` (important), `p3` (nice-to-have). Mapping from the `ia-code-review` severity scale: Critical→p1, Important→p2, Medium→p3, Minor→p3.17- **description**: kebab-case, brief description1819Examples: `001-pending-p1-mailer-test.md`, `002-ready-p1-fix-n-plus-1.md`, `005-complete-p2-refactor-csv.md`2021## File Structure2223Use [todo-template.md](./assets/todo-template.md) as a starting point. YAML frontmatter:2425```yaml26---27status: ready # pending | ready | complete28priority: p1 # p1 | p2 | p329issue_id: "002"30tags: [typescript, performance, database]31dependencies: ["001"] # Issue IDs this is blocked by32---33```3435**Required sections:** Problem Statement, Findings, Proposed Solutions, Recommended Action, Acceptance Criteria, Work Log3637**Optional sections:** Technical Details, Resources, Notes3839## Key Distinctions4041**File-todos system (this skill):** Markdown files in `todos/` directory for development/project tracking. Used by humans and agents.4243**Application Todo model:** Database model for user-facing task management. Different from this file-based system.4445**TodoWrite tool:** In-memory task tracking during agent sessions. Temporary, not persisted to disk.4647## Verify4849Before considering a todo file correctly written, confirm:5051- `issue_id` is unique and sequentially the next number in `todos/` (never reused).52- All required frontmatter fields are present: `status`, `priority`, `issue_id`.53- `status` and `priority` values match the filename and their enums (`pending|ready|complete`, `p1|p2|p3`).5455## References5657- [workflows.md](./references/workflows.md) - Creating, triaging, dependencies, work logs, completing todos, integration table58- [quick-reference.md](./references/quick-reference.md) - Bash commands for finding work, dependencies, searching59- [todo-template.md](./assets/todo-template.md) - Template for new todo files
iliaal