Skip to content
OpenSmartRoute
Skillv1.0.0

doc-validator

Validate the SDD corpus - cross-document references, orphans, cumulative-tag gaps, duplicate IDs, and full bidirectional traceability (with optional repair), plus a prose/terminology pass. Use before

by vladm3105(0) 0 installs
Free
Sign in to install

Free account. Installing gives you the manifest plus copy-paste snippets.

See reviews

About

Imported from vladm3105/aidoc-flow-framework (platforms/claude-code-plugin/skills/doc-validator/SKILL.md). Install upstream with npx skills add vladm3105/aidoc-flow-framework --skill doc-validator. Copyright stays with the author.

doc-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 emits XDOC-E007; use it to check IDs — doc-naming is 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_updated earlier than created).
  • 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 downstream required_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-term TERM findings 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

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml
targets:
  - https://api.opensmartroute.ai/api/v1/registry/vladm3105-aidoc-flow-framework-doc-validator/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

vladm3105-aidoc-flow-framework-doc-validator.ocm.jsonjson
{
  "ocm": "1",
  "id": "vladm3105-aidoc-flow-framework-doc-validator",
  "kind": "skill",
  "name": "doc-validator",
  "description": "Validate the SDD corpus - cross-document references, orphans, cumulative-tag gaps, duplicate IDs, and full bidirectional traceability (with optional repair), plus a prose/terminology pass. Use before releases, after batch generation, or to validate and repair the corpus.",
  "publisher": "vladm3105",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "general"
    ],
    "tags": [
      "skill-md",
      "sdd-workflow",
      "utility",
      "quality-assurance",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Validate the SDD corpus - cross-document references, orphans, cumulative-tag gaps, duplicate IDs, and full bidirectional traceability (with optional repair), plus a prose/terminology pass. Use before releases, after batch generation, or to validate and repair the corpus."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/vladm3105/aidoc-flow-framework",
      "path": "platforms/claude-code-plugin/skills/doc-validator/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/vladm3105/aidoc-flow-framework/blob/HEAD/platforms/claude-code-plugin/skills/doc-validator/SKILL.md",
      "key": "vladm3105/aidoc-flow-framework/platforms/claude-code-plugin/skills/doc-validator/SKILL.md"
    }
  },
  "instructions": "# doc-validator\n\n## Purpose\n\nValidate relationships and consistency **across** documents in the SDD corpus:\nbroken cross-references, orphaned artifacts, one-way links, cumulative-tag\ngaps, duplicate or malformed IDs, and traceability-matrix completeness across\nthe 8 layers. This skill **is** the validator — the framework ships no runtime\ncode; it applies declarative checks against `${CLAUDE_PLUGIN_ROOT}/framework/governance/` and the\nlayer `README.md` files.\n\n**Layer**: cross-cutting utility (reads all 8 layers; produces no artifacts).\n\n## When to Use\n\n**Use** for project-wide checks: relation",
  "cost": {
    "context_tokens": 1719
  }
}

Fetch it by URL: GET /api/v1/registry/vladm3105-aidoc-flow-framework-doc-validator/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.