doc-validate

doc-validate

Validate AsciiDoc documentation files for technical accuracy, style compliance, and structural correctness.

Parse arguments

$ARGUMENTS contains:

1. Target: file path, directory, or glob pattern for AsciiDoc files to validate
2. --context (optional): path to context package for cross-reference validation (defaults to workspace/context-package.json)

Step 1: Discover files

Resolve the target argument to a list of .adoc files:

• If a single file: validate that file
• If a directory: glob for **/*.adoc
• If a glob pattern: expand it

Step 2: Run deterministic validators

Execute the validation script on all discovered files:

python3 "${CLAUDE_SKILL_DIR}/scripts/validate-artifacts.py" "${file1}" "${file2}" ...

This runs:

• Vale: prose style compliance
• Asciidoctor: compilation check (can the file be built?)
• Lychee: link checking (are URLs valid?)
• YAML syntax: validate embedded YAML code blocks

Collect all findings from the script output.

Step 3: Extract embedded artifacts

For each AsciiDoc file, extract embedded technical artifacts:

1. YAML blocks: Content within [source,yaml] delimiters
2. CLI commands: Content within [source,bash] or [source,terminal] delimiters
3. Configuration references: Attribute references like {attribute-name}
4. API paths: URLs or paths in the format /api/v1/...
5. CRD references: Kubernetes resource kinds and API versions

Step 4: Cross-reference validation (LLM)

If a context package is available, use LLM judgment to cross-reference extracted artifacts against the gathered context:

For each extracted artifact:

• YAML blocks: Compare against CRD schemas and config examples in context
• CLI commands: Verify flags and options against --help output or source code in context
• API paths: Check against API specs or route definitions in context
• CRD references: Verify kind names, API versions, and field names against type definitions