Manage Todo

Purpose

Manage ./todo.md in project root with task state tracking, TodoWrite synchronization, and ADR-governed refactor support. Primary use: Claude proactively creates/updates todos when detecting multi-step work.

CRITICAL: Todo File Location

Use ./todo.md for 95% of work (this skill)

Session todos: .claude/artifacts/YYYY-MM-DD/todos/todo-{name}.md

When to Use

Agent-Initiated (PRIMARY)

PROACTIVELY invoke when Claude detects:

• •"I need to create a todo to track this work"
• •"User has given me multiple tasks to coordinate"
• •"This is complex enough to warrant tracking"

User-Initiated

When user requests:

• •"Create a todo for [feature]"
• •"Update task [N] to [state]"
• •"Track these tasks"

NOT to Use

• •Single, straightforward tasks
• •Trivial operations (<3 steps)
• •Purely informational requests

Quick Start

Creating a Todo

1. •Read project context
2. •Create ./todo.md with structured tasks
3. •Assign states (🔴 pending by default)
4. •Add acceptance criteria
5. •Sync with TodoWrite

Updating State

1. •Read ./todo.md
2. •Update task state: 🔴 → 🟡 → 🟢
3. •Update TodoWrite to match
4. •Update progress summary

Checking Progress

1. •Read ./todo.md
2. •Calculate completion %
3. •Identify blockers
4. •Suggest next actions

Basic Todo Structure

# Todo: [Feature Name]
Date: YYYY-MM-DD

## Objective
[Clear statement of goal]

## Tasks

### Task 1: [Title]
**Status:** 🔴 Not Started | 🟡 In Progress | 🟢 Complete
**Priority:** High | Medium | Low

**Description:**
What needs to be done.

**Acceptance Criteria:**
- [ ] Functionality implemented
- [ ] Tests pass
- [ ] Code follows conventions

## Progress Summary
- Total: X | Completed: Y (Z%)

Task States

Integration Requirements (CRITICAL)

Prevents "done but not integrated" failures.

The CCV Principle

Missing any phase = NOT complete

Four Questions Test

Before "done", answer ALL:

1. •How do I trigger this?
2. •What connects it to the system?
3. •What proves it runs?
4. •What shows it works?

Three-Phase Todo Pattern

For integration work:

### Phase 1: CREATION
- [ ] Create [module]
- [ ] Unit tests pass

### Phase 2: CONNECTION
- [ ] Import in [consumer]
- [ ] Register in [system]
- [ ] Verify: `grep "module" src/`

### Phase 3: VERIFICATION
- [ ] Integration test passes
- [ ] Execution logs attached
- [ ] Expected outcome observed

See: references/integration-requirements.md

Key Integrations

TodoWrite Synchronization

Rule: todo.md is source of truth

Update todo.md → Update TodoWrite → Verify sync

Refactor/Migration Tracking

Rule: Refactors REQUIRE an ADR

1. •Detect refactor keywords
2. •Invoke validate-refactor-adr skill
3. •If no ADR: STOP, instruct user to create
4. •If ADR exists: Use enhanced template

Task Sizing

Good size:

• •1-4 hours of focused work
• •Clear deliverable
• •Single responsibility
• •Testable outcome

Too large: "Implement entire auth system" Too small: "Add import statement"

Enforcement Rules

1. •No Create Without Connect — Creation needs connection tasks
2. •No Connect Without Verify — Connection needs verification
3. •No Verify Without Evidence — Attach proof when checking
4. •Phase 3 Blocks Completion — Cannot complete without runtime proof

Supporting Files

References

• •references/reference.md - Task states, sync protocol, refactor tracking
• •references/integration-requirements.md - CCV principle, patterns

Templates

• •templates/todo-templates.md - Five use-case templates
• •templates/refactor-todo-template.md - ADR-governed refactor
• •templates/integration-verification-checklist.md - Integration verification

Examples

• •examples/examples.md - Workflows and examples

Red Flags

Success Metrics

Version: 2.0.0 | Updated: 2025-12-07