Step 1: Output Messages

Start Message:

🎯 STARTING: Documentation Validation
Target: {file_or_directory}
Checks: {checks_list}
───────────────────────────────────────

Step 2: Validate Input Parameters

Check required parameters:

• target: File path or directory (required)
• checks: Array of checks to run (optional, default: all)
• doc_type: Expected document type (optional, for structure validation)
• strict: Treat warnings as errors (optional, default: false)

Validation Checks Available:

• markdown-lint: Markdown syntax and style
• frontmatter: Front matter structure and required fields
• structure: Required sections per document type
• links: Internal and external link validity
• all: Run all checks (default)

Step 3: Determine Validation Scope

Single File:

if [[ -f "$TARGET" ]]; then
  validate_single_file "$TARGET"
fi

Directory:

if [[ -d "$TARGET" ]]; then
  find "$TARGET" -name "*.md" -type f | while read file; do
    validate_single_file "$file"
  done
fi

Step 4: Run Validation Checks

For each file, run requested checks:

Check 1: Markdown Linting

Invoke lint-markdown.sh:

./skills/doc-validator/scripts/lint-markdown.sh --file "$FILE_PATH"

Checks:

• Line length (< 120 characters recommended)
• Heading incrementing (don't skip levels)
• List marker consistency
• Code block language tags
• Trailing whitespace
• Multiple blank lines
• Hard tabs vs spaces

Returns:

{
  "success": true,
  "file": "/path/to/doc.md",
  "issues": [
    {
      "line": 42,
      "rule": "MD013",
      "severity": "warning",
      "message": "Line length exceeds 120 characters"
    }
  ]
}

Check 2: Front Matter Validation

Invoke check-frontmatter.sh:

./skills/doc-validator/scripts/check-frontmatter.sh --file "$FILE_PATH"

Checks:

• Front matter exists
• Valid YAML syntax
• Required fields present (title, type, date)
• Field types correct (string, array, boolean)
• Status value valid for document type
• Date format correct (YYYY-MM-DD)
• Tags are array of strings
• Related paths exist

Returns:

{
  "success": true,
  "file": "/path/to/doc.md",
  "has_frontmatter": true,
  "issues": [
    {
      "field": "status",
      "severity": "error",
      "message": "Invalid status value 'draft' for type 'adr'. Valid: proposed, accepted, deprecated, superseded"
    }
  ]
}

Check 3: Structure Validation

Invoke validate-structure.sh:

./skills/doc-validator/scripts/validate-structure.sh \
  --file "$FILE_PATH" \
  --doc-type "$DOC_TYPE" \
  --required-sections "$REQUIRED_SECTIONS_JSON"

Checks:

• Required sections present
• Section heading levels correct
• Sections in logical order
• No duplicate section headings
• Subsection hierarchy valid

Returns:

{
  "success": true,
  "file": "/path/to/doc.md",
  "doc_type": "adr",
  "sections_found": ["Status", "Context", "Decision", "Consequences"],
  "issues": [
    {
      "section": "Alternatives Considered",
      "severity": "warning",
      "message": "Recommended section missing"
    }
  ]
}

Check 4: Link Validation

Invoke check-links.sh:

./skills/doc-validator/scripts/check-links.sh \
  --file "$FILE_PATH" \
  --check-external "$CHECK_EXTERNAL"

Checks:

• Internal links to markdown files exist
• Anchor links valid (heading exists)
• External links accessible (optional)
• Image links valid
• No broken relative paths

Returns:

{
  "success": true,
  "file": "/path/to/doc.md",
  "links_checked": 12,
  "issues": [
    {
      "line": 45,
      "link": "../api/missing-api.md",
      "severity": "error",
      "message": "Broken internal link: file not found"
    }
  ]
}

Step 5: Aggregate Results

Collect all issues from all checks:

{
  "files_checked": 15,
  "files_passed": 12,
  "files_failed": 3,
  "total_issues": 8,
  "issues_by_severity": {
    "error": 2,
    "warning": 4,
    "info": 2
  },
  "issues": [...]
}

Step 6: Determine Validation Status

Logic:

• If any errors: "failed"
• If only warnings: "warnings"
• If only info: "passed"
• If no issues: "passed"

Strict Mode:

• If strict enabled: warnings treated as errors
• Status: "failed" if errors OR warnings

Step 7: Output End Message

✅ COMPLETED: Documentation Validation
Files Checked: {count}
Status: {passed/warnings/failed}
Issues: {total} ({errors} errors, {warnings} warnings)
───────────────────────────────────────
Next: Review issues and fix errors

Step 8: Return Structured Result

Return JSON with all issues:

{
  "success": true,
  "operation": "validate-directory",
  "target": "docs/",
  "files_checked": 15,
  "files_passed": 12,
  "files_failed": 3,
  "total_issues": 8,
  "issues_by_severity": {
    "error": 2,
    "warning": 4,
    "info": 2
  },
  "validation_status": "warnings",
  "issues": [
    {
      "file": "docs/architecture/adrs/ADR-001.md",
      "line": 42,
      "severity": "error",
      "check": "structure",
      "message": "Missing required section: Consequences"
    },
    {
      "file": "docs/api/user-api.md",
      "line": 15,
      "severity": "warning",
      "check": "markdown-lint",
      "rule": "MD013",
      "message": "Line length exceeds 120 characters"
    }
  ],
  "timestamp": "2025-01-15T12:00:00Z"
}