todo-scan

name	todo-scan
description	Use when user wants to Scan the repo for TODO code comments, TODO-titled GitHub issues, and predict the next best work item to tackle. Reusable across any git repository.

TODO Scan + Next-Step Predictor

You are performing a structured triage of outstanding work for the current repository. Execute all three phases, then synthesize a recommendation.

Phase 1 - Code TODOs

Find all TODO/FIXME/HACK/XXX annotations in tracked source files:

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
cd "$REPO_ROOT"

# Search source files, exclude common noise dirs
git grep -n --no-color -E "(TODO|FIXME|HACK|XXX)\b" \
 -- ':!*.lock' ':!node_modules' ':!.git' ':!dist' ':!build' ':!__pycache__' ':!*.min.js' \
 2>/dev/null | head -80

Group results by file. For each TODO, note:

• File path + line number
• The full comment text
• The surrounding function/class if determinable from context

Phase 2 - GitHub Issues with TODO in Title

Check if the gh CLI is available and the repo has a GitHub remote:

Detect GitHub remote

GH_REMOTE=$(git remote -v 2>/dev/null | grep -oP '(?<=github.com[/:])[^/]+/[^\s.]+' | head -1)

if command -v gh >/dev/null 2>&1 && [ -n "$GH_REMOTE" ]; then echo "=== Open issues with TODO in title ===" gh issue list --search "TODO in:title" --state open --limit 20
--json number,title,labels,assignees,createdAt
--jq '.[] | "#(.number) [(.labels | map(.name) | join(", "))] (.title)"' 2>/dev/null ||
gh issue list --search "TODO in:title" --state open --limit 20 2>/dev/null

echo "" echo "=== Open issues with FIXME in title ===" gh issue list --search "FIXME in:title" --state open --limit 10
--json number,title --jq '.[] | "#(.number) (.title)"' 2>/dev/null else echo "gh CLI not available or no GitHub remote detected. Skipping issue search." echo "Remote detected: ${GH_REMOTE:-none}" fi

Phase 3 - Predict Next Work Item

Gather signals about recent activity and open work:

echo "=== Recent commits (last 10) ===" git log --oneline -10 2>/dev/null

echo "=== Uncommitted changes ===" git status --short 2>/dev/null

echo "=== Most-changed files (last 30 days) ===" git log --since="30 days ago" --name-only --format="" 2>/dev/null |
grep -v '^$' | sort | uniq -c | sort -rn | head -15

echo "=== Open PRs (if gh available) ===" command -v gh >/dev/null 2>&1 &&
gh pr list --state open --limit 10
--json number,title,isDraft
--jq '.[] | "#(.number)(if .isDraft then " [DRAFT]" else "" end) (.title)"' 2>/dev/null ||
echo "gh not available"

echo "=== Failed CI on recent commits (if gh available) ===" gh run list --limit 5 --json conclusion,name,headBranch
--jq '.[] | select(.conclusion == "failure") | "(.name) on (.headBranch)"' 2>/dev/null || \

Synthesis

After collecting all three phases of data, reason through the following and produce a structured report:

1. TODO Inventory

List all code TODOs grouped by severity:

• Critical (FIXME, HACK with production impact)
• Normal (TODO with clear scope)
• Minor (XXX, style/cleanup notes)

2. Issue Backlog

List any GitHub issues found, noting if they overlap with code TODOs.

3. Next-Step Prediction

Apply this heuristic to pick the single best next item:

• TODO is in a file modified in the last 7 days: High - already in context
• TODO is in a hot-path file (high commit frequency): High - high-impact area
• TODO corresponds to an open GitHub issue: High - tracked and expected
• FIXME or HACK tag: High - indicates known debt
• PR is open touching the same file: Medium - coordinate, don't duplicate
• TODO is in test files only: Low - not blocking

Output format:

TODO Scan Report - REPO_NAME - DATE

Code TODOs (N_FOUND found)

• [CRITICAL] src/foo/bar.py:42 - FIXME: null check missing before deref
• [NORMAL] src/baz/qux.py:17 - TODO: add retry logic for API timeout ...

GitHub Issues (N_FOUND found)

• #123 [bug] TODO: fix login race condition

Recommended Next Step

FILE:LINE - TODO_TEXT Reason: 1-2 sentence explanation using signals above

Alternatives:

1. SECOND_CANDIDATE
2. THIRD_CANDIDATE

Notes

• Works on any git repository - no project-specific config needed
• If gh is unavailable, Phases 2 and CI checks are skipped gracefully
• Adjust head -80 limit in Phase 1 for very large repos
• Run with /todo-scan or ask Claude to "scan todos and predict next step"