# Codebase Tasks

> Scan a codebase for TODOs, tech debt, and improvements — prioritize and optionally put up PRs for the quick wins

- Skill: `dylanpulver/codebase-tasks` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add dylanpulver/codebase-tasks`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dylanpulver/codebase-tasks/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dylanpulver (https://skillmd.com/u/dylanpulver)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dylanpulver/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:

```bash
# 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:

| Priority | Criteria |
|---|---|
| **Quick win** | Can be fixed in <10 lines, no risk, clear improvement |
| **Should do** | Real issue, moderate effort, worth scheduling |
| **Consider** | Valid improvement but low urgency |
| **Skip** | Noise, intentional tech debt, or not worth the effort |

### 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