Purpose
Check the link relationships between documents, and identify broken links, orphan documents, cycles, and deep-link risks.
Core Objective
Primary Objective: Output a fixable link health report.
Success Criteria：
- ✅ Document link graph has been built
- ✅ Broken links and orphan documents have been identified
- ✅ Circular references and deep links have been identified
- ✅ Fix recommendations have been provided
- ✅ Written to
docs/calibration/doc-link-health.md
Scope Boundaries
This skill is responsible for: document graph health. This skill is not responsible for: standards compliance, code alignment, SSOT audit.
Use Cases
- Pre-release link inspection
- Regression check after document migration
Behavior
Phase 0: Norms Resolution (new in v1.1)
Implemented according to specs/artifact-contract.md §8 Runtime Norms Resolution Protocol §8.2 / §8.3 / §8.5: if the project norms declare doc-link-health for artifact_type path_pattern, use the project value; otherwise fall through to the skill default (docs/calibration/doc-link-health.md). This skill is afixed-path governance output, and only uses the path_pattern override mechanism.
Phase 1: Link Graph Construction and Assessment
- Scan Markdown/Wiki links
- Build a directed graph
- Detect issues (broken/orphan/cycle/depth)
- Summarize risk levels and fix recommendations
Input & Output
Input
- docs root path
- Optional path filter
- Optional depth threshold (default 4)
Output
docs/calibration/doc-link-health.md
Restrictions
- Do not modify document files
- Do not check external URL reachability (only flag)
Self-Check
- Graph construction complete
- Issue classification complete
- Report written to disk complete
Examples
- Document A points to a nonexistent file -> broken link
Appendix: Output Contract
This skill produces a Doc Link Health Report:
| Element | Format | Required Fields | Path Pattern |
|---|---|---|---|
| Report body | Markdown | front-matter; sections: summary / broken links / orphan documents / circular references / deep-link paths | docs/calibration/doc-link-health.md |
| Broken link entry | List item | source_path / target_ref / kind（404 / anchor_missing / external_unreachable） | "Broken Links" section |
| Orphan entry | List item | doc_path / inbound_count=0 / suggested_link_target | "Orphan Documents" section |
| Machine-readable block | YAML fenced yaml link_health: |
broken[]、orphans[]、cycles[]、deep_chains[] | End of report |