What patterns does Stale Todo Finder detect and across which languages?

It detects TODO, FIXME, HACK, XXX, BUG, OPTIMIZE across Python, JavaScript, TypeScript, Go, Java, C/C++, Ruby, and Rust.

How is staleness calculated?

Staleness is computed by correlating the TODO with git history to capture the commit date when the item was added, yielding an age in days and the original author.

How can I customize outputs or filters?

You can tailor results by adjusting patterns, excluding paths (e.g., vendor/ or node_modules/), and exporting reports via generate_report.py or generate_html_report.py.

Stale Todo Finder

Scanned

npx machina-cli add skill dcs-soni/awesome-claude-skills/stale-todo-finder --openclaw

Files (1)

SKILL.md

3.6 KB

Stale TODO Finder

Find forgotten TODO/FIXME/HACK comments and track their age using git blame.

Quick Start

Copy this checklist:

Stale TODO Analysis:
- [ ] Step 1: Scan for TODO comments
- [ ] Step 2: Analyze staleness with git blame
- [ ] Step 3: Categorize by age
- [ ] Step 4: Generate actionable report

Workflow

Step 1: Scan for TODO Comments

Find all TODO-style comments in the codebase:

python scripts/find_todos.py <directory> --format json

Patterns detected:

TODO, FIXME, HACK, XXX, BUG, OPTIMIZE
Works across Python, JavaScript, TypeScript, Go, Java, C/C++, Ruby, Rust

Step 2: Analyze Staleness

Correlate TODOs with git history:

python scripts/analyze_staleness.py <directory> --min-age 90

Output includes:

Commit date when TODO was added
Age in days
Original author
File and line number

Step 3: Categorize by Age

TODOs are grouped into staleness buckets:

Category	Age	Priority
🔴 Ancient	>1 year	High - likely forgotten
🟠 Stale	6-12 months	Medium - needs review
🟡 Aging	3-6 months	Low - monitor
🟢 Recent	<3 months	OK - still relevant

Step 4: Generate Report

Create actionable markdown report:

python scripts/generate_report.py <directory> --output stale_todos.md

Report includes:

Summary statistics
TODOs sorted by age (oldest first)
Grouped by category
Author attribution

Utility Scripts

Script	Purpose
`find_todos.py`	Find all TODO comments
`analyze_staleness.py`	Git blame analysis
`generate_report.py`	Generate markdown report
`generate_html_report.py`	Generate interactive HTML report

Example

User: "Find forgotten TODOs in this project"

Run find_todos.py . → Finds 47 TODOs
Run analyze_staleness.py . → 12 are older than 1 year
Run generate_report.py . → Creates report with:
- 12 ancient TODOs (>1 year)
- 8 stale TODOs (6-12 months)
- 27 recent TODOs (<6 months)

Sample output:

## 🔴 Ancient TODOs (>1 year) - 12 found

| File         | Line | Age      | Author | Content                  |
| ------------ | ---- | -------- | ------ | ------------------------ |
| src/utils.py | 42   | 847 days | @alice | TODO: optimize this loop |
| lib/auth.js  | 156  | 623 days | @bob   | FIXME: handle edge case  |

Configuration

Filter by patterns or paths:

# Only FIXME and BUG
python scripts/find_todos.py . --patterns FIXME,BUG

# Exclude vendor directories
python scripts/find_todos.py . --exclude "vendor/*,node_modules/*"

# Only show TODOs older than 6 months
python scripts/analyze_staleness.py . --min-age 180

Related Skills

codebase-onboarding — Understand codebase before cleanup
incident-response-helper — Some TODOs may be related to incidents

Source

git clone https://github.com/dcs-soni/awesome-claude-skills/blob/main/stale-todo-finder/SKILL.mdView on GitHub

Overview

Stale Todo Finder scans codebases for forgotten TODO/FIXME/HACK comments and analyzes their age using git blame. It helps surface tech debt and plan cleanup by producing actionable reports. This aids code archaeology and maintainers in prioritizing fixes across languages like Python, JavaScript, Go, Java, and more.

How This Skill Works

The tool first scans the repository for common patterns (TODO, FIXME, HACK, XXX, BUG, OPTIMIZE) across languages such as Python, JavaScript, TypeScript, Go, Java, C/C++, Ruby, and Rust using find_todos.py. It then correlates each comment with git history via analyze_staleness.py to compute age, author, and file/line data. Finally, it categorizes items by age and generates a markdown or HTML report with an actionable backlog.

When to Use It

When you suspect legacy comments exist after refactors or partial rewrites
When planning a tech debt cleanup or refactor sprint
When auditing a codebase for forgotten tasks and improvements
When onboarding new contributors to align TODOs with current priorities
When preparing project health reports or PR backlogs for stakeholders

Quick Start

Step 1: Scan for TODO/FIXME/HACK patterns across the codebase using find_todos.py
Step 2: Analyze staleness with analyze_staleness.py to compute age and authors
Step 3: Generate a report with generate_report.py (or HTML) to share with stakeholders

Best Practices

Run find_todos.py across the repo to surface all patterns: TODO, FIXME, HACK, XXX, BUG, OPTIMIZE
Use analyze_staleness.py with --min-age to focus on older items and reduce noise
Exclude generated or vendor directories to avoid false positives
Cross-check results with git blame to verify authorship and add context if needed
Export reports with generate_report.py or generate_html_report.py for sharing with teams

Example Use Cases

Discover 12 ancient TODOs (>1 year) across core modules and prioritize fixes
Identify hotspots by file and author pairs to assign clean-up tasks
Generate a markdown backlog report for a sprint planning meeting
Produce an HTML report for engineering leads to review tech debt risk
Archaeologically trace legacy comments to understand historical decisions

Frequently Asked Questions

Add this skill to your agents