# File Todos

> Tracks review findings and work items as individual markdown files whose filename encodes lifecycle state — {id}-{status}-{priority}-{description}.md, status pending to ready to complete — so the queue is visible with plain `ls`, survives crashes, and needs no database. Use when findings need to persist and be triaged across sessions rather than fixed immediately, or when items should be reviewed one at a time and then fixed independently, possibly in parallel.

- Skill: `jsvillalbat/file-todos` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add jsvillalbat/file-todos`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jsvillalbat/file-todos/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: jsvillalbat (https://skillmd.com/u/jsvillalbat)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jsvillalbat/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:

```text
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

```bash
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.