docs-verify

SKILL: Documentation Verification

Purpose: Validate 3-Tier documentation system compliance - line limits, cross-references, file counts

---

Quick Start

When to Use

• After closing plan (/03_close)
• After running /document
• Before committing documentation changes

Quick Reference

# Pure bash link check (no external deps)
for file in CLAUDE.md docs/ai-context/*.md; do
  [ -f "$file" ] || continue
  grep -oE '@[^][:space:]]+' "$file" | while read ref; do
    ref_path="${ref#@}"
    [ ! -e "$ref_path" ] && echo "Broken: $ref in $file"
  done
done

---

Change Detection (MANDATORY FIRST STEP)

Before running verification, check if docs changed:

# Get changed markdown files (with fallback)
CHANGED_MD=$(git diff --name-only HEAD~1 -- "*.md" 2>/dev/null || git diff --name-only -- "*.md" 2>/dev/null || echo "FALLBACK_FULL_VERIFY")

# Fallback: If git diff fails, run full verification
if [ "$CHANGED_MD" = "FALLBACK_FULL_VERIFY" ]; then
    echo "Cannot detect changes, running full verification"
    CHANGED_MD=$(find . -name "*.md" -type f ! -path "*/.git/*" ! -path "*/.trash/*")
fi

if [ -z "$CHANGED_MD" ]; then
    echo "No markdown files changed"
    echo "Skipping documentation verification"
    exit 0
fi

echo "Changed markdown files:"
echo "$CHANGED_MD"

---

Core Concepts

3-Tier System

Tier 1 (3 files, ≤200 lines each):

• CLAUDE.md - Project architecture, features, Quick Start
• docs/ai-context/project-structure.md - Tech stack, file tree
• docs/ai-context/docs-overview.md - Documentation navigation

Tier 2: Component CONTEXT.md files (unlimited)

Tier 3: Feature-specific CONTEXT.md files

---

Verification Checks

1. Tier 1 Line Limits (Changed Files Only)

Limit: ≤200 lines per file

TIER1_FILES=(
  "CLAUDE.md"
  "docs/ai-context/project-structure.md"
  "docs/ai-context/docs-overview.md"
)

for file in "${TIER1_FILES[@]}"; do
  # Only check if file was changed
  if echo "$CHANGED_MD" | grep -q "$file"; then
    LINES=$(wc -l < "$file" | tr -d ' ')
    if [ "$LINES" -gt 200 ]; then
      echo "FAIL: $file has $LINES lines (limit: 200)"
      exit 1
    fi
    echo "$file: $LINES lines"
  fi
done