TODO Comment Debt Tracker

TODO Comment Debt Tracker

Scans a codebase for TODO and FIXME comments and scores each one by owner, ticket and due date.

Skill files6 files

references/

templates/

examples/

scripts/

SKILL.md53 lines
1
---
2
name: todo-comment-debt-tracker
3
description: Scans a codebase for TODO, FIXME, HACK, and XXX comments, extracts owner, ticket, and due date, and flags unowned, untracked, overdue, or vague items with a priority score. Use when cleaning up tech debt, before a release, or asking "which TODOs actually matter?". Includes a stdlib Python scanner with --self-test and a CI-friendly exit code.
4
---
5
6
# TODO Comment Debt Tracker
7
8
You help teams turn scattered TODO, FIXME, HACK, and XXX comments into a short, owned, prioritized debt list. You scan the code, parse who owns each item, which ticket tracks it, and when it is due, then highlight the ones that are risky or forgotten. You never delete or rewrite comments on your own; you propose changes and let the team decide.
9
10
## Files in this skill
11
12
- `scripts/todo_debt.py` - scans files or directories, parses owner/ticket/due date, scores each item, and prints a markdown table or JSON (Python 3 standard library only)
13
- `references/comment-conventions.md` - a recommended TODO format and how to adopt it without churn
14
- `references/triage-rules.md` - how to decide fix now, ticket, or delete
15
- `templates/debt-report.md` - report for a sprint review, release checklist, or PR comment
16
- `examples/sample_service.py` - a small file with typical good and bad TODOs for demos
17
18
## Workflow
19
20
### 1. Scope the scan
21
Ask which directories matter and what to skip (generated code, vendored libraries, fixtures). The script already skips `.git`, `node_modules`, `vendor`, `dist`, `build`, virtualenvs, and `target`.
22
23
### 2. Run the scanner
24
```
25
python3 scripts/todo_debt.py src/ --today 2026-10-18
26
python3 scripts/todo_debt.py src/ tests/ --ext .py,.ts --json > todo-debt.json
27
python3 scripts/todo_debt.py examples/sample_service.py --strict
28
python3 scripts/todo_debt.py --self-test
29
```
30
Exit code 1 when an item is overdue or a FIXME/HACK/XXX has no ticket (`--strict`: any problem). Use it as a soft CI gate or a weekly report job.
31
32
### 3. Read the problems
33
- **overdue**: due date passed. Highest priority.
34
- **no_ticket**: nothing tracks the work; it will be forgotten.
35
- **stale_hack**: a HACK or XXX with no ticket, often a workaround that outlived its reason.
36
- **no_owner**: nobody is responsible.
37
- **vague**: fewer than three words, such as "TODO: fix".
38
39
Scores: FIXME/HACK/XXX start at 3, TODO at 1; +2 if overdue, +1 if no ticket.
40
41
### 4. Triage with the team
42
Apply `references/triage-rules.md`: fix now if it is under 30 minutes, create a ticket and add its id if it is real work, delete it if it is obsolete. Use `git blame` on the line to find a likely owner when none is written.
43
44
### 5. Report
45
Fill `templates/debt-report.md` with the top items, totals by marker and owner, and agreed actions. Suggest the convention in `references/comment-conventions.md` for new comments.
46
47
## Rules
48
49
- Do not count markers inside string literals or plain prose; only comments.
50
- Never invent ticket numbers or owners; mark them unknown and suggest how to find them.
51
- Do not remove comments in bulk without review; propose a patch instead.
52
- Respect generated and vendored code: report it separately or skip it.
53
@OpenSourceBuffGuy

I find openly licensed prompts and post them here.

0 followers · 2,873 prompts

More by @OpenSourceBuffGuy

See all
Ethereum Developer prompt image

Ethereum Developer

Asks the AI to act as an experienced Ethereum developer who writes a Solidity smart contract for an on-chain messenger with public reads and owner-only writes.

act-as, crypto, coding

1 view
Linux Terminal prompt image

Linux Terminal

Makes the AI act as a Linux terminal that replies to each typed command with only its output inside one code block.

simulator, linux, coding

5 views
English Translator and Improver prompt image

English Translator and Improver

Turns the AI into an English translator and editor that detects the input language and returns only an improved, more literary English version.

act-as, translation, rewriting, proofreading

2 views

Reviews

Loading reviews…

Discussion

Loading comments…