Skill: Validate Document Artifacts

Purpose

Check that documents under docs/ conform to the project's artifact norms (or default spec/artifact-contract.md). Emit a findings list for path, naming, and front-matter violations so users can remediate.

Core Objective

Primary Goal: Produce a findings list of documents that violate artifact norms, with Location, Severity, Title, Description, and Suggestion for each finding.

Success Criteria (ALL must be met):

✅ Norms resolved: Project norms read from docs/ARTIFACT_NORMS.md or .ai-cortex/artifact-norms.yaml; fallback to spec/artifact-contract.md
✅ Docs scanned: All relevant Markdown under docs/ (or specified scope) enumerated
✅ Artifact type inferred: Per file, inferred from path pattern or front-matter artifact_type
✅ Compliance checked: Path, naming, front-matter validated against norms
✅ Findings emitted: Each violation as a finding with Location, Category, Severity, Title, Description, Suggestion

Acceptance Test: Can a user apply the suggestions to fix all reported violations?

Scope Boundaries

This skill handles:

Resolving project norms per spec/artifact-norms-schema.md
Scanning docs/ for Markdown files
Inferring artifact type from path or front-matter
Checking path, naming, and front-matter against norms
Emitting findings list in standard format

This skill does NOT handle:

Auto-fixing violations (user or other tools apply suggestions)
Readiness assessment (use assess-documentation-readiness)
Establishing norms (use discover-document-norms)

Handoff point: When findings are delivered, hand off to user for remediation or to discover-document-norms if norms need to be created or updated.

Use Cases

Pre-commit check: Ensure new docs comply before commit
Audit: Identify existing docs that violate norms
After norms change: Re-validate after updating ARTIFACT_NORMS.md

Behavior

Phase 1: Resolve Norms

Check .ai-cortex/artifact-norms.yaml then docs/ARTIFACT_NORMS.md
If found, parse path_pattern and naming per spec/artifact-norms-schema.md
If not found, use spec/artifact-contract.md defaults

Phase 2: Scan and Infer

Enumerate Markdown under docs/ (or user-specified root)
For each file: read front-matter for artifact_type; if absent, infer from path (e.g. backlog/ → backlog-item, design-decisions/ → design)
Map each file to expected path_pattern and naming from norms

Phase 3: Validate and Emit

For each file: compare actual path and filename to expected pattern
Check front-matter for required fields (artifact_type, created_by when applicable)
Emit finding for each violation: Location (path), Category (artifact-norms), Severity (major or minor), Title, Description, Suggestion

Findings Format

Each finding MUST follow:

Field	Content
Location	`path/to/file.md`
Category	`artifact-norms`
Severity	`critical` \| `major` \| `minor` \| `suggestion`
Title	Short violation summary
Description	What is wrong
Suggestion	How to fix (e.g. move to X, add front-matter Y)

Input & Output

Input

Project path (default: workspace root)
Optional: docs root (default docs/)
Optional: scope (all, or specific artifact_type)

Output

Findings list (array of findings)
Summary: total files scanned, violations count by severity

Restrictions

Hard Boundaries

Read-only: Do not modify files; only report findings.
Schema compliance: Findings MUST follow standard format for aggregation.

Skill Boundaries (Avoid Overlap)

Do NOT do these:

Create or update norms → discover-document-norms
Assess doc readiness → assess-documentation-readiness
Auto-fix → User applies suggestions

Self-Check

Core Success Criteria (ALL must be met)

Norms resolved: Project or default norms used
Docs scanned: Relevant Markdown enumerated
Compliance checked: Each file validated
Findings emitted: Standard format, actionable suggestions

Acceptance Test

Can a user apply the suggestions to fix all reported violations?

If NO: Suggestions unclear or incomplete. Refine findings. If YES: Validation complete.

Examples

Example 1: Path Mismatch

File: docs/designs/2026-03-06-auth.md (project norm: docs/design-decisions/)

Finding: Location docs/designs/2026-03-06-auth.md, Category artifact-norms, Severity major, Title "Design doc in non-standard path", Description "File is under docs/designs/ but norms specify docs/design-decisions/", Suggestion "Move to docs/design-decisions/2026-03-06-auth.md"

Example 2: Missing Front-Matter

File: docs/backlog/2026-03-06-bug.md (no artifact_type or created_by)

Finding: Location docs/backlog/2026-03-06-bug.md, Category artifact-norms, Severity minor, Title "Missing artifact front-matter", Description "File lacks artifact_type and created_by", Suggestion "Add front-matter: artifact_type: backlog-item, created_by: capture-work-items"

Appendix: Output contract

This skill emits a findings-list compatible with aggregation. Each finding MUST follow:

Element	Requirement
Location	File path (e.g. `docs/backlog/2026-03-06-bug.md`)
Category	`artifact-norms` \| `path` \| `naming` \| `front-matter`
Severity	`critical` \| `major` \| `minor` \| `suggestion`
Title	Short one-line summary
Description	What is wrong and why it matters
Suggestion	Concrete fix or remediation step

validate-document-artifacts