dotclaude

Command in productivity

todo-triage

Inventory every TODO, FIXME, HACK, and XXX comment, enrich each with age and author from git blame, classify them (bug risk, missing feature, cleanup, obsolete), and produce a prioritized triage table with recommended dispositions. Pass a path to limit the scan. Use when technical-debt comments have accumulated and nobody knows which ones still matter.

Arguments
[path]
Model
inherit
Allowed tools
Read, Grep, Glob, Bash(git:*)

Install

As a plugin

Bundled in the productivity plugin. Add the marketplace once, then install the bundle; it updates with the marketplace.

/plugin marketplace add KhaledSaeed18/dotclaude
/plugin install productivity@dotclaude

As a single item

Run from the project root; the command lands under .claude/. Copy it to ~/.claude/ to make it global.

npx shadcn@latest add KhaledSaeed18/dotclaude/todo-triage

Files installed

  • .claude/commands/todo-triage.md

What it does

Context

Scope (optional, defaults to the whole repository): $ARGUMENTS

Marker counts:

!grep -rInE "(TODO|FIXME|HACK|XXX)[:( ]" --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=dist --exclude-dir=build . 2>/dev/null | wc -l

Task

Turn stale debt comments into decisions. Every marker gets exactly one disposition: fix now, ticket it, keep with a better comment, or delete.

Step 1: Collect

grep -rInE "(TODO|FIXME|HACK|XXX)[:( ]" --exclude-dir=node_modules --exclude-dir=.git \
  --exclude-dir=dist --exclude-dir=build .

Replace the trailing . with the scope path when $ARGUMENTS names one. For each hit, capture file, line, marker type, and the comment text. If there are more than ~60, group obviously identical/boilerplate ones and triage the groups.

Step 2: Enrich with history

For each marker (or group representative), get age and author:

git blame -L <line>,<line> --porcelain -- <file> | head -3

Age matters: a three-year-old TODO next to code that has since been rewritten is usually obsolete; a two-week-old FIXME by the current author is usually real. Read enough surrounding code to judge whether the comment still describes reality.

Step 3: Classify

Sort every marker into exactly one bucket:

  • Bug risk - the comment describes incorrect or unsafe behavior that is still present (FIXME on a race, HACK around validation). These are latent defects wearing a comment as a disguise.
  • Missing feature / follow-up - real work someone deferred; still relevant.
  • Cleanup - refactors, naming, dead-code notes; valid but low urgency.
  • Obsolete - the surrounding code changed, the feature shipped, the dependency was replaced; the comment is noise now.

Step 4: Report

Produce one table, ordered bug risk first, then by age within each bucket:

| # | Marker | Location | Age | Author | Comment (condensed) | Bucket | Recommendation |

Recommendations are specific: "fix now (5-line change, suggest doing it in this session)", "file an issue titled ...", "delete the comment, superseded by <commit/feature>", "rewrite the comment to say what is actually blocked on". Close with the totals per bucket and offer the two follow-ups you can do immediately: fix the quick bug-risk items, and delete the obsolete comments in one commit.

Do not change any code during triage; the deliverable is the table and the offer.

This is the command as installed, rendered from its source on GitHub. Read it as Markdown.

  • primeLoad project context into the session by reading key files and recent history. Primes the model with package metadata, architecture notes, recent commits...
  • weekly-reviewProduce a weekly review from the evidence in the repository and the workspace: commits and pull requests merged or open, issues closed and opened...
  • brainstormingTurn a rough idea into a fully formed, written design through collaborative dialogue, exploring intent, requirements, and trade-offs one question at a...
  • decision-logKeep a lightweight decision log for a project or a person: one dated line per decision with the choice, the reason, the alternatives, who decided, and a...
  • grill-meRelentlessly stress-test a plan, design, architecture, idea, or strategy until all critical decisions are resolved. Use when a plan, design, or decision...
  • handoffCompact the current conversation into a handoff document for another agent to pick up. Use when ending a session, switching agents, or preserving context...