skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
vladm3105/aidoc-flow-framework71 installs

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 releases, after batch generation, or to validate and repair the corpus.

How do I install this agent skill?

npx skills add https://github.com/vladm3105/aidoc-flow-framework --skill doc-validator
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    This skill is a document validation utility designed to enforce consistency, traceability, and naming standards across a documentation corpus. It analyzes local files for broken links, orphan artifacts, and metadata accuracy. No malicious behaviors or security risks were identified.

  • Socketpass

    No alerts

  • Snykpass

    Risk: LOW · No issues

  • Runlayerpass

    1/2 files flagged

What does this agent skill do?

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

CategoryCheckError codes
LINKSEvery markdown/document link and anchor resolvesXDOC-E001, XDOC-E004
CROSS-REFEach cited document/element ID exists in the corpusXDOC-E001, XDOC-E003
ORPHANNo artifact lacks an upstream connectionXDOC-E005
TAGSCumulative upstream tags complete per the 8-layer hierarchyXDOC-E002
IDSElement IDs TYPE.NN.SS.xxxx; doc refs SPEC-NN/ADR-NN/IPLAN-NN; no duplicates; no legacy/3-segment/retired formsXDOC-E006, XDOC-E007
MATRIXTraceability-matrix completeness across 8 layersXDOC-W001
SECTIONSection file count matches metadataSEC-E001…E003, SEC-W001
DIAGRAMMermaid entities match proseDIAG-E001/E002, DIAG-W001/W002
TERMTerminology/acronym consistencyTERM-E001/E002, TERM-W001/W002
COUNTStated counts match itemized totalsCOUNT-E001, COUNT-W001
FWDREFNo upstream→downstream references; no cyclesFWDREF-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

LayerArtifactRequired upstream tags
1BRDnone
2PRD@brd
3EARS@brd, @prd
4BDD@brd, @prd, @ears
5ADR@brd, @prd, @ears, @bdd
6SPEC+ @adr (5)
7TDD+ @spec (6)
8IPLAN+ @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

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/vladm3105/aidoc-flow-framework/doc-validator">View doc-validator on skillZs</a>