File Todos

File TODOs

A backlog that only lives in chat history disappears when the session ends. This skill stores each item as its own markdown file with the lifecycle state baked into the filename, so the queue is inspectable with ls, greppable, diffable, and survives a crash mid-triage without losing state.

When to use this

• A batch of findings (a code review, a bug bash, an audit) that shouldn't all be fixed immediately and need triage first.
• Work items should persist across sessions, not just this conversation.
• Multiple items need to be worked through independently, possibly in parallel, by whoever/whatever picks them up next.
• Don't use this for an immediate one-off fix — just fix it. Creating a todo file for something you're about to fix in the next two minutes is pure ceremony.

Instructions

Directory and filename convention

Store items under todos/, one file per item:

todos/{id}-{status}-{priority}-{description}.md

• id — a short, stable identifier (an incrementing number is simplest, e.g. 007) so renames never collide.
• status — one of pending (needs triage) → ready (approved, queued for work) → complete (resolved and verified).
• priority — p1 (critical/blocking) through p3 (nice-to-have).
• description — a short kebab-case slug.

Example: 007-pending-p1-race-condition-in-cache.md. Moving between states is a filename rename (status segment only) — the file's content and id stay put.

File content

Each file must be fully self-contained — anyone picking it up later (including a fresh agent with none of this session's context) needs everything in the file, not in someone's memory. Use references/template.md: Problem, Evidence, Proposed fix, Priority rationale.

Triage: pending → ready

Go through pending files one at a time, not a batch skim. For each, decide:

• Ready — valid, worth fixing → rename status to ready.
• Dismiss — not worth it, duplicate, or won't-fix → delete the file, or rename to a dismissed status with a one-line reason added to the file first.

This is a deliberate gate: nothing enters the work queue without individual judgment. Skipping straight from pending to complete defeats the point of triage.

Resolve: ready → complete

ready files can be picked up in any order, independently, possibly by parallel workers — each is self-contained by design. For each:

1. Fix it.
2. Verify the fix — actually confirm it per verify-before-done's evidence ladder, don't just mark it complete because a plausible-looking change was made.
3. Rename status to complete.

Checking status at a glance

ls todos/ | sort              # id-ordered view of the whole queue
ls todos/*-pending-*          # what still needs triage
ls todos/*-ready-p1-*         # what's queued and critical

Reference files

• references/template.md — the blank todo-file template.