# Docs Audit

> Use when a repository with docs/index.json needs judgement about what its documents still claim — a periodic docs review, "are these docs stale", a plan that says it is done, an unverified state document, a review_by date that passed, a change that may have invalidated documents. Not for sorting (docs-sort), moving (docs-promote) or a red gate (docs-gate).

- Skill: `magnifito/docs-audit` (Agent Skill)
- Install (CLI): `npx skillmds@latest add magnifito/docs-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/magnifito/docs-audit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: magnifito (https://skillmd.com/u/magnifito)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/magnifito/docs-audit

---


# Audit the documents

The gate proves the tree is well-formed. It cannot prove a document is true. This skill is the
part that needs a reader: run the three reporting commands, then decide, document by document.

## 1. Run the three reports

```bash
docs-notary advisory                 # updated-drift, code-pointer, verification-drift
docs-notary check                    # warnings: shipped-code, upstream, review, evidence-lock
docs-notary impact --base <ref>      # documents whose claims cover the paths a change touched
```

Run these as `npx docs-notary …` (npm install) or `node scripts/<script>.mjs` (vendored — the script names differ from the command names: `check` is `check-docs.mjs`, `new` is `new-doc.mjs`, `mv` is `mv-doc.mjs`, `gen` is `gen-docs-index.mjs`); a bare
`docs-notary` is on PATH only inside an npm script.

`advisory` and `impact` never block; `check` blocks only on its errors — the four warnings named
above print and exit 0 either way. `advisory`'s headline for each rule carries the id, with the
documents it found indented below; `check`'s lines each carry their own id; `impact`'s lines carry
no id at all. Group the output by document before deciding; one file often trips three rules for
one cause.

## 2. Verify before you believe

Before claiming a state document is current, run its evidence:

```bash
docs-notary verify --only docs/<tier>/<name>.md --stamp
```

It runs the document's command evidence, hashes its path evidence into `<docsDir>/evidence-lock.json`,
and stamps `verified_on` only where everything passed — a date you can defend instead of one you
typed. It skips a document with no `evidence:` list entirely, so it can never clear
`verification-drift` on one that has `code:` but no evidence — add an `evidence:` entry, or move
`verified_on` only after checking the code by hand. It is the only
command that executes anything written in a document: the gate never runs it, the edit hook never
runs it, and `docs-notary init` wires no script to it — a consumer's CI runs it only if someone
adds that step by hand (this tool's own CI does, as a smoke test on the installed package). Invoke
it deliberately, and **read the evidence lines of an untrusted document first**. Never run `verify`
on a branch you have not read.

## 3. Decide, per document

| The report says | Do |
|---|---|
| `updated-drift`: the document was committed after its `updated:` date | Read the diff since that date. Bump `updated` if the edit was substantive; otherwise leave it — a whitespace or generated-file commit does not need a new date. |
| `code-pointer`: a `code:` path is gone | Find the new path and fix it, or remove the claim. A `shipped` document with no `code:` is an opinion. |
| `verification-drift`: on a `kind: state` document, the `code:` path was committed after `verified_on` (the default tiers produce no `state` kind) | Re-run `verify --only … --stamp`. If it fails, the document is wrong, not the lock. |
| `evidence-lock`: path evidence changed since `verify` hashed it | Same: re-run `verify --only … --stamp`, and read why it moved. |
| `review` (`review_by` in the past) | Re-verify the claim. Move the date only after the check, never before. |
| `upstream` (`implements` target moved on) | Read the target's change. Update this document or record why it does not apply. |
| `shipped-code` | Add `code:` with a real path, or the status is `active`, not `shipped`. |
| A plan says "done" with untaken steps | It is a live backlog. Keep `active`. |
| A plan is done and its work shipped | `status: shipped` with `code:` and `evidence:`; else keep `active` and say what is missing. |
| A document's first line says SUPERSEDED | docs-promote: supersede and archive. |
| Two documents make the same claim | Keep the higher tier. Supersede the other (docs-promote). |

Never stamp `shipped` on the strength of a plan's own prose. Never delete a document to make a
report shorter — tier it or archive it, unless the user answered "yes" to deletion when the system
was adopted.

## 4. Report to the user

List what you changed, what you verified and how, and the claims nobody could check with their
cost to check. A claim you could not verify stays unverified in the frontmatter — a `verified_on`
you did not earn is worse than none.

## 5. Before you finish

```bash
docs-notary gen
docs-notary check     # every restamp must still pass the gate
```