File Todos

View source

File-Based Todo Tracking Skill

Overview

The .context/systematic/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.

Legacy support: During the transition period, always check both .context/systematic/todos/ (canonical) and todos/ (legacy) when reading or searching for todos. Write new todos only to the canonical path. Unlike per-run scratch directories, .context/systematic/todos/ has a multi-session lifecycle — do not clean it up as part of post-run scratch cleanup.

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

Directory Paths

Purpose	Path
Canonical (write here)	.context/systematic/todos/
Legacy (read-only)	todos/

When searching or listing todos, always search both paths. When creating new todos, always write to the canonical path.

File Naming Convention

{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 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

Tool preference: Use native file-search (e.g., Glob in OpenCode) and content-search (e.g., Grep in OpenCode) tools instead of shell commands for finding and reading todo files. This avoids unnecessary permission prompts in sub-agent workflows. Use shell only for operations that have no native equivalent (e.g., mv for renames, mkdir -p for directory creation).

Creating a New Todo

1. Ensure directory exists: mkdir -p .context/systematic/todos/
2. Determine next issue ID by searching both canonical and legacy paths for files matching [0-9]*-*.md using the native file-search/glob tool. Extract the numeric prefix from each filename, find the highest, and increment by one. Zero-pad to 3 digits (e.g., 007).
3. Read the template at todo-template.md, then write it to .context/systematic/todos/{NEXT_ID}-pending-{priority}-{description}.md using the native file-write tool.
4. Edit and fill required sections:
   • Problem Statement
   • Findings (if from investigation)
   • Proposed Solutions (multiple options)
   • Acceptance Criteria
   • Add initial Work Log entry
5. Determine status: pending (needs triage) or ready (pre-approved)
6. 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

1. Find pending items using the native file-search/glob tool with pattern *-pending-*.md in both directory paths.
2. For each todo:
   • Read Problem Statement and Findings
   • Review Proposed Solutions
   • Make decision: approve, defer, or modify priority
3. 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
4. Deferred todos stay in pending status

Load the triage skill for an 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: Use the native content-search tool (e.g., Grep in OpenCode) to search for ^dependencies: in the todo file.

To find what a todo blocks: Search both directory paths for files containing dependencies:.*"002" using the native content-search tool.

To verify blockers are complete before starting: For each dependency ID, use the native file-search/glob tool to look for {dep_id}-complete-*.md in both directory paths. Any missing matches indicate incomplete blockers.

Updating Work Logs

When working on a todo, always add a work log entry:

### YYYY-MM-DD - Session Title

**By:** Agent name / 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

1. Verify all acceptance criteria checked off
2. Update Work Log with final session and results
3. Rename file: mv {file}-ready-{pri}-{desc}.md {file}-complete-{pri}-{desc}.md
4. Update frontmatter: status: ready -> status: complete
5. Check for unblocked work: search both directory paths for *-ready-*.md files containing dependencies:.*"{issue_id}" using the native content-search tool
6. Commit with issue reference: feat: resolve issue 002

Integration with Development Workflows

Trigger	Flow	Tool
Code review	/ce:review -> Findings -> /triage -> Todos	Review agent + skill
Beta autonomous review	/ce:review-beta mode:autonomous -> Downstream-resolver residual todos -> /resolve-todo-parallel	Review skill + todos
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

Quick Reference Patterns

Use the native file-search/glob tool (e.g., Glob in OpenCode) and content-search tool (e.g., Grep in OpenCode) for these operations. Search both canonical and legacy directory paths.

Finding work:

Goal	Tool	Pattern
List highest priority unblocked work	Content-search	dependencies: \[\] in *-ready-p1-*.md
List all pending items needing triage	File-search	*-pending-*.md
Find next issue ID	File-search	[0-9]*-*.md, extract highest numeric prefix
Count by status	File-search	*-pending-*.md, *-ready-*.md, *-complete-*.md

Dependency management:

Goal	Tool	Pattern
What blocks this todo?	Content-search	^dependencies: in the specific todo file
What does this todo block?	Content-search	dependencies:.*"{id}" across all todo files

Searching:

Goal	Tool	Pattern
Search by tag	Content-search	tags:.*{tag} across all todo files
Search by priority	File-search	*-p1-*.md (or p2, p3)
Full-text search	Content-search	{keyword} across both directory paths

Key Distinctions

File-todos system (this skill):

• Markdown files in .context/systematic/todos/ (legacy: todos/)
• Development/project tracking across sessions and agents
• Standalone markdown files with YAML frontmatter
• Persisted to disk, cross-agent accessible

In-session task tracking (e.g., todowrite/TaskUpdate in OpenCode, update_plan in Codex):

• In-memory task tracking during agent sessions
• Temporary tracking for single conversation
• Not persisted to disk after session ends
• Different purpose: use for tracking steps within a session, not for durable cross-session work items