Variables
Arguments: $ARGUMENTS
Shared tracker context
The seam, operation routing, label taxonomy, canonical-role remapping, recurring schedule, and
topic-docs binding that every work-items skill relies on live in
${CLAUDE_PLUGIN_ROOT}/reference/tracker-seam.md
(and the references it links). Read it at the start of an invocation. Item creation goes through the
seam via the /work-items:track add path; the core inlines no provider commands.
Purpose
Sweep the codebase for actionable comment markers (TODO/FIXME/HACK/XXX) and resolve or file each one. Not the encouraged workflow for new work. Durable work belongs in the tracker at authoring time; prefer a commit-time hygiene gate (linter or git hook) in the consuming repo to catch new violations as they land.
Usage
/work-items:scan-todos [--path <dir>] [--work]
Flags
--path <dir>, Limit scan to a specific directory (default: repo root)--work, After presenting groups, auto-select the smallest group and start resolving
Detection
If the consuming repo has its own comment-hygiene tooling (a shared pattern library, a lint lane), use that as the detection source of truth per the repo's own rules. Otherwise, scan tracked files directly:
# -C roots the scan at the repo top — a bare git grep from a subdirectory searches only that subtree.
# With --path <dir>, thread it in as a root-relative pathspec (keep the exclusions): ... -- '<dir>' ':!*.min.*' ':!*node_modules*'
git -C "${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel)}" grep -nE '\b(TODO|FIXME|HACK|XXX)\b' -- ':!*.min.*' ':!*node_modules*' | tr -d '\r'
- Actionable (in scope): bare
TODO/FIXME/HACK/XXX markers describing work to do; internal tracker provenance comments (e.g. item #N breadcrumbs left in code)
- Not actionable (skip): external upstream citations (
org/repo#issue), structured task-list grammar in working-notes files (e.g. [TODO] phase tags), test fixtures that assert on the literal marker text, and the consuming repo's documented exclusion paths
Workflow
Scan using the detection command above (or the repo's own tooling). Avoid per-file grep loops over large trees, one git grep pass scales; per-file spawning is unusable on Windows.
Group by parent folder. Count items per group.
Present summary table sorted by count (smallest first).
User selects a group (by #) or use --work to auto-select the smallest.
For each marker, read context (10 lines before/after), then classify:
- Resolve now, small fix; do the work, remove the marker
- File a work item + remove marker, significant work; create it by invoking
/work-items:track add via the Skill tool following the shared self-observation contract (${CLAUDE_PLUGIN_ROOT}/reference/dogfood-filing.md: dedupe → categorize → fixed shape → needs-triage), remove the inline marker (do not leave TODO as a stand-in for the item)
- Remove (already done), work completed; delete the comment
- False positive, structured grammar or external upstream citation misclassified; fix the exclusion if systemic, otherwise note it in the PR
Never "Keep (intentional)" for actionable TODO/FIXME/HACK/XXX in merged production code.
After processing a group, present results table with file, line, action, detail.
Verify. Run the consuming repo's build/test/lint commands if any source files were modified.
1---2name: scan-todos3description: Sweep the codebase's source comments, not tracker items, for actionable markers (TODO/FIXME/HACK/XXX) and resolve or file each one. Use when: 'scan TODOs', 'scan for FIXME', 'sweep the codebase for markers', 'find TODO comments', 'resolve TODO/FIXME/HACK', 'scan for tech-debt comments', 'clean up markers'. NOT the encouraged workflow for new work. Durable work belongs in the tracker at authoring time; prefer a commit-time hygiene gate. Sibling skills: /work-items:track (backlog CRUD), /work-items:work (auto-select + execute), /work-items:triage (raw intake), /work-items:decompose (plan → tickets).4---56## Variables78Arguments: `$ARGUMENTS`910## Shared tracker context1112The seam, operation routing, label taxonomy, canonical-role remapping, recurring schedule, and13topic-docs binding that every work-items skill relies on live in14[`${CLAUDE_PLUGIN_ROOT}/reference/tracker-seam.md`](${CLAUDE_PLUGIN_ROOT}/reference/tracker-seam.md)15(and the references it links). Read it at the start of an invocation. Item creation goes through the16seam via the `/work-items:track add` path; the core inlines no provider commands.1718## Purpose1920Sweep the codebase for actionable comment markers (`TODO`/`FIXME`/`HACK`/`XXX`) and resolve or file each one. **Not** the encouraged workflow for new work. Durable work belongs in the tracker at authoring time; prefer a commit-time hygiene gate (linter or git hook) in the consuming repo to catch new violations as they land.2122## Usage2324```25/work-items:scan-todos [--path <dir>] [--work]26```2728## Flags2930- `--path <dir>`, Limit scan to a specific directory (default: repo root)31- `--work`, After presenting groups, auto-select the smallest group and start resolving3233## Detection3435If the consuming repo has its own comment-hygiene tooling (a shared pattern library, a lint lane), use that as the detection source of truth per the repo's own rules. Otherwise, scan tracked files directly:3637```bash38# -C roots the scan at the repo top — a bare git grep from a subdirectory searches only that subtree.39# With --path <dir>, thread it in as a root-relative pathspec (keep the exclusions): ... -- '<dir>' ':!*.min.*' ':!*node_modules*'40git -C "${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel)}" grep -nE '\b(TODO|FIXME|HACK|XXX)\b' -- ':!*.min.*' ':!*node_modules*' | tr -d '\r'41```4243- **Actionable (in scope):** bare `TODO`/`FIXME`/`HACK`/`XXX` markers describing work to do; internal tracker provenance comments (e.g. `item #N` breadcrumbs left in code)44- **Not actionable (skip):** external upstream citations (`org/repo#issue`), structured task-list grammar in working-notes files (e.g. `[TODO]` phase tags), test fixtures that assert on the literal marker text, and the consuming repo's documented exclusion paths4546## Workflow47481. **Scan** using the detection command above (or the repo's own tooling). Avoid per-file grep loops over large trees, one `git grep` pass scales; per-file spawning is unusable on Windows.49501. **Group** by parent folder. Count items per group.51521. **Present** summary table sorted by count (smallest first).53541. **User selects a group** (by `#`) or use `--work` to auto-select the smallest.55561. **For each marker**, read context (10 lines before/after), then classify:5758- **Resolve now**, small fix; do the work, remove the marker59- **File a work item + remove marker**, significant work; create it by invoking `/work-items:track add` via the Skill tool following the shared self-observation contract ([`${CLAUDE_PLUGIN_ROOT}/reference/dogfood-filing.md`](${CLAUDE_PLUGIN_ROOT}/reference/dogfood-filing.md): dedupe → categorize → fixed shape → `needs-triage`), remove the inline marker (do not leave `TODO` as a stand-in for the item)60- **Remove (already done)**, work completed; delete the comment61- **False positive**, structured grammar or external upstream citation misclassified; fix the exclusion if systemic, otherwise note it in the PR6263**Never** "Keep (intentional)" for actionable `TODO`/`FIXME`/`HACK`/`XXX` in merged production code.64651. **After processing a group**, present results table with file, line, action, detail.66671. **Verify**. Run the consuming repo's build/test/lint commands if any source files were modified.
melodic-software