title	doc-validator: Cross-document validation for SDD framework
name	doc-validator
description	Cross-document validation, traceability gaps, and project-wide consistency checks for SDD framework
tags	sdd-workflow, shared-architecture, quality-assurance, required-both-approaches, cross-document-validation
custom_fields	[object Object]

doc-validator

Cross-document validation for SDD framework compliance. For single-document validation, use the dedicated layer validators.

Purpose

Validates relationships and consistency ACROSS documents in the SDD framework.

Core Functions:

Identifies broken cross-references between documents
Detects orphaned artifacts (documents with no upstream references)
Validates bidirectional link consistency
Checks cumulative tagging hierarchy across layers
Detects duplicate IDs across documents
Validates traceability matrix completeness
Monitors project-wide consistency

This Skill Does NOT:

Validate single document structure (use {TYPE}_VALIDATION_RULES.md in each artifact directory)
Validate single document metadata (use {TYPE}_VALIDATION_RULES.md in each artifact directory)
Validate single document content (use {TYPE}_VALIDATION_RULES.md in each artifact directory)

Dedicated Layer Validators:

Layer	Artifact	Validation Rules File
1	BRD	`ai_dev_flow/BRD/BRD_VALIDATION_RULES.md`
2	PRD	`ai_dev_flow/PRD/PRD_VALIDATION_RULES.md`
3	EARS	`ai_dev_flow/EARS/EARS_VALIDATION_RULES.md`
4	BDD	`ai_dev_flow/BDD/BDD_VALIDATION_RULES.md`
5	ADR	`ai_dev_flow/ADR/ADR_VALIDATION_RULES.md`
6	SYS	`ai_dev_flow/SYS/SYS_VALIDATION_RULES.md`
7	REQ	`ai_dev_flow/REQ/REQ_VALIDATION_RULES.md`
8	IMPL	`ai_dev_flow/IMPL/IMPL_VALIDATION_RULES.md`
9	CTR	`ai_dev_flow/CTR/CTR_VALIDATION_RULES.md`
10	SPEC	`ai_dev_flow/SPEC/SPEC_VALIDATION_RULES.md`
11	TASKS	`ai_dev_flow/TASKS/TASKS_VALIDATION_RULES.md`
12	IPLAN	`ai_dev_flow/IPLAN/IPLAN_VALIDATION_RULES.md`

ID Format Validation: For unified ID format validation (4-segment element IDs), use doc-naming skill.

Reference: ID_NAMING_STANDARDS.md

Complexity: Medium (cross-reference analysis across multiple documents)

Resource Requirements:

CPU: Moderate (file parsing, graph traversal)
Memory: 200-500MB for 100-200 documents
Disk: Minimal (read-only validation)
Network: None (local file operations only)

Failure Modes:

Broken cross-reference: Reports links to non-existent documents
Missing bidirectional link: Reports one-way references
Orphaned artifact: Reports documents with no upstream connections
Duplicate ID: Reports ID conflicts across documents
Traceability gap: Reports missing required upstream tags

When to Use This Skill

Use doc-validator when:

Validating relationships BETWEEN documents
Checking project-wide traceability
Detecting orphaned artifacts
Validating bidirectional link consistency
Checking cumulative tagging across layers
Detecting duplicate IDs across documents
Before major releases (project-wide validation)

Do NOT use doc-validator when:

Validating a single document's structure (use {TYPE}_VALIDATION_RULES.md)
Validating a single document's metadata (use {TYPE}_VALIDATION_RULES.md)
Validating a single document's content (use {TYPE}_VALIDATION_RULES.md)
Validating ID format compliance (use doc-naming skill)
For detailed traceability analysis (use trace-check skill)

Skill Inputs

Input	Type	Description	Example/Default
docs_path	Required	Path to documentation directory	`{project_root}/docs/`
scope	Optional	Validation scope	`"cross-document"` (default), `"traceability"`, `"full"`
strictness	Optional	Validation strictness level	`"strict"` (default), `"permissive"`
report_format	Optional	Output report format	`"markdown"` (default), `"json"`, `"text"`

Scopes:

cross-document: Links, references, bidirectional consistency
traceability: Cumulative tags, upstream/downstream validation
full: All cross-document validations

Cross-Document Validators

[IMPLEMENTED] Validation Scripts

Category	Script	Description	Error Codes
LINKS	`validate_links.py`	Markdown link resolution	XDOC-E001, XDOC-E004
CROSS-REF	`validate_cross_document.py`	Cross-reference validation	XDOC-E001, XDOC-E003
SECTION	`validate_section_count.py`	Section file count vs metadata	SEC-E001, SEC-E002, SEC-E003, SEC-W001
DIAGRAM	`validate_diagram_consistency.py`	Mermaid diagrams match prose	DIAG-E001, DIAG-E002, DIAG-W001, DIAG-W002
TERM	`validate_terminology.py`	Terminology/acronym consistency	TERM-E001, TERM-E002, TERM-W001, TERM-W002
COUNT	`validate_counts.py`	Stated counts match itemized totals	COUNT-E001, COUNT-W001
FWDREF	`validate_forward_references.py`	Prevent upstream to downstream ID refs	FWDREF-E001, FWDREF-E002, FWDREF-W001
TAGS	`validate_tags_against_docs.py`	Cumulative tag compliance	XDOC-E002
IDS	`validate_requirement_ids.py`	Duplicate ID detection	XDOC-E006
MATRIX	`validate_traceability_matrix.py`	Matrix validation	XDOC-W001

Auto-Fix Support: SECTION, TERM, COUNT validators support --auto-fix flag.

Reference: See VALIDATION_STANDARDS.md for complete error code registry.

[IMPLEMENTED] Support Scripts

Script	Purpose	Status
`validate_all.py`	Unified orchestrator for all validators	[IMPLEMENTED]
`validate_cross_document.py`	Cross-reference validation	[IMPLEMENTED]
`validate_links.py`	Markdown link resolution	[IMPLEMENTED]
`validate_tags_against_docs.py`	Cumulative tag compliance	[IMPLEMENTED]
`validate_traceability_matrix.py`	Matrix validation	[IMPLEMENTED]
`error_codes.py`	Standardized error code registry	[IMPLEMENTED]

Validation Workflow

graph TD
    A[Input: Documentation Directory] --> B[Collect All Documents]
    B --> C[Build Document Graph]
    C --> D{Cross-Reference Check}
    D -->|Broken| E[XDOC-E001: Broken Link]
    D -->|Valid| F{Bidirectional Check}
    F -->|Missing| G[XDOC-E003: One-Way Reference]
    F -->|Valid| H{Anchor Check}
    H -->|Missing| I[XDOC-E004: Anchor Not Found]
    H -->|Valid| J{Orphan Check}
    J -->|Orphaned| K[XDOC-E005: Orphaned Artifact]
    J -->|Connected| L{Cumulative Tags}
    L -->|Missing| M[XDOC-E002: Missing Tag]
    L -->|Complete| N{Duplicate IDs}
    N -->|Found| O[XDOC-E006: Duplicate ID]
    N -->|Unique| P[Validation PASS]

    E --> Q[Validation Report]
    G --> Q
    I --> Q
    K --> Q
    M --> Q
    O --> Q
    P --> Q

Error Codes Reference

Cross-Document Errors (XDOC)

Code	Message	Severity	Fix
XDOC-E001	Referenced ID/file not found	ERROR	Verify target document exists
XDOC-E002	Missing cumulative tag	ERROR	Add required upstream tag
XDOC-E003	Bidirectional link missing	ERROR	Add reverse reference
XDOC-E004	Anchor not found in target	ERROR	Fix anchor reference
XDOC-E005	Orphaned artifact	ERROR	Add upstream reference
XDOC-E006	Duplicate ID detected	ERROR	Use unique IDs across project
XDOC-W001	Weak traceability	WARNING	Add direct links
XDOC-W002	Unused artifact	WARNING	Consider removal or linking

Section Consistency Errors (SEC)

Code	Message	Severity	Fix
SEC-E001	Section count mismatch	ERROR	Update metadata or add sections
SEC-E002	Missing referenced section	ERROR	Create referenced section file
SEC-E003	Section ordering invalid	ERROR	Fix section numbering
SEC-W001	Empty section detected	WARNING	Add content or remove section

Diagram Consistency Errors (DIAG)

Code	Message	Severity	Fix
DIAG-E001	Diagram references missing entity	ERROR	Add entity to prose
DIAG-E002	Diagram syntax error	ERROR	Fix Mermaid syntax
DIAG-W001	Diagram outdated vs prose	WARNING	Update diagram
DIAG-W002	Prose entity missing from diagram	WARNING	Add to diagram

Terminology Errors (TERM)

Code	Message	Severity	Fix
TERM-E001	Undefined term used	ERROR	Add to glossary
TERM-E002	Conflicting term definitions	ERROR	Standardize definition
TERM-W001	Inconsistent term usage	WARNING	Use canonical form
TERM-W002	Acronym without expansion	WARNING	Add first-use expansion

Count Consistency Errors (COUNT)

Code	Message	Severity	Fix
COUNT-E001	Stated count differs from actual	ERROR	Update count or items
COUNT-W001	Count format non-standard	WARNING	Use standard count format

Forward Reference Errors (FWDREF)

Code	Message	Severity	Fix
FWDREF-E001	Upstream references downstream ID	ERROR	Remove forward reference
FWDREF-E002	Circular reference detected	ERROR	Break reference cycle
FWDREF-W001	Implicit forward reference	WARNING	Make explicit or remove

Cumulative Tag Validation

Each layer must include ALL upstream tags per the SDD hierarchy:

Layer	Artifact	Required Upstream Tags
1	BRD	None (top level)
2	PRD	@brd
3	EARS	@brd, @prd
4	BDD	@brd, @prd, @ears
5	ADR	@brd, @prd, @ears, @bdd
6	SYS	@brd through @adr (5 tags)
7	REQ	@brd through @sys (6 tags)
8	IMPL	@brd through @req (7 tags)
9	CTR	@brd through @req (7 tags)
10	SPEC	@brd through @req (7 tags)
11	TASKS	@brd through @spec (8 tags)
12	IPLAN	@brd through @tasks (9 tags)

Validation Script: validate_tags_against_docs.py

Quality Gates

Severity Levels

Level	Code	Exit Code	Blocks Commit	Description
ERROR	E	2	Yes	Critical issue, must fix
WARNING	W	1	--strict only	Should fix
INFO	I	0	No	Suggestion

Project-Wide Gates

Gate	Threshold	Measurement
Zero Cross-Ref Errors	0	Count of XDOC-E level issues
Orphan Limit	0	Count of orphaned artifacts
Bidirectional Compliance	100%	Links with reverse references
Cumulative Tag Compliance	100%	Documents with complete upstream tags
Duplicate ID Count	0	Duplicate IDs across project

Integration Points

With Layer Validators

Single-document validation delegated to doc-{type}-validator skills
Cross-document validation runs after layer validators pass
Combined quality reports

With doc-flow

Invoked after artifact generation for cross-document checks
Blocks workflow on cross-reference errors
Provides link fix suggestions

With trace-check

Complementary validation (cross-refs vs. detailed traceability)
Shared cumulative tag validation logic
Combined traceability reports

With code-review

Post-commit cross-document validation
Quality gate enforcement

Usage Examples

Validate Cross-References

python ai_dev_flow/scripts/validate_cross_document.py docs/ --strict

Validate All Links

python ai_dev_flow/scripts/validate_links.py docs/

Validate Cumulative Tags

python ai_dev_flow/scripts/validate_tags_against_docs.py \
  --source docs/ \
  --validate-cumulative \
  --strict

Detect Duplicate IDs

python ai_dev_flow/scripts/validate_requirement_ids.py docs/ --check-duplicates

Full Cross-Document Validation

python ai_dev_flow/scripts/validate_all.py docs/ --scope cross-document

Validation Report Format

=== Cross-Document Validation Report ===

Scope: docs/
Status: FAILED

Cross-Reference Errors (3):
- [XDOC-E001] REQ-02_payments.md references non-existent SPEC-05_gateway.yaml
  → Create target document or fix reference

- [XDOC-E003] ADR-03_caching.md linked from SYS-01 but no reverse link
  → Add @sys reference to ADR-03

- [XDOC-E005] IMPL-04_batch.md has no upstream references
  → Add @req tag to connect to requirements

Cumulative Tag Warnings (2):
- [XDOC-E002] TASKS-02 missing required @adr tag
  → Add @adr: ADR-NN to traceability section

- [XDOC-E002] IPLAN-01 missing required @spec tag
  → Add @spec: SPEC-NN to traceability section

Summary:
- Documents analyzed: 45
- Cross-reference errors: 3
- Orphaned artifacts: 1
- Bidirectional compliance: 94% (32/34)
- Cumulative tag compliance: 96% (43/45)

Script Reference

Cross-Document Validation Scripts (Location: `ai_dev_flow/scripts/`)

Script	Purpose	Usage
`validate_all.py`	Unified orchestrator	`python validate_all.py <dir> --scope cross-document`
`validate_cross_document.py`	Cross-references	`python validate_cross_document.py <dir>`
`validate_links.py`	Link resolution	`python validate_links.py <dir>`
`validate_tags_against_docs.py`	Cumulative tags	`python validate_tags_against_docs.py <dir>`
`validate_traceability_matrix.py`	Matrix validation	`python validate_traceability_matrix.py <dir>`
`validate_requirement_ids.py`	Duplicate IDs	`python validate_requirement_ids.py <dir>`
`validate_section_count.py`	Section consistency	`python validate_section_count.py <dir>`
`validate_diagram_consistency.py`	Diagram vs prose	`python validate_diagram_consistency.py <dir>`
`validate_terminology.py`	Term consistency	`python validate_terminology.py <dir>`
`validate_counts.py`	Count consistency	`python validate_counts.py <dir>`
`validate_forward_references.py`	Forward refs	`python validate_forward_references.py <dir>`
`error_codes.py`	Error code registry	(library - import in validators)

Version Information

Version: 3.1.0 Last Updated: 2025-12-29 Created: 2025-11-01 Status: Active

Change Log:

3.1.0 (2025-12-29): Updated layer validator references
- Changed from non-existent doc-{type}-validator skills to actual {TYPE}_VALIDATION_RULES.md files
- Added doc-naming skill reference for ID format validation
- Updated "Do NOT use" section with additional guidance
3.0.0 (2025-12-20): Refactored to cross-document validation only
- Removed single-document validation (now in dedicated layer validators)
- Added references to 12 layer-specific validator skills
- Focused scope on cross-document relationships
- Updated workflow diagram for cross-document focus
- Streamlined error codes to XDOC, SEC, DIAG, TERM, COUNT, FWDREF
- Removed redundant single-document sections
2.0.0 (2025-12-19): Complete overhaul
- Restructured following trace-check pattern
- Added [IMPLEMENTED]/[PLANNED] status markers
- Standardized error codes
1.0.0 (2025-11-01): Initial release

doc-validator

Install Skill

SKILL.md

doc-validator

Purpose

When to Use This Skill

Skill Inputs

Cross-Document Validators

[IMPLEMENTED] Validation Scripts

[IMPLEMENTED] Support Scripts

Validation Workflow

Error Codes Reference

Cross-Document Errors (XDOC)

Section Consistency Errors (SEC)

Diagram Consistency Errors (DIAG)

Terminology Errors (TERM)

Count Consistency Errors (COUNT)

Forward Reference Errors (FWDREF)

Cumulative Tag Validation

Quality Gates

Severity Levels

Project-Wide Gates

Integration Points

With Layer Validators

With doc-flow

With trace-check

With code-review

Usage Examples

Validate Cross-References

Validate All Links

Validate Cumulative Tags

Detect Duplicate IDs

Full Cross-Document Validation

Validation Report Format

Script Reference

Cross-Document Validation Scripts (Location: `ai_dev_flow/scripts/`)

Version Information

Install Skill

SKILL.md

doc-validator

Purpose

When to Use This Skill

Skill Inputs

Cross-Document Validators

[IMPLEMENTED] Validation Scripts

[IMPLEMENTED] Support Scripts

Validation Workflow

Error Codes Reference

Cross-Document Errors (XDOC)

Section Consistency Errors (SEC)

Diagram Consistency Errors (DIAG)

Terminology Errors (TERM)

Count Consistency Errors (COUNT)

Forward Reference Errors (FWDREF)

Cumulative Tag Validation

Quality Gates

Severity Levels

Project-Wide Gates

Integration Points

With Layer Validators

With doc-flow

With trace-check

With code-review

Usage Examples

Validate Cross-References

Validate All Links

Validate Cumulative Tags

Detect Duplicate IDs

Full Cross-Document Validation

Validation Report Format

Script Reference

Cross-Document Validation Scripts (Location: ai_dev_flow/scripts/)

Version Information

Cross-Document Validation Scripts (Location: `ai_dev_flow/scripts/`)