Promptheus/commands36 commands · free · CC0Promptheus hub ↗
← All commands
/todo

Workflow

Triage TODOs

Find every TODO/FIXME/HACK and triage them.

todotech-debt
CategoryWorkflow
Argumentsnone
Allowed toolsGrepGlobRead
What it does

Scan the codebase for TODO / FIXME / HACK markers, group and prioritize them, and propose what to act on.

.claude/commands/todo.md.claude/commands/ (project) · ~/.claude/commands/ (global)
Install into your repo
npx promptheus-commands add todo

The prompt

Find, group, and triage every unresolved code-comment marker in the codebase. Surface and prioritize them; do not fix anything in this command.

Scan

  • Search tracked source only. Detect the repo's ignore rules first (.gitignore, .git) and, if inside a git repo, prefer git grep -nEI so vendored/build/node_modules output is excluded automatically. Otherwise use ripgrep respecting ignore files.
  • Match these markers as standalone uppercase words where they read as annotations: TODO, FIXME, HACK, XXX, BUG, OPTIMIZE, REFACTOR, DEPRECATED; also catch JSDoc/PHPDoc doc tags @todo and @fixme in any case. POSIX-ERE-safe regex that works in both git grep -E and rg: \b(TODO|FIXME|HACK|XXX|BUG|OPTIMIZE|REFACTOR|DEPRECATED)\b|@[Tt][Oo][Dd][Oo]|@[Ff][Ii][Xx][Mm][Ee].
  • Requiring uppercase for the bare markers is a deliberate precision tradeoff: it avoids false positives from a todo variable or the word "hack" in prose, but under-counts lowercase/mixed conventions like // fixme or Todo:. State this caveat in the output; if the codebase visibly uses lowercase markers, re-run the same search case-insensitively and reconcile the totals.
  • Restrict hits to comments/strings: skip matches inside a marker's own definition (e.g. this command, linter configs, todo-list library code, a TODO enum/type). When a word is clearly a variable, function, or product name rather than an annotation, drop it.
  • Capture per hit: the repo-relative path exactly as git grep/rg prints it, the line number, the marker type, and the full comment text including any continuation lines, (author), ticket ref, or date.

Triage

For each hit, read enough surrounding code to judge it, then classify on two axes:

  • Effort: Quick win (localized, <30 min, no design decision) / Moderate / Large (needs design or cross-cutting change).
  • Risk if left: High (correctness, security, data-loss, or a FIXME/BUG/HACK guarding real breakage) / Medium / Low (cosmetic, nice-to-have).
  • Also flag Stale/obsolete: the referenced code, API, or condition no longer exists, the ticket is closed, or it duplicates an existing implementation — verify by reading the code, not by guessing.

Give each a priority bucket:

  • Act now: High risk if left, at any effort. A quick win joins this bucket only when its risk is Medium or higher — a low-risk cosmetic quick win does NOT auto-qualify as Act now.
  • Schedule: real work that isn't high risk — moderate/large items, plus low-risk quick wins worth doing opportunistically.
  • Drop: stale/obsolete, or vague beyond recovery.

Output

  • One-line summary: total markers, counts per type, counts per bucket.
  • Group by area (directory or module), most-loaded area first. Within each group, sort rows by bucket (Act now → Schedule → Drop), then Risk (High → Low), then Effort (Quick → Large), so the most urgent item leads every group. Use a table or list: path:line · type · one-line paraphrase of the intent · Effort · Risk · Bucket.
  • A "Propose to act on now" section: the 3-7 highest-value items, each with a one-sentence rationale and the concrete first step to resolve it.
  • A "Likely stale — candidates to delete" section listing each with the evidence that it is obsolete.

Rules

  • Never edit code or delete comments in this command. Triage only.
  • Never invent markers, line numbers, or intent — quote the actual comment; if intent is unclear, say so and put it in Drop.
  • Report the exact path:line (same repo-relative form used everywhere above) for every item so each is one click to open.
  • If zero markers are found, say so plainly and stop — do not manufacture work.
  • If hits exceed ~60, still count all of them, but detail only Act-now and stale items; summarize the rest by area and count.

Add it to your toolkit

Save it as .claude/commands/todo.md or .cursor/commands/todo.md, then invoke it with /todo.

Back to top ↑