code-health-audit

Code Health Audit

A repeatable sweep for dead code, overengineering, and embarrassing/inconsistent patterns. The point isn't to list everything wrong — it's to ship a handful of high-value, low-risk simplifications with a net-negative line count and a green test suite.

The distinctive value of this skill is the pre-flight (Phase 0). Most audit rework comes from auditing the wrong branch or a stale worktree copy, then building changes that were already merged or that don't match the live code. Do Phase 0 first, every time — don't skip it because you "know" the state.

Phase 0: Pre-Flight — Get the Working State Right

1. Sync the correct base branch

Audits run against the integration branch, not whatever happens to be checked out. Confirm the base (usually develop; main if there's no develop) and sync it:

git fetch --prune
git rev-parse --abbrev-ref HEAD          # what am I on?
git checkout [BASE_BRANCH]
git pull --ff-only
git rev-list --count HEAD..origin/[BASE_BRANCH]   # 0 == up to date

If that count isn't 0 after a pull, stop and sort out why before auditing. Never audit or build against a stale local checkout — that's the single most common way this work gets wasted.

2. Confirm the active worktree and its dev server

If the repo uses git worktrees, know which one you're in and which dev server is actually live — verification later has to hit the checkout you're editing, not a stale server from another worktree:

pwd
git rev-parse --show-toplevel            # the worktree you're editing
git worktree list
lsof -i -P | grep LISTEN | grep node     # which dev server(s) are up, on which ports

Make sure the dev server you'll verify against is serving this worktree. If it's serving a different checkout, restart it here or note the right URL.

3. List the files in scope and confirm

Before scanning, state what you're auditing (a directory, a domain, the whole src/) and list the files so the user can confirm you're pointed at the right code. A one-line scope check here prevents a whole audit aimed at the wrong area.