A Claude Code skill · open source
codebase-audit
Find out what is true about a codebase before changing it at scale, with evidence you can check, and turn it into work in an order that is safe to build.
Nine read-only agents read the code through nine lenses at once. One session reads all nine reports and writes the plan's spec: what several lenses found on their own, the bugs already shipped, and the axes of work in dependency order. You make the calls; dot-plan builds it.
/plugin marketplace add khairold/skills
/plugin install khairold@khairold
/khairold:codebase-auditPart of khairold/skills, with dot-plan and agent-guides. MIT licensed.
The idea in five lines
- Evidence is file:line. What was only read says so. What was not looked at is named, so silence is not taken for clean.
- Read-only until you decide. The audit writes its reports and nothing else.
- Many lenses, one picture. Each lens gets a fresh agent. A problem three of them flag on their own is a real one.
- Invariants over symptoms. "The header showed the wrong language" is a bug. "Every date format passes the locale" is something you can search for.
- Guidance, not checklists. The lenses are questions worth asking. The agent picks the ones that fit and adds the one your codebase needs.
Modes
/codebase-audit
Survey, one agent per lens in parallel, the reports folded into axes of work, your decisions, then a hand-off to a build plan.
You pick the lenses and decide/codebase-audit "<bug class>"
One bug that keeps coming back. The invariant it breaks, parallel sweeps, the bugs and risks, small fixes, the rule written down.
You confirm the axes and fixes--check
Either mode, reading only. The synthesis in chat, no files written.
You read itThe nine lenses
The default set. A small service may need four; a large monolith all nine and one of its own.
Boundaries
Who imports whom, the cycles, the hidden edges, and the orchestration that has no home.
State
Every write of a status, its guard and its lock; the transition graph the code really allows.
Writes and sensitive data
Who writes each table, what the audit trail misses, every read of personal data, what survives a delete.
Module shape
Logic in the wrong layer, files that always change together, duplication, names that trip people.
Tests
Coverage, speed, fragility, and the behaviour a refactor could change without a test noticing.
Agent guidance
Stale claims, duplicated facts, what a cold agent reads. Runs agent-guides --check if installed.
Resilience
Each dependency down, slow or wrong; poison inputs; retries forever; the go-live risks, ranked.
Data model
Facts stored twice, ids that drift, constraints the code relies on and the database does not hold.
Types and errors
What crosses module borders untyped, loose strings for closed sets, broad and swallowed errors.
The full audit
- Survey. The parts, the data, the entry points, the dependencies, the tests, the guidance, the recent history. The commit it audits.
- Propose the lenses, then wait. Which to run and why, which to skip, what your codebase needs that the set lacks, and what you already know is wrong.
- Run the lenses in parallel, one read-only agent each, all at once. Each writes one report: findings rated High, Medium or Low, a target design, open questions.
- Fold into axes. One session reads every report and writes
AXES.md. - Stop for your decisions, grouped, each with a recommendation. The answers go under "Decided".
- Hand off. The reports and
AXES.mdare the spec for/dot-plan init.
| AXES.md | Holds |
|---|---|
| Convergence | problems flagged by three or more lenses on their own |
| Bugs in finished work | High and Medium, with file:line, fixed early with a test that fails first |
| The axes | each with what "done" looks like, its size and what it depends on |
| Suggested order | a safety net first, then the bugs, then the axes that unblock the most |
| Open decisions | every question from every report, grouped, each with a recommendation |
| Decided | your answers, dated, in your words |
A safety net first
The first axis is almost always the same: record what the code does today, whole, so every later change in behaviour shows up as a diff someone reads. Snapshots of each scenario's outcome, of every message sent, of each screen per role, of the prompts sent to a model; every rule with a case where it fires and one where it only just misses. A snapshot changes only on purpose, and the commit that changes it says why.
The drift sweep
For a bug that has shipped more than once, same shape in a different file.
- Confirm it recurs in the history. Once is a bug, not drift.
- Restate the bug as the rule it breaks. The rule is the search target.
- Widen, then narrow. At least ten candidate axes first, then the five to eight worth sweeping. You see both lists; the one you rescue is often the one that matters.
- Sweep in parallel, one agent per axis, each returning confirmed bugs, latent risks, a count, and the conventions worth keeping.
- Fix the small ones and write the rule down, in the guide of the folder it governs. Work that spans many files becomes a plan.
Where it came from
Before refactoring a Django monolith with agents, I ran nine audits in parallel, one per lens, and folded them into eleven axes of work. Seven problems were flagged by three or more audits on their own. Ten High bugs turned up in code that was already finished and tested. Each got a test that failed on the old code before it was fixed.
The axes became the phases of a dot-plan build that ran mostly unattended, safety net first. This skill is that audit, written down so it works on any codebase, with an older skill for recurring bugs folded in as the drift sweep.