Techdebt

Tech Debt (/techdebt)

End-of-session codebase cleanup scan.

When to Use

• End of a coding session
• Before creating a PR
• Periodic hygiene check
• After a big feature merge

Instructions

When the user invokes /techdebt:

Step 1: Identify Scope

Determine what to scan:

# Files modified this session (since last commit on main)
BASELINE=$(git merge-base HEAD main 2>/dev/null || echo "HEAD~10")
git diff --name-only $BASELINE HEAD
git diff --name-only  # Unstaged too

If no changes, scan the whole project's src/ directory.

Step 2: Run Parallel Scans

Scan 1 — TODOs and FIXMEs (grep for actionable items):

grep -rn "TODO\|FIXME\|HACK\|XXX\|WORKAROUND" src/ --include="*.ts" --include="*.tsx"

Categorize each:

• Stale (> 30 days, check git blame)
• Actionable now ( 30 days old per git blame)
• Remove unused local variables
• Fix obvious type narrowing gaps

Step 4: Report

## Tech Debt Report

### Auto-Fixed
- Removed N unused imports
- Deleted N lines of dead code
- Fixed N type issues

### Needs Attention
| File | Issue | Effort |
|------|-------|--------|
| src/foo.ts:42 | Stale TODO from 2 months ago | 5 min |
| src/bar.ts:17 | Type assertion could fail | 15 min |

### TODOs Summary
- N stale (> 30 days)
- N actionable now
- N need tickets

### Health Score: X/10

Step 4b: Research Artifact Index Sweep

Check for new files in ~/.claude/artifacts/research/ that aren't in ~/.claude/artifacts/research/INDEX.md:

# Find files newer than INDEX.md
find ~/.claude/artifacts/research/ -name "*.md" -newer ~/.claude/artifacts/research/INDEX.md ! -name "INDEX.md" 2>/dev/null

If any unindexed files found, append them to the appropriate section in INDEX.md with channel tag. Report: "INDEX.md: added N new research artifacts."

Step 5: Offer Next Steps

Would you like me to:
A) Fix the "Needs Attention" items now
B) Create GitHub issues for the complex ones
C) Just note it and move on

Arguments

| Arg | Effect | |-----|--------| | --fix-all | Auto-fix everything safe, no prompt | | --report-only | No fixes, just report | | --scope "dir" | Scan specific directory |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Lucface
• Source: Lucface/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.