Step 6: Run a doctor

Links break when files move, filenames drift, and active/ slowly fills with abandoned work. A small doctor command can find those mechanical problems at any time. It reports what it sees; it does not block the work. The agent fixes problems introduced by the current session and brings judgment calls to you.

You’ve met this before. This is linting, pointed at prose and structure, and it’s the vault edition of the coding-agents guide’s turn checkable rules into checks: rules a script can check shouldn’t stay prose. It’s also where the verification loop reaches the vault, founding incident included: the first version of a doctor script once reported “0 broken links” because its own path handling was broken. Plant a known-bad file and watch the probe fail before you trust its pass.

What it checks (start with three)

Broken links: internal references to files that moved or died.
Naming drift: files violating the kebab-case convention.
Stale actives: anything in active/ untouched for 30+ days, as candidates for the later/ sweep (step 2).

Frontmatter validity, empty stubs, orphaned files with no inbound links: all natural additions later, once the first three have run for a while. It’s a small tool: one job, boring interface, no policy baked in. The thresholds live in how you call it (the small-tools rules, applied).

Try it

TRY IT The doctor's first run

you

Write that doctor script for the vault: broken links, bad filenames, stale actives.

agent

Written: scripts/doctor.py, three checks, advisory output. Now comes the moment that decides whether we can ever trust it.

Pick the agent's next move, then see where it leads:

AFirst run on the vault: zero findings across all three checks. Clean bill of health. Nice, your vault's in better shape than you thought!

you

Months later: I just clicked three dead [[wikilinks]] in one afternoon. The doctor's been saying clean this whole time.

agent

Found it: my link regex only matched standard markdown links. [[wikilinks]] never matched anything, so that check has scanned zero of them since day one. "0 broken links" was the check being blind, not the vault being healthy. A years-old vault scoring perfect on its first scan should have been the tell.

the baseline

The clean first run, trusted: a probe that reports zero findings on its maiden voyage is broken until proven otherwise. Celebrating it shipped a blind checker as a health system. AF-01

BBefore trusting it: planting a note with a deliberately broken [[wikilink]] and a file named With Spaces.md. The doctor has to catch both, or it can't catch anything.

agent

First run: caught the bad filename... missed the planted wikilink. The regex only handled markdown links. Fixed, re-run: both plants flagged. Removing the plants; the honest run finds 11 real broken links and 3 stale actives. The 11 are real: I checked four by hand.

you

So the plant caught the blind spot before the blind spot cost anything.

correct

The probe was proven able to fail before its pass meant anything, and the plant immediately caught a real blind spot. The 11 findings are trustworthy precisely because the zero wasn't trusted. AF-01 · AF-02

CTo make sure vault health actually stays enforced, I'll wire the doctor as a pre-commit gate: any finding blocks the commit until fixed. No rot can ever land.

you

I just tried to commit today's log and it's blocked by 14 findings in notes from 2024.

agent

The gate holds today's work hostage to history's debt, and you've started committing with --no-verify to get past it, which means the doctor now runs never instead of always. The gate converted an advisory habit into a bypassed obstacle.

plausible but wrong

Gate-ification: blocking commits on advisory findings taxes the wrong moment and teaches routing-around. The doctor is taste infrastructure: it reports, the human decides, and it keeps getting run because it never bites.

The cadence

After any session that moved things: scope the check to what changed, fix what the session broke. Same-session, while the context is warm.
Weekly-ish, the full sweep: the agent runs it, fixes the mechanical findings, and brings you only the judgment calls (probable-stale actives, ambiguous link targets).

Try it with your agent

Write scripts/doctor.py for my vault: python, stdlib only. Checks:
(1) broken internal links (markdown links and [[wikilinks]] pointing
at files that don't exist), (2) filenames violating kebab-case,
(3) files in active/ not modified in 30+ days. Output: one finding
per line with the file path and a one-line fix suggestion; exit 0
always. Findings are advisory, not failures. Include --scope <dir>
to limit a run to what a session touched. Before we trust it: plant
a deliberately broken link and a badly named file, run the doctor,
and show me it catches both; then remove the plants, run it clean,
and fix anything real it found. Add to the supported project
instruction file: after any session that moves or renames files, run
the doctor scoped to what changed and fix findings that session
introduced.

Watch out

The clean first run: a doctor that reports zero findings on a vault of any age is broken until proven otherwise. Plant the bad file first. The founding incident of this step is exactly this.
The doctor becoming a nag: findings you’ve decided not to fix (that one legacy folder with spaces) need an ignore mechanism, or the report becomes noise and stops being read.
Gate-ification: the moment the doctor blocks a commit, filing starts routing around it. Advisory forever: this is taste infrastructure, not CI.