Broken Internal Reference¶
Rule ID: content-broken-internal-reference
Detect markdown links where the target file does not exist
| Severity | warning (auto) |
| Autofix | auto |
| Since | v0.9.0 |
Research Basis¶
Detects markdown links pointing to files that do not exist (e.g.,
[setup guide](docs/setup.md) when docs/setup.md has been deleted or
renamed).
Broken internal links are a standard software engineering defect — dead references that mislead both human readers and AI agents. When an LLM encounters a broken link in an instruction file, it cannot follow the reference to gather the intended context. Worse, the LLM may hallucinate the contents of the missing file based on the link text, producing confidently wrong output grounded in a nonexistent source.
This is the same class of defect that link checkers catch in documentation sites and wikis. The difference is that instruction files for AI agents are executable context — a broken link doesn't just frustrate a reader, it removes a dependency from the agent's decision-making chain.
The rule constrains resolved paths to the repository root to avoid
environment-dependent results from ../ traversal, and skips files inside
template directories where placeholder links are expected.
References:
- W3C: Link Checking — Broken links are a recognized web quality defect; the same principle applies to interlinked instruction files
- Google Technical Writing: Links — "Don't force readers to backtrack because a link doesn't work"
- Anthropic: Effective Context Engineering — Context that references missing information degrades agent performance