About doc-validator
doc-validator is a skill for checking relationships and consistency across an SDD document corpus. It reports cross-reference, orphan, ID, traceability, diagram, terminology, and prose issues, with optional repair for safely fixable findings.
Key features
- 01Checks links and cross-references across documents
- 02Finds orphaned artifacts and broken traceability
- 03Validates IDs and cumulative upstream tags
- 04Reviews diagrams, terminology, and stated counts
- 05Optionally repairs selected issues with backups
Use cases
- 01Running project-wide document checks before a release
- 02Checking bidirectional traceability and orphaned artifacts
- 03Reviewing documentation prose before publication
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/doc-validatorin Claude Code to confirm it loaded.
Details
From the project READMEdoc-validator
Purpose
Validate relationships and consistency across documents in the SDD corpus:
broken cross-references, orphaned artifacts, one-way links, cumulative-tag
gaps, duplicate or malformed IDs, and traceability-matrix completeness across
the 8 layers. This skill is the validator — the framework ships no runtime
code; it applies declarative checks against ${CLAUDE_PLUGIN_ROOT}/framework/governance/ and the
layer README.md files.
Layer: cross-cutting utility (reads all 8 layers; produces no artifacts).
When to Use
Use for project-wide checks: relationships between documents, cumulative tagging, orphan detection, bidirectional-link consistency, duplicate IDs, deep traceability (with optional link repair), prose/terminology review, and before major releases. It is the single corpus-level validator — it also covers the traceability depth + repair and the prose review that were previously separate skills.
Do NOT use for:
- single-document structure/metadata/content — use that layer's
../doc-<layer>-audit/SKILL.md; - the definition of the ID-format rules — that authority is
../doc-naming/SKILL.md. (This skill enforces ID format and emitsXDOC-E007; use it to check IDs —doc-namingis where the rules live.)
Inputs: docs_path (required), scope (cross-document default /
traceability / prose / full), strictness (strict / permissive),
auto_fix (repair broken links / regenerate counts where safe), report_format.
Behavior
Cross-document checks
| Category | Check | Error codes |
|---|---|---|
| LINKS | Every markdown/document link and anchor resolves | XDOC-E001, XDOC-E004 |
| CROSS-REF | Each cited document/element ID exists in the corpus | XDOC-E001, XDOC-E003 |
| ORPHAN | No artifact lacks an upstream connection | XDOC-E005 |
| TAGS | Cumulative upstream tags complete per the 8-layer hierarchy | XDOC-E002 |
| IDS | Element IDs TYPE.NN.SS.xxxx; doc refs SPEC-NN/ADR-NN/IPLAN-NN; no duplicates; no legacy/3-segment/retired forms | XDOC-E006, XDOC-E007 |
| MATRIX | Traceability-matrix completeness across 8 layers | XDOC-W001 |
| SECTION | Section file count matches metadata | SEC-E001…E003, SEC-W001 |
| DIAGRAM | Mermaid entities match prose | DIAG-E001/E002, DIAG-W001/W002 |
| TERM | Terminology/acronym consistency | TERM-E001/E002, TERM-W001/W002 |
| COUNT | Stated counts match itemized totals | COUNT-E001, COUNT-W001 |
| FWDREF | No upstream→downstream references; no cycles | FWDREF-E001/E002, FWDREF-W001 |
SECTION / TERM / COUNT findings are typically auto-fixable (regenerate counts/sections, normalize terms); the rest are reported for manual fix.
Traceability depth + repair
Beyond the cross-document checks, run the full bidirectional traceability pass:
- Bidirectional symmetry — for each A→B link confirm B→A exists; score
(matched pairs / total) × 100(target ≥ 95%). - Coverage + orphans — upstream is required for every artifact except BRD; downstream is optional; flag mid-chain artifacts with no downstream and unexpected orphans; report coverage by type.
- Repair (
auto_fix) — when enabled, repair only safely-fixable issues: add a missing reciprocal link, regenerate section/COUNT metadata, normalize terminology. Write a timestamped backup first and print a rollback command; never invent placeholder IDs to satisfy a check. Structural/content gaps stay reported for the relevant-fixer.
Prose review (scope: prose)
Review a single file or a folder for prose quality independent of traceability, across four classes:
- DATA — stated counts / status / date logic vs. content (e.g. "5 features"
but 4 listed;
last_updatedearlier thancreated). - REF — inline link / anchor / tag-format resolution.
- TYPO — misspellings, doubled words, broken markdown.
- TERM — undefined acronyms, inconsistent or subjective terminology.
Severity follows strictness: under strict, any DATA/REF/TYPO/TERM finding is
an error (blocks); under permissive, they are warnings. Honor the project
glossary (.aidoc/profile.yaml; see Adaptation) to suppress domain-term TERM
false positives. Use before publishing or committing documentation.
Cumulative-tag hierarchy
| Layer | Artifact | Required upstream tags |
|---|---|---|
| 1 | BRD | none |
| 2 | PRD | @brd |
| 3 | EARS | @brd, @prd |
| 4 | BDD | @brd, @prd, @ears |
| 5 | ADR | @brd, @prd, @ears, @bdd |
| 6 | SPEC | + @adr (5) |
| 7 | TDD | + @spec (6) |
| 8 | IPLAN | + @tdd (7) |
Authority: ${CLAUDE_PLUGIN_ROOT}/framework/registry/LAYER_REGISTRY.yaml (required_tags) and
${CLAUDE_PLUGIN_ROOT}/framework/governance/TRACEABILITY.md.
ID-format enforcement (IDS)
Require element IDs in the 4-segment form TYPE.NN.SS.xxxx
(TYPE ∈ {BRD, PRD, EARS, BDD, ADR, TDD}) and document-level refs in the dash
form SPEC-NN/ADR-NN/IPLAN-NN. Reject legacy 3-segment element IDs,
the numeric type-code scheme, and any reference to retired 12-layer artifacts —
flag each with XDOC-E007. See ../doc-naming/SKILL.md.
Quality gates
ERROR blocks (exit 2); WARNING blocks only under --strict (exit 1);
INFO is advisory. Project-wide gates: zero cross-reference errors, zero
orphans, 100% bidirectional and 100% cumulative-tag compliance, zero duplicate
IDs. Output is a consolidated report (markdown/json/text) listing each finding,
its code, and a fix hint.
Adaptation
Read the project adaptation profile (.aidoc/profile.yaml) before validating.
Honor this skill's declared knobs:
active_layers— when a skippable layer (BDD / ADR) is disabled, treat it as absent by design: apply the cascade (drop it from downstreamrequired_tags/can_reference) so the cumulative-tag, orphan, and bidirectional checks do not flag the intentional gap as an error.glossary— use the project's preferred terms to normalize and suppress domain-termTERMfindings in the prose pass (no false positives on accepted vocabulary).
Ignore unknown / out-of-surface keys; absent a profile, use framework defaults.
Authority: ${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md.
Related Resources
- Governance:
${CLAUDE_PLUGIN_ROOT}/framework/governance/DOC_GOVERNANCE_CORE.md·${CLAUDE_PLUGIN_ROOT}/framework/governance/TRACEABILITY.md·${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md - Layer registry:
${CLAUDE_PLUGIN_ROOT}/framework/registry/LAYER_REGISTRY.yaml - Per-layer authority:
${CLAUDE_PLUGIN_ROOT}/framework/layers/NN_<X>/README.md - ID-format authority:
../doc-naming/SKILL.md - Single-document gates:
../doc-brd-audit/SKILL.md…../doc-iplan-audit/SKILL.md - Workflow routing:
../doc-flow/SKILL.md· Diagrams:../charts-flow/SKILL.md