File-Based Todo Tracking

Overview

The

.context/compound-engineering/todos/

directory is a file-based tracking system for code review feedback, technical debt, feature requests, and work items. Each todo is a markdown file with YAML frontmatter.

Legacy support:

Always check both

.context/compound-engineering/todos/

(canonical) and

todos/

(legacy) when reading. Write new todos only to the canonical path. This directory has a multi-session lifecycle -- do not clean it up as scratch.

Directory Paths

Purpose

Path

Canonical (write here)

.context/compound-engineering/todos/

Legacy (read-only)

todos/

File Naming Convention

{issue_id}-{status}-{priority}-{description}.md

issue_id

Sequential number (001, 002, ...) -- never reused

status

:

pending

|

ready

|

complete

priority

:

p1

(critical) |

p2

(important) |

p3

(nice-to-have)

description

kebab-case, brief Example: 002-ready-p1-fix-n-plus-1.md File Structure Each todo has YAML frontmatter and structured sections. Use the todo template included below when creating new todos.

status : ready priority : p1 issue_id : "002" tags : [ rails , performance ] dependencies : [ "001" ]

Issue IDs this is blocked by

Required sections: Problem Statement, Findings, Proposed Solutions, Recommended Action (filled during triage), Acceptance Criteria, Work Log. Optional sections: Technical Details, Resources, Notes. Workflows Tool preference: Use native file-search/glob and content-search tools instead of shell commands for finding and reading todo files. Shell only for operations with no native equivalent ( mv , mkdir -p ). Creating a New Todo mkdir -p .context/compound-engineering/todos/ Search both paths for [0-9]-.md , find the highest numeric prefix, increment, zero-pad to 3 digits. Use the todo template included below, write to canonical path as {NEXT_ID}-pending-{priority}-{description}.md . Fill Problem Statement, Findings, Proposed Solutions, Acceptance Criteria, and initial Work Log entry. Set status: pending (needs triage) or ready (pre-approved). Create a todo when the work needs more than ~15 minutes, has dependencies, requires planning, or needs prioritization. Act immediately instead when the fix is trivial, obvious, and self-contained. Triaging Pending Items Glob -pending-.md in both paths. Review each todo's Problem Statement, Findings, and Proposed Solutions. Approve: rename pending -> ready in filename and frontmatter, fill Recommended Action. Defer: leave as pending . Load the todo-triage skill for an interactive approval workflow. Managing Dependencies dependencies : [ "002" , "005" ]

Blocked by these issues

dependencies : [ ]

No blockers

To check blockers: search for {dep_id}-complete-.md in both paths. Missing matches = incomplete blockers. Completing a Todo Verify all acceptance criteria. Update Work Log with final session. Rename ready -> complete in filename and frontmatter. Check for unblocked work: search for files containing dependencies:."{issue_id}" . Integration with Workflows Trigger Flow Code review /ce:review -> Findings -> /todo-triage -> Todos Autonomous review /ce:review mode:autofix -> Residual todos -> /todo-resolve Code TODOs /todo-resolve -> Fixes + Complex todos Planning Brainstorm -> Create todo -> Work -> Complete Key Distinction This skill manages durable, cross-session work items persisted as markdown files. For temporary in-session step tracking, use platform task tools ( TaskCreate / TaskUpdate in Claude Code, update_plan in Codex) instead. Todo Template @./assets/todo-template.md