# content-broken-internal-reference Detect markdown links where the target file does not exist | | | |---|---| | **Severity** | warning (auto) | | **Autofix** | auto | | **Since** | v0.9.0 | | **Category** | [Content Intelligence](content-intelligence.md) | ## Why A markdown link pointing to a nonexistent file is a dead reference — the model cannot follow it to read context it was promised, and a human reader clicking it gets a 404. Broken links typically appear after renames or directory restructuring when the referencing file was not updated. ## Examples **Bad:** ```markdown See [setup guide](docs/old-setup.md) for installation steps. ``` **Good:** ```markdown See [setup guide](docs/setup.md) for installation steps. ``` ## How to fix Update the link target to the file's current path. When the violation includes a "did you mean" suggestion, that is a fuzzy match against the repository — verify it is correct and apply it. The autofix is suggest-confidence: a plain `skillsaw fix` skips it, so run `skillsaw fix --suggest` to apply the suggested corrections, and review the result before committing. Only repository-relative targets are checked. Anchors (`#...`) and any target carrying an RFC 3986 URI scheme — not just `http(s):` and `mailto:`, but also application links like `app://` or `vscode://` — are treated as external and never reported. Suggested corrections preserve link labels, titles, queries and anchors. Destinations with spaces or parentheses are percent-encoded so the corrected link remains valid Markdown. Files edited after the finding was produced are left alone when their original token span can no longer be verified. Links such as `docs/setup.md?plain=1#install` are checked against the path `docs/setup.md`. Query text and fragments remain unchanged if a typo in that path receives a suggested correction. Exact existing filenames containing `?` are also accepted on filesystems that support them. ## Configuration ```yaml rules: content-broken-internal-reference: enabled: auto # true | false | auto severity: warning ``` ## 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](https://www.w3.org/QA/Tools/) — Broken links are a recognized web quality defect; the same principle applies to interlinked instruction files - [Google style guide: Make headings into link targets](https://developers.google.com/style/headings-targets) — Keep old anchors when headings change so existing links keep working - [Anthropic: Effective Context Engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) — Context that references missing information degrades agent performance *Run `skillsaw explain content-broken-internal-reference` to see this documentation and the rule's effective configuration in your terminal.*