File Todos

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)
• 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.

References

• workflows.md - Creating, triaging, dependencies, work logs, completing todos, integration table
• quick-reference.md - Bash commands for finding work, dependencies, searching
• todo-template.md - Template for new todo files

Brief Task Title

Replace with a concise title describing what needs to be done.

Problem Statement

What is broken, missing, or needs improvement? Provide clear context about why this matters.

Example:

• Template system lacks comprehensive test coverage for edge cases discovered during PR review
• Email service is missing proper error handling for rate-limit scenarios
• Documentation doesn't cover the new authentication flow

Findings

Investigation results, root cause analysis, and key discoveries.

• Finding 1 (with specifics: file, line number if applicable)
• Finding 2
• Key discovery with impact assessment
• Related issues or patterns discovered

Example format:

• Identified 12 missing test scenarios in src/__tests__/user.test.ts
• Current coverage: 60% of code paths
• Missing: empty inputs, special characters, large payloads
• Similar issues exist in src/__tests__/post.test.ts (~8 scenarios)

Proposed Solutions

Present multiple options with pros, cons, effort estimates, and risk assessment.

Option 1: [Solution Name]

Approach: Describe the solution clearly.

Pros:

• Benefit 1
• Benefit 2

Cons:

• Drawback 1
• Drawback 2

Effort: 2-3 hours

Risk: Low / Medium / High

---

Option 2: [Solution Name]

Approach: Describe the solution clearly.

Pros:

• Benefit 1
• Benefit 2

Cons:

• Drawback 1
• Drawback 2

Effort: 4-6 hours

Risk: Low / Medium / High

---

Option 3: [Solution Name]

(Include if you have alternatives)

Recommended Action

To be filled during triage. Clear, actionable plan for resolving this todo.

Example: "Implement both unit tests (covering each scenario) and integration tests (full pipeline) before merging. Estimated 4 hours total effort. Target coverage > 85% for this module."

Technical Details

Affected files, related components, database changes, or architectural considerations.

Affected files:

• src/models/User.ts:45 - full_name method
• src/services/UserService.ts:12 - validation logic
• src/__tests__/models/user.test.ts - existing tests

Related components:

• UserMailer (depends on user validation)
• AccountPolicy (authorization checks)

Database changes (if any):

• Migration needed? Yes / No
• New columns/tables? Describe here

Resources

Links to errors, tests, PRs, documentation, similar issues.

• PR: #1287
• Related issue: #456
• Error log: [link to AppSignal incident]
• Documentation: [relevant docs]
• Similar patterns: Issue #200 (completed, ref for approach)

Acceptance Criteria

Testable checklist items for verifying completion.

• [ ] All acceptance criteria checked
• [ ] Tests pass (unit + integration if applicable)
• [ ] Code reviewed and approved
• [ ] (Example) Test coverage > 85%
• [ ] (Example) Performance metrics acceptable
• [ ] (Example) Documentation updated

Work Log

Chronological record of work sessions, actions taken, and learnings.

2025-11-12 - Initial Discovery

By: Claude Code

Actions:

• Identified 12 missing test scenarios
• Analyzed existing test coverage (file:line references)
• Reviewed similar patterns in codebase
• Drafted 3 solution approaches

Learnings:

• Similar issues exist in related modules
• Current test setup supports both unit and integration tests
• Performance testing would be valuable addition

---

(Add more entries as work progresses)

Notes

Additional context, decisions, or reminders.

• Decision: Include both unit and integration tests for comprehensive coverage
• Blocker: Depends on completion of issue #001
• Timeline: Priority for sprint due to blocking other work

Quick Reference Commands

Finding Work

# List highest priority unblocked work
grep -l 'dependencies: \[\]' todos/*-ready-p1-*.md

# List all pending items needing triage
ls todos/*-pending-*.md

# Find next issue ID
ls todos/ | grep -o '^[0-9]\+' | sort -n | tail -1 | awk '{printf "%03d", $1+1}'

# Count by status
for status in pending ready complete; do
  echo "$status: $(ls -1 todos/*-$status-*.md 2>/dev/null | wc -l)"
done

Dependency Management

# What blocks this todo?
grep "^dependencies:" todos/003-*.md

# What does this todo block?
grep -l 'dependencies:.*"002"' todos/*.md

Searching

# Search by tag
grep -l "tags:.*typescript" todos/*.md

# Search by priority
ls todos/*-p1-*.md

# Full-text search
grep -r "payment" todos/

Todo Workflows

Creating a New Todo

To create a new todo from findings or feedback:

1. Determine next issue ID: ls todos/ | grep -o '^[0-9]\+' | sort -n | tail -1 2. Copy template: cp assets/todo-template.md todos/{NEXT_ID}-pending-{priority}-{description}.md 3. Edit and fill required sections:

• Problem Statement
• Findings (if from investigation)
• Proposed Solutions (multiple options)
• Acceptance Criteria
• Add initial Work Log entry

4. Determine status: pending (needs triage) or ready (pre-approved) 5. 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

To triage pending todos:

1. List pending items: ls todos/*-pending-*.md 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

Use slash command: /ia-triage for 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:

grep "^dependencies:" todos/003-*.md

To find what a todo blocks:

grep -l 'dependencies:.*"002"' todos/*.md

To verify blockers are complete before starting:

for dep in 001 002 003; do
  [ -f "todos/${dep}-complete-*.md" ] || echo "Issue $dep not complete"
done

Updating Work Logs

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

### YYYY-MM-DD - Session Title

**By:** Claude Code / 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

To mark a todo as complete:

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: grep -l 'dependencies:.*"002"' todos/*-ready-*.md 6. Commit with issue reference: feat: resolve issue 002

---

Integration with Development Workflows

ia-file-todos Specification

Intent

ia-file-todos is a tool-class skill (a narrow utility scoped to a single capability). 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.

Scope

In scope:

• Behaviors described in SKILL.md and routed via the should_trigger phrasings in distillery/tests/fixtures/triggers/ia-file-todos.jsonl.
• Updates to runtime behavior, structure, trigger precision, references, and validation.

Out of scope:

• Acting as the runtime instructions themselves (those live in SKILL.md).
• Trigger phrasings already covered by adjacent ia-* skills (validate-plugin flags >70% description overlap as DUPLICATE_TRIGGER).
• <!-- to fill in: domain-specific exclusions when the skill drifts -->

Trigger Context

• Class: tool
• Hook regex: plugins/whetstone/hooks/skill-patterns.sh -> SKILL_PATTERNS[ia-file-todos]
• Common requests (from fixture should_trigger):
• "set up the todo directory for tracking work items"
• "manage the file-based todo list for this sprint"
• "manage todos for this refactor"
• Should not trigger for (from fixture should_not_trigger):
• "optimize the image processing pipeline"
• "add WebSocket support for real-time notifications"
• "close the GitHub issue for this bug"

Source And Evidence Model

Authoritative sources:

• SKILL.md -- runtime instructions and reference routing.
• references/*.md -- bundled supplementary content (2 file(s)).
• distillery/tests/fixtures/triggers/ia-file-todos.jsonl -- positive and negative trigger phrasings under regression test.
• plugins/whetstone/hooks/skill-patterns.sh -- regex pattern that fires this skill.
• distillery/.eval-data/ia-file-todos/ -- harvested session examples (when present).

Data that must not be stored in this skill or its references:

• Secrets, credentials, tokens.
• Machine-specific filesystem paths (/home/..., /Users/..., ~/ai/...). The validator (MACHINE_PATH_LEAK) flags these as HIGH.
• Private URLs, customer data, or unredacted personal information.

Coverage matrix

Evaluation

Lightweight (run on every change):

python3 distillery/scripts/distiller.py validate-plugin --component ia-file-todos
python3 distillery/scripts/distiller.py test-triggers --skill ia-file-todos

Deeper (when behavior risk warrants):

python3 distillery/scripts/distiller.py dspy-eval ia-file-todos
python3 distillery/scripts/distiller.py diagnose-negatives ia-file-todos

Acceptance gates:

• validate-plugin --component ia-file-todos returns 0 HIGH findings.
• test-triggers --skill ia-file-todos returns F1 = 1.0 with floors of 5 should_trigger and 5 should_not_trigger.
• For dspy-eval, the composite score does not regress against the most recent saved baseline (see distillery/.eval-data/ia-file-todos/history.json).

Known Limitations

<!-- to fill in over time as drift surfaces. Default rule: any time diagnose-negatives surfaces a recurring failure pattern, document it here so future maintainers understand the trade-off the current implementation accepts. -->

Maintenance Notes

• Update SKILL.md when the runtime workflow, branch conditions, or output contract changes.
• Update this SPEC.md when intent, scope, evidence model, evaluation gates, or maintenance expectations change.
• Update the trigger fixture when adding new positive phrasings, removing stale ones, or expanding scope (the 5/5 floor is a hard validator gate).
• Update the hook regex in skill-patterns.sh whenever fixture positives expose a missed phrasing; verify F1 = 1.0 with eval-triggers before committing.
• Run the full release pipeline via /release -- never bump versions or update CHANGELOG.md from a per-skill edit.