TODO and FIXME sweep

Claude Code slash command (.claude/commands/todo-sweep.md). Finds every TODO, FIXME, HACK, and XXX comment, dates and attributes each via git blame, triages them into fix-now / ticket / delete, and offers to act.

License: CC0-1.0 · By waxmark · v1 · 2026-11-02

Share on X

Add a trust badge to your README

[![Waxmark](https://waxmark.app/api/badge/todo-sweep)](https://waxmark.app/items/todo-sweep/scan)
Report
---
description: Find all TODO/FIXME/HACK/XXX comments, date them with git blame, and triage into fix now, ticket, or delete
argument-hint: [path to limit the sweep, default whole repo]
allowed-tools: Grep, Read, Glob, Bash(git grep *), Bash(git blame *), Bash(git log *)
---

Sweep the codebase for deferred-work markers. Scope: $ARGUMENTS (empty means the whole repository).

Markers found:
!`git grep -n -I -E '\b(TODO|FIXME|HACK|XXX)\b' -- . ':!*.lock' ':!*.min.*' ':!node_modules' ':!vendor' ':!dist' || echo "(none)"`

Procedure:
1. If a scope path was given, ignore matches outside it.
2. For each marker, get age and author with `git blame -L <line>,<line> --porcelain <file>` (use `author-time`). Read 10 lines of context around it to understand what was deferred and whether it is still true.
3. Triage each into exactly one bucket:
   - **Fix now**: the fix is under ~15 lines, has clear intent, and is covered or easily coverable by a test.
   - **Ticket**: real work that needs a decision, more than a small change, or someone else's area. Draft a one-line issue title and two-line body.
   - **Delete**: already done, obsolete (refers to removed code or shipped feature), or so vague nobody could act on it.
   - **Keep**: a deliberate, documented limitation that should stay as a comment. Use sparingly.
4. Flag any marker older than 12 months separately; age is the strongest signal that a TODO is really documentation of a known gap.

Output:

## TODO sweep: <N> markers in <M> files (scope: <path or repo>)

| # | Location | Age | Author | Text (trimmed) | Bucket |
|---|---|---|---|---|---|

### Fix now (<count>)
- #<n> `path:line` - what to do, in one sentence

### Ticket (<count>)
- #<n> **<issue title>** - <two-line body>

### Delete (<count>)
- #<n> `path:line` - why it is obsolete

### Oldest five
- ...

Then ask: "Apply the Fix now and Delete buckets? (I will not touch Ticket items.)" Do nothing until the user answers. If they say yes, make the changes, run the relevant tests, and list the files changed.
TODO and FIXME sweep · Waxmark