Link Health — Repo-wide Markdown Link Audit Methodology
A reusable methodology for bringing a broken docs-heavy repo's link checker to green. Codified from a real audit that took AlterLab-IEU/AlterLab-Academic-Skills from 1208 errors out of 1966 links to 0 errors out of 1912 links across 8 commits, with an auto-detected Tier 3 regression that validated the guardrail rule.
Quick Start
Full audit (fresh repo, failing link checker):
Audit and repair the link health of <owner/repo>. Run the full four-tier pipeline.
→ Dispatch the 10-agent audit from playbooks/full-audit.md, then the tiered APPLY phase.
Targeted residual pass (first dispatch reduced errors but some remain):
The link checker is down from 1208 to 67 errors. Close the residuals.
→ Dispatch the 3-agent followup pass from playbooks/followup-pass.md.
Post-merge cleanup (PR is green, need to finalize human-decision items):
Finalize the post-merge cleanup: resolve pending human-decision items, file follow-up issues, document link debt.
→ Dispatch the 4-agent post-merge pass from playbooks/post-merge.md.
When to Use This Skill
- A weekly
Check Links(or similar lychee / markdown-link-check) workflow has been failing. - The user mentions a large error count (hundreds+) that they suspect is mostly config-driven false positives.
- The user wants to refactor broken intra-repo file references across many skills / docs.
- The user wants a reusable process for link debt maintenance going forward.
Trigger keywords — English: link audit, dead links, link health, lychee, broken links, link checker, markdown link audit, link-health audit, 404 audit, check-links failing, CI link-check. 繁體中文: 連結健檢, 死鏈, 失效連結, 斷鏈檢查, 連結審計.
Does NOT Trigger
| Scenario | Use Instead |
|---|---|
| Verify that cited works exist (DOI/author resolution, fabricated or hallucinated references, retractions) | alterlab-citation-verifier — link-health only repairs hyperlinks; it never validates that a cited work exists |
| Fix a single broken link in a single file | A direct edit — no pipeline needed |
| Audit repo structure beyond links (schema, frontmatter, metadata) | A separate schema-drift audit (out of scope here) |
Pipeline Overview (4 Tiers)
Each tier is a single reviewable commit. Run them in order — each unlocks the next by making the error signal cleaner.
| Tier | Scope | Typical Delta |
|---|---|---|
| 1 — Config | Introduce .lychee.toml with an explicit accept set (it replaces lychee's defaults, so list 200..=299), a .lycheeignore for permanent noise hosts, and a hardened CI workflow. | Biggest single win — often -70% to -90% of errors. Fixes the "--accept 403 replaces the default set" gotcha. |
| 2 — Intra-repo refs | Repair [ERROR] file:// entries: singular/plural directory typos, missing path prefixes, YAML frontmatter bugs. Wrap pedagogical placeholder paths as inline code. | Eliminates the bulk of real breakage — usually 200-400 entries collapse to zero. |
| 3 — URL substitutions | Replace MOVED external URLs with verified-live substitutes; replace DEAD_INFRA URLs with replacement resources. Never substitute without verification. | Reduces residuals to the low dozens. |
| 4 — Exclusions | Everything left that cannot be fixed: bot-hostile hosts, pedagogical placeholders, expired upstream infrastructure, chronically flaky academic sites. | Gets to 0 errors or stable single-digit residuals. |
See references/tier1-config.md through references/tier4-exclusions.md for the decision rules in each tier.
The Tier 3 Guardrail
After any URL substitution pass, re-run the link checker and diff against the baseline success set. Any URL that returned 200 OK in baseline and is non-200 after substitution is a regression; revert it before committing.
Self-check:
bashdiff <(grep "^\[200\]" baseline.log | sort -u) \ <(grep "^\[200\]" post.log | sort -u)
Output should show no deletions, only additions. Deletions mean a substitution regressed a previously-working URL.
This rule exists because during the source audit, broad sed prefix substitutions silently concatenated onto more-specific paths (e.g. /v3/ → /v3/docs turned an already-correct /v3/docs into /v3/docsdocs). The guardrail caught it on the second CI dispatch, not the commit itself. Assume your Tier 3 pass will have regressions. Verify.
Full detail: references/tier3-substitution.md.
The Verification-First Rule
Probe-verify before any URL substitution. Unverified substitutions are how phantom URLs land in public skills. Before every [old] → [new] replacement:
- For GitHub repos:
gh api repos/owner/name— status must be 200 (repo exists, not archived). - For HTTP URLs:
curl -sSI -L --max-time 15 '<new>'— final status must be 200 (after redirects). - For PyPI / npm / crates packages: check the registry API or landing page directly.
If verification fails, exclude the dead target via .lycheeignore with a commented reason rather than guessing a replacement. An excluded dead link is honest; a substituted wrong link is a time bomb.
Full detail: references/tier3-substitution.md § "Verification rules".
Playbooks
Three ready-to-dispatch prompt bundles that call this skill's tiers in the right order.
| Playbook | When to Use | Agents |
|---|---|---|
playbooks/full-audit.md | Fresh audit, failing CI, no prior work. | 10 parallel subagents + synthesis |
playbooks/followup-pass.md | Errors significantly reduced but residuals remain. | 3 targeted subagents |
playbooks/post-merge.md | PR green, time to resolve pending human-decision items. | 4 parallel subagents |
All three follow the same shape: pre-flight → parallel dispatch → synthesize → commit/PR/merge → verify.
References
| File | Content |
|---|---|
references/tier1-config.md | .lychee.toml schema, workflow YAML, accept-code gotchas |
references/tier2-intra-repo.md | Intra-repo path audit, singular/plural directory patterns, frontmatter fixes |
references/tier3-substitution.md | URL substitution rules, the guardrail, sed-safety patterns |
references/tier4-exclusions.md | When to exclude vs substitute, .lycheeignore category rubric |
references/known-debt-template.md | The 5-category KNOWN_LINK_DEBT.md layout for maintainers |
Examples
examples/pr-1-retrospective.md— the source audit that generated this skill. 1208 → 0 errors, 8 commits, auto-detected Tier 3 regression in commit 5 (9cbd801), merged as93a72fe.
Scope Discipline
This skill fixes link health. It does NOT:
- Standardize SKILL.md schemas across the repo. File schema drift as a separate issue.
- Refactor skill content, examples, or prose. Only touches link URLs and the CI config.
- Modify
.lychee.toml's accept list to mask real breakage. Flaky upstream 5xx / timeouts get excluded per-host with rationale, not blanket-accepted.
Scope discipline keeps the PR reviewable and the link-check signal honest.
Part of the AlterLab Academic Skills suite.
