drift-audit
Every self-description, checked against the repo
The build checks catch what a script can check. The drift-audit skill covers the layer beneath them: prose that makes a claim about the system, and instructions that only fail when someone follows them. It changes nothing on its own. super-ship runs it as its first audit and repairs what it finds. Below are the steps, then one renamed route traced from the change to the report. The full skill file is on Skills.
The steps
- Establish what is true nowRun
npm run validate-registry, list the scripts and the exports map, and read the recent commits. The chain writes generated files, so checkgit statusbefore and after. If the chain fails, stop and report that first. - Run the mechanical cross-checksEvery script a doc names exists, in the right workspace. Every path exists. Every import matches the exports map. Every internal link reaches a real page. Counts come from registries. Retired wording has left the generated files. Config still sits where its tool reads it.
- Read the prose surfacesREADME first, since it ships to npm. Then the registries that ship as prose,
CLAUDE.md,design.md,content-design.md, the other root specs and the pages that say how the system is built. The test: would a stranger who followed this succeed, and believe only true things? - Follow the change-type playbookThe recent commits say what kind of change landed. An API change, a token change and a route change each have surfaces that must have moved with it, and the audit checks all of them.
- Audit every skillRead every skill, not just the related ones. Where a skill scripts a recipe with several steps, run it in a throwaway place and clean up. Then look for a repeated workflow that has no skill yet.
- Check what ships and what is publicInspect the built package: its manifest, its files, its size and the docs inside it. Sweep for secrets, personal data and local paths, and say which public identifiers are public on purpose.
- Report, then askFindings grouped by severity, each with its path, what it says, why that is wrong now and the fix. A coverage table marks each section as executed, read or skipped. Then the audit asks whether to apply the fixes.
A renamed route, end to end
A route change is one of the playbook’s kinds. The audit reads the nav, the sitemap, llms.txt, the page summaries and the corpus route lists for it, and every skill and spec as it always does. Each finding is sorted into one class and goes into the report before anything is fixed.
What each class means
The report is the deliverable. Some findings are judgement calls, so the owner decides which fixes to apply.
| Finding | What it means | What happens next | Class |
|---|---|---|---|
A skill names a script that no longer exists | Following it would fail | Fixed at the source once the owner agrees | Broken |
A doc describes a folder that moved | Inaccurate, so it would mislead | Fixed at the source once the owner agrees | Stale |
A repeated workflow with no skill | Missing coverage | Reported, since it may be deliberate scope | Gap |
A surface that still matches | Checked and found correct | Named, so the reader knows the scope | Verified |
A section not run in full | Weaker evidence than a run | Marked in the coverage table with a reason | Skipped |