Find Dead Links and Stale Docs After Repo Rewrite

How it works

Repo Doc-Reset Audit is for the day after you restructure or rewrite a repository's documentation. It finds what the rewrite broke and what it left behind, and proposes minimal fixes without changing anything unless you ask.

Phase 1 — Scope. Which docs, which deleted or renamed paths, which README sections you agreed on.

Phase 2 — Safe checks. A read-only dead-relative-link snippet that ignores code blocks and anchors, plus a stale-marker search (blocked, waiting, TODO).

Phase 3 — Classify. P1 / P2 / P3 findings with file:line evidence; live URLs that returned 403 or 429 are never reported as dead.

Phase 4 — Patch list and re-check. Minimal edits as a numbered list you can approve, then a re-run to prove it is fixed.

Sample output

Real, unedited output from running this Skill on a sample problem:

Summary: P1 4, P2 2, P3 1 — 3 doc files scanned (README.md, docs/pricing.md, docs/api/README.md); audit limited to the pasted text.

## Scope
- Source: pasted tree and excerpts only; no repo access, no commands run, checks done by reading. Limits: `docs/install.md`, `docs/api/endpoints.md` and `scripts/seed.py` were not pasted, so their contents, links and README shape were not checked. No `git log` search was possible; the history comes from the two lines you gave.
- Deleted or renamed paths searched for: `docs/pricing-old.md` (deleted), `guides/setup.md` (renamed to `docs/install.md`), `guides/` (merged into `docs/`).
- Agreed README shape: `## Purpose`, `## Status`, `## How to run` (stated by you). Declared sources of truth: none stated.
- Checked: relative links (2a), old-name references (2b), stale markers (2c), README shape (2d), URLs (2e, no network, so unchecked), history text (2f). Anchors and HTML links were not checked.

## Findings
**P1**
- README.md:5 — "Sync is blocked on the new auth service; waiting for the vendor to enable it." — resolved-but-still-written: your note says the auth service went live last week and `scripts/seed.py` already uses it.
- README.md:7 — "[setup](guides/setup.md)" — dead link: `guides/setup.md` was renamed to `docs/install.md`.
- docs/api/README.md:2 — "Rate limits: see [limits](limits.md)" — dead link: `docs/api/limits.md` is not in the tree.
- docs/api/README.md:3 — "Prices: see docs/pricing-old.md." — reference to a deleted file as if it exists; the surviving page is `docs/pricing.md`.

**P2**
- docs/api/README.md:1 — "# API" — README is missing all three agreed sections: `## Purpose`, `## Status`, `## How to run`. (`README.md` at the root has all three.)
- docs/pricing.md:3 — "https://tinytasks.example.com/pricing" — live URL not verified (see Unverified).

**P3**
- docs/api/README.md:3 — "(We used to host this in guides/ before the merge.)" — history text; it belongs in `git log`.

Kept (no finding): README.md:7 link `docs/api/endpoints.md` and docs/api/README.md:2 link `endpoints.md` both resolve to `docs/api/endpoints.md`, which is in the tree.

## Unverified
- https://tinytasks.example.com/pricing (docs/pricing.md:3) — not requested and no network in this audit. The `example.com` domain suggests a placeholder; confirm whether it is real before anyone relies on it.
- README.md:5 — the "blocked" note is marked resolved only on your statement; I did not see `scripts/seed.py` or the auth config. Confirm the Sync feature actually works, not just that the service is live, before rewriting the Status line.
- Pricing figures in docs/pricing.md ("Free plan: 3 projects. Pro: $5/month.") are stated once in the pasted text, so no duplicate-truth conflict was found. Unpasted pages could restate them.

## Patch list
1. P1 README.md:5 — old: "Sync is blocked on the new auth service; waiting for the vendor to enable it." — new: a present-tense status, e.g. "Sync uses the new auth service." (confirm the exact wording and whether Sync works) — reason: the blocker is gone.
2. P1 README.md:7 — old: `[setup](guides/setup.md)` — new: `[setup](docs/install.md)` — reason: renamed in the merge of `guides/` into `docs/`.
3. P1 docs/api/README.md:3 — old: "Prices: see docs/pricing-old.md." — new: "Prices: see [pricing](../pricing.md)." — reason: the old file was deleted; link to the surviving page rather than copying prices. If the old content is still needed, `git show <commit>:docs/pricing-old.md` retrieves it; do not recreate the file.
4. P1 docs/api/README.md:2 — old: "Rate limits: see [limits](limits.md)." — new: remove the sentence, or point it at the page that now holds rate limits — reason: `limits.md` does not exist. Question for you: was it deleted, never written, or moved under another name?
5. P2 docs/api/README.md — add `## Purpose`, `## Status`, `## How to run` under "# API" (one line each; content is yours to supply) — reason: agreed README shape.
6. P3 docs/api/README.md:3 — old: " (We used to host this in guides/ before the merge.)" — new: remove — reason: history belongs in `git log`.
7. P2 docs/pricing.md:3 — no edit proposed; confirm the URL is real or replace the placeholder.

Reply `apply 1,2,5` (or `apply all P1`) and I will make exactly those edits.

Use cases

• Cleaning up after moving or merging doc folders
• Finding references to files you deleted
• Spotting 'blocked on X' notes that stopped being true
• Checking every README still has the sections your team agreed on

FAQ

Does it edit my files? Not unless you tell it which items to apply.

Does it check live URLs? Only if you give it results; it never calls a bot-blocked page dead.

Which repos? Any git repo with Markdown docs.