Codebase Audit

Systematic review of the entire codebase to identify cruft, outdated content, and issues before release. Uses parallel exploration for discovery, then interactive triage for decisions.

When to Use

• Pre-release cleanup
• Periodic codebase health check
• After major refactoring
• When onboarding to understand technical debt

Workflow

Phase 1: Discovery (Parallel Exploration)

Launch 5 parallel Explore agents to review different areas:

Task tool (subagent_type: Explore) - run all 5 in parallel:

1. DOCS: Review *.md files for outdated content, stale TODOs,
   inconsistencies, wrong command syntax, aspirational features
   documented as current

2. CODE: Review src/ for dead code, unresolved TODOs/FIXMEs,
   duplicate functions, commented-out code, debug artifacts,
   unused imports/exports

3. CONFIG: Review package.json, tsconfig, etc. for unused deps,
   misplaced deps (dev vs prod), broken scripts, stale configs,
   version drift

4. TESTS: Review tests/ for skipped tests, dead mocks, duplicate
   test names, flaky patterns, missing coverage, outdated fixtures

5. SPECS: Review .kspec/ for stale spec items, orphaned tasks,
   status mismatches, empty stubs, inbox items that should be
   promoted, accumulating session files

Each agent should report findings with:

• File and location
• What the issue is
• Why it's cruft (outdated, redundant, broken, etc.)
• Recommended action

Phase 2: Compilation

Organize all findings by severity:

Severity	Criteria	Examples
CRITICAL	Blocks release, breaks functionality	Runtime deps in devDeps, security vulns, broken required scripts
HIGH	Should fix, user-facing or misleading	Wrong docs, incorrect command syntax, misleading task statuses
MEDIUM	Recommended, technical debt	Unresolved TODOs, duplicate code, test improvements
LOW	Nice to have, minor cleanup	Doc cross-refs, test name clarity, helper consolidation

Present compiled summary to user before triage.

Phase 3: Triage (Interactive)

Go through items one-by-one using AskUserQuestion:

For each item, present options:

- Fix now      → Execute the fix immediately
- Task         → Create task with context notes
- Inbox        → Add to inbox for later review
- Punt         → Skip, not worth tracking
- Discuss      → Need more context before deciding

Triage principles:

• One item at a time (don't batch)
• User decides disposition
• Execute decisions immediately
• Add context notes to tasks/inbox

Phase 4: Execution

For each decision type:

Fix now:

# Delete dead files
rm path/to/dead-file.js

# Quick edits
# Use Edit tool for small fixes

# Commit cleanup changes at end
git add -A && git commit -m "chore: Audit cleanup - [summary]"

Task:

kspec task add --title "Description" --priority N --slug slug-name --tag relevant-tag
kspec task note @slug "Context: file location, what needs doing, why"

Inbox:

kspec inbox add "Description of item for later" --tag tag1 --tag tag2

Phase 5: Summary

At end of triage, report:

## Audit Summary

### Fixed Now
- Item 1
- Item 2

### Tasks Created (N)
| Task | Priority | Description |
|------|----------|-------------|
| @slug | PN | Brief description |

### Inbox Added (N)
- Item description

### Punted (N)
- Reason for each

### Remaining
- Any items not yet triaged

Commit any direct fixes made during audit.

Key Principles

• Parallel discovery - Explore agents run concurrently for speed
• Severity-first - Critical items get triaged first
• Interactive triage - User controls every decision
• Immediate execution - Don't batch, act on each decision
• Full tracking - Everything either fixed or tracked
• Clean commit - End with committed state

Quick Reference

# Get session context first
kspec session start

# After triage, commit fixes
git add -A && git commit -m "chore: Audit cleanup"

# Create task with context
kspec task add --title "..." --priority N --slug slug --tag tag
kspec task note @slug "Context..."

# Add to inbox
kspec inbox add "Description" --tag tag

# Check what was created
kspec task list --status pending
kspec inbox list

Exploration Prompts

Use these prompts for the parallel Explore agents:

Docs:

Review documentation files for cruft in preparation for release. Look for: outdated content, stale TODOs, inconsistencies between docs, wrong command syntax, features documented that don't exist. Check README.md, AGENTS.md, CLAUDE.md, and other .md files.

Code:

Review src/ directory for code cruft. Look for: dead code, unused exports, unresolved TODO/FIXME comments, duplicate functions, commented-out code, debug artifacts, unused imports. Note file paths and line numbers.

Config:

Review configuration files for cruft. Look for: unused dependencies, misplaced deps (devDeps vs deps), broken npm scripts, stale tsconfig/eslint options, version inconsistencies. Check package.json, tsconfig.json, and config files.

Tests:

Review tests/ for cruft. Look for: skipped tests (.skip/.todo), dead mock files, duplicate test names, flaky patterns, missing coverage, outdated fixtures. Verify temp directory isolation pattern.

Specs:

Review .kspec/ for spec and task cruft. Look for: stale spec items, orphaned tasks, incorrect statuses, empty stubs, inbox items that should be promoted, tasks with empty slugs.

Tips

• Run tests before and after to catch regressions
• Check git status frequently during fixes
• For complex fixes, create tasks rather than fixing inline
• Group related fixes in a single commit
• If unsure about a fix, punt and discuss later