Which of Your Obsidian Notes Is Claude Getting Wrong?

Hello builders,

By tonight you can hand a teammate a dated file naming every page in your vault they could catch you out on, and almost nobody in this space can currently produce one. Mine came back with seventeen findings across two hundred and fourteen pages, and I would have bet money on maybe two. Search “find stale notes obsidian vault” and you will get plugins that reindex files by modification date, when what we actually want is one read-only pass that puts two disagreeing files on the same screen and writes down what it saw.

What makes it a finding

Look at finding 3 above, because the shape is the whole idea. The page says the project deploys by running deploy.sh from the project root. Source A is sources/repo/.github/workflows/deploy.yml, where the deploy runs on push to main. Source B is a standup transcript in which somebody says out loud that they are off deploy.sh as of that day.

Both of those files had been sitting in my vault for four months. Nothing was corrupted and nothing was hidden. We’d simply never run a process that put the two of them on the same screen.

That is all a sweep does. It reads two files in one pass that nothing had ever read together.

The header block is not decoration either. By class: contradicted 4 · duplicate 7 · stale 3 · orphaned 2 · dead-ref 1 and By confidence: high 6 · medium 8 · low 3 are the only two lines we compare across runs, and both foot to seventeen. Finding 3 earns its high mark for a stated reason: both sources are present in the vault and the field is typed on both.

The four callouts in the margin are the parts we should steal. Source A and Source B are there because a finding you have to go re-derive is a finding you will skip. The third points at deploy_path and says the typed field is what makes it a finding, which is the rule that keeps the report honest: same entity, same typed field, two values. Similar wording is not a finding, and a report full of pages that are merely about similar subjects is one we will skim once and never open again.

The fourth callout is the one people argue with. It points at backlinks: 9 and reads ordered by traffic, not by age. Sort your findings by how many pages link in, not by how long it has been since anyone touched the file. A page nobody opens can sit there wrong for a year and cost you nothing. The page everybody opens is the one that stays wrong longest, because its popularity implies that somebody else already checked it.

The sweep writes one file

Save this as pages/SWEEP.md so it is version controlled and so the scheduled version later runs the same file rather than a retyped approximation of it.

# Sweep (read-only)

You may READ anything. You may WRITE exactly one file: `reports/rot-report.md`.
Any other write is a bug, not a judgment call.

Scope: every page in `pages/`. Order by inbound backlink count, descending.

For each page, look for:
1. stale        : decay class exceeded since last verification
2. contradicted : same entity + same typed field, two sources, two values
3. duplicate    : page holds its own copy of a status/date/owner/version that
                  is authoritative elsewhere in the vault
4. orphaned     : provenance inferred, or a source_ref that no longer resolves
5. dead-ref     : external reference gone, or content hash changed since cited

Rules:
- A contradiction requires the SAME entity and the SAME typed field. If you are
  matching on prose overlap, stop.
- Every finding cites BOTH sources by path, with the conflicting values quoted.
- You are NOT correcting anything. Do not propose diffs. Report only.
- Head the report with the run number and the date you ran it.

Then we run it, and we run it locked down:

claude -p "$(cat pages/SWEEP.md)" --permission-mode dontAsk

dontAsk denies anything you have not explicitly allowed, and it means that literally, so we give it read on the two layers and write on the one report:

{
  "permissions": {
    "allow": ["Read(pages/**)", "Read(sources/**)", "Edit(reports/**)"],
    "deny": ["Edit(sources/**)"]
  }
}

Watch the first few findings scroll past, and kill the run if it starts proposing edits. That means our prompt lost, and it is cheaper to fix the prompt than to review a bad report.

Prior art, and its hole

Somebody already shipped a version of this and you should install it. claude-obsidian ships fifteen skills under an MIT license, one of them called wiki-lint, and its own instruction file is unusually honest about its limits:

Use the portable lint engine as the source of truth. Lint observes vault state; it does not create reports, dashboards, canvases, stubs, or fixes.

Report only the checks and counts present in its output; do not claim that it performed semantic, stylistic, or prose-level contradiction analysis when it did not.

Read that second line twice, because it is telling us exactly what we still have to build. wiki-lint finds dead links, orphan pages, frontmatter gaps and stale index entries, and it says in writing that it does not do contradiction analysis. It also refuses to repair anything: “Never auto-fix a lint result.” That’s the right instinct and it matches ours.

What it cannot give you is a dated file you can diff against last month’s. A lint pass emits findings for right now, nothing accumulates, and we cannot tell whether the vault is improving or whether we are just running the checker more often. Run both, and keep the file you can edit.

Fix nothing on run one

You’re about to have seventeen findings and an agent that could clear all of them in four minutes. That’s the exact moment every horror story in this topic starts, so our first pass writes nothing.

Pick one high-confidence finding and correct it by hand, start to finish, and time it. Mine came in around eleven minutes for a contradicted page with a handful of backlinks. Seventeen of those is a bit over three hours, which isn’t an afternoon I was willing to spend every month, and that one number is the entire argument for letting us schedule the sweep later.

If your report comes back with two low-confidence findings, that’s a real result and we shouldn’t go looking for something to be wrong. It usually means your vault is young, or small enough that you are still holding it in your head, or made mostly of reference material that rots slowly.

Your vault already contained everything needed to know that page was wrong. What it lacked was a process that put the two files next to each other.

Now go build something this weekend!

John Cook