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