Repo Doc-Reset Audit
Find dead links, stale blocked/TODO notes, missing README sections and duplicated facts in a git repo's docs after a rewrite, rename or file move. Audits repository documentation after a big rewrite or restructure. It finds dead relative links (ignoring code blocks and anchors), references to deleted or renamed files, READMEs missing agreed sections, stale 'blocked / waiting / TODO' notes, the same source-of-truth stated twice, live URLs worth re-checking (bot-blocks are labeled unverified, not dead), and history text that belongs in git log. Output is a P1/P2/P3 report with file:line evidence and a minimal patch list. It is read-only by default, never edits, commits or pushes unless asked, does not rewrite prose, and re-runs the checks to prove fixes after you apply them.
Example input
Use the Repo Doc-Reset Audit on this (a sample I wrote). I just restructured our docs repo (example-org/handbook). Agreed README shape per docs/CONTRIBUTING.md: "Purpose", "Status", "How to run", "Owner". Source of truth: support hours live only in docs/support/hours.md. Commit log (git log --name-status -n 3): a1f3c9e R docs/install.md -> docs/setup/install.md a1f3c9e D docs/faq-old.md 7be2d40 D docs/billing/legacy-invoices.md Tree: README.md, docs/CONTRIBUTING.md, docs/setup/install.md, docs/support/hours.md, docs/support/README.md, docs/billing/README.md README.md 3: Start with [installation](docs/install.md) or the [FAQ](docs/faq-old.md). 9: Support is open 9:00-17:00 UTC, Mon-Fri. docs/setup/install.md 12: Run `make install` (see [config](./config.md)). 20: TODO: blocked on the new CI runner, waiting for ops. docs/support/README.md 1: # Support 5: Hours: 8:00-18:00 UTC, Mon-Fri. 7: See https://status.example.com/ for outages. docs/billing/README.md 4: Old invoices: [legacy](legacy-invoices.md). We used to bill monthly before the migration. (ops note in docs/CONTRIBUTING.md:30: "CI runner migrated, done 2 weeks ago")
Example output
Summary: P1 6, P2 4, P3 2 across 6 files (pasted excerpts only; limited to what was pasted, so no commands were run and no files were modified). ## Scope - Doc set: README.md, docs/CONTRIBUTING.md, docs/setup/install.md, docs/support/hours.md, docs/support/README.md, docs/billing/README.md. Excerpts were available for 4 of them; docs/support/hours.md and CONTRIBUTING.md (beyond line 30) were not pasted. - Excluded: none stated. - Deleted/renamed (from the pasted log): R docs/install.md -> docs/setup/install.md (a1f3c9e); D docs/faq-old.md (a1f3c9e); D docs/billing/legacy-invoices.md (7be2d40). - Agreed README shape (CONTRIBUTING.md): Purpose, Status, How to run, Owner. - Source of truth: support hours live only in docs/support/hours.md. - Limits: anchors not checked, HTML links not followed, case-sensitive resolution. ## Findings ### P1 - README.md:3 — "[installation](docs/install.md)" — dead link; file was renamed to docs/setup/install.md in a1f3c9e. - README.md:3 — "[FAQ](docs/faq-old.md)" — dead link; file deleted in a1f3c9e. - docs/setup/install.md:12 — "[config](./config.md)" — dead link; no docs/setup/config.md in the tree. - docs/billing/README.md:4 — "[legacy](legacy-invoices.md)" — dead link; file deleted in 7be2d40. - docs/setup/install.md:20 — "TODO: blocked on the new CI runner, waiting for ops." — resolved-but-still-written; docs/CONTRIBUTING.md:30 says "CI runner migrated, done 2 weeks ago". - README.md:9 vs docs/support/README.md:5 — "9:00-17:00 UTC" versus "8:00-18:00 UTC" — two contradictory statements of support hours; neither file is the declared source (docs/support/hours.md, content not pasted). ### P2 - docs/support/README.md:1 — "# Support" is the only heading shown — missing agreed sections as far as the excerpt shows (Purpose, Status, How to run, Owner); excerpt may be partial. - docs/billing/README.md — no agreed headings visible in the excerpt (only line 4 pasted) — cannot tell. - README.md:9 and docs/support/README.md:5 — support hours restated outside the declared source of truth; they should link to docs/support/hours.md. - docs/setup/install.md:20 — TODO has no owner or date. ### P3 - docs/billing/README.md:4 — "We used to bill monthly before the migration." — history text that belongs in git log. - README.md:3 — mixed link style (`docs/install.md` without `./` versus `./config.md`) — hygiene. ## Unverified - https://status.example.com/ (docs/support/README.md:7) — not checked; no network used. If checked later, a 403/429/captcha or JS shell must be reported as "unverified: bot-block or SPA", not dead. …
Real output from running the skill on a sample problem, shortened. The skill file itself is not published here.