Codebase Tasks

Codebase Task Finder

Scan the codebase for work that should be done — TODOs, fixmes, tech debt, dead code, missing error handling at boundaries, and low-hanging improvements. Prioritize by impact and effort, and optionally fix the quick wins.

Input: "$ARGUMENTS"

Workflow

1. Determine Scope

• If a path or scope is provided (e.g., apps/sync, packages/, src/), limit the scan to that area
• If no scope is provided, scan the full repo but focus on src/, apps/, packages/, lib/ — skip node_modules, dist, .next, vendor directories

2. Scan for Explicit Markers

Search for developer-left markers:

# TODOs and FIXMEs
grep -rn "TODO\|FIXME\|HACK\|XXX\|TEMP\|WORKAROUND" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.go" --include="*.py" <scope>

# Disabled or skipped tests
grep -rn "\.skip\|xdescribe\|xit\|@skip\|@disabled" --include="*.test.*" --include="*_test.*" <scope>

# Commented-out code blocks (3+ consecutive commented lines)

3. Scan for Implicit Issues

Read key files and look for:

Dead code:

• Exported functions/types that are never imported elsewhere
• Unused variables flagged by linter configs but not yet cleaned up
• Files that haven't been modified in 6+ months and aren't referenced

Error handling gaps:

• Empty catch blocks
• Caught errors that are silently swallowed (no log, no rethrow)
• API endpoints without try/catch at the handler level

Consistency issues:

• Mixed patterns in the same directory (some files use one approach, others use another)
• Duplicated logic that could be a shared utility

Dependency concerns:

• Check package.json or equivalent for packages with known deprecations
• Major version bumps available for key dependencies

4. Prioritize

Categorize each finding:

5. Present Findings

# Codebase Tasks — [repo/scope]

## TLDR
[X] items found: [Y] quick wins, [Z] should-do, [W] consider

## Quick Wins (fix now)
| # | File:Line | Issue | Effort |
|---|---|---|---|
| 1 | src/api/handler.ts:42 | Empty catch block swallows auth error | 2 min |
| 2 | lib/utils.ts:15 | TODO from 6 months ago — dead code below | 1 min |

## Should Do (schedule)
| # | File:Line | Issue | Effort | Impact |
|---|---|---|---|---|
| 1 | apps/sync/worker.ts:200 | Retry logic has no backoff | 30 min | Reliability |

## Consider
- [Lower priority items, briefly listed]

## Skipped
- [Items that look like issues but are intentional, with a note why]

6. Fix Quick Wins (if --fix flag passed)

If the user passed --fix:

• Fix each quick win (empty catches, dead TODOs, obvious dead code)
• Stage the changes
• Create a commit per logical group of fixes
• Push to a new branch and put up a PR
• Follow the repo's CLAUDE.md commit format and branch naming

If --fix was NOT passed, just present the findings.

Rules

• Don't flag style preferences — only flag things that are objectively improvable
• Don't flag things a linter or type checker would catch — assume those run in CI
• TODOs with context ("TODO(alex): revisit after Q2 migration") are lower priority than naked TODOs
• If the repo has a CLAUDE.md, respect its conventions for what counts as an issue
• Dead code removal should be verified — check imports and references before flagging
• When fixing, keep changes minimal — fix the issue, don't refactor the neighborhood