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

On violation: Extract content to Tier 2 CONTEXT.md files

2. Tier 1 File Count (CRITICAL)

Limit: Exactly 2 files in docs/ai-context/

COUNT=$(find docs/ai-context -maxdepth 1 -name "*.md" -type f | wc -l | tr -d ' ')
if [ "$COUNT" -ne 2 ]; then
  echo "FAIL: docs/ai-context/ has $COUNT files (expected: 2)"
  exit 1
fi

3. Cross-Reference Validation (Changed Files Only)

# Only validate changed files
for file in $CHANGED_MD; do
  [ -f "$file" ] || continue
  grep -oE '@\.(claude|docs)/[^][:space:]]+' "$file" 2>/dev/null | while read ref; do
    ref_path="${ref#@}"
    ref_path="${ref_path%[\`\*\]\"]}"
    if [ ! -e "$ref_path" ]; then
      echo "Broken reference: $ref in $file"
    fi
  done
done

4. Circular Reference Detection

# Check for self-references (A → A)
find . -name "*.md" ! -path "*/REFERENCE.md" ! -path "*/.git/*" | while read file; do
  refs=$(grep -oE '@\.(claude|docs)/[^)[:space:]+' "$file" || true)
  for ref in $refs; do
    if [ "${ref#@}" = "$file" ]; then
      echo "Self-reference: $file"
    fi
  done
done

5. Skill Count Validation

ACTUAL=$(find .claude/skills -name "SKILL.md" | wc -l | tr -d ' ')
STATED=$(grep -oE '\*\*[0-9]+ Skills\*\*' README.md | grep -oE '[0-9]+' || echo "0")

if [ "$ACTUAL" -ne "$STATED" ]; then
  echo "WARNING: Skill count mismatch - README: $STATED, actual: $ACTUAL"
fi

Integration Pattern

In Commands

## Step 3: Documentation Verification

Invoke the `docs-verify` skill to validate documentation compliance.

The skill checks:
- Tier 1 line limits (≤200 lines)
- Tier 1 file count (exactly 2 in ai-context/)
- Cross-reference validity
- Circular references

Claude reads this skill file and executes the bash commands inline.

Related Skills

three-tier-docs: Full 3-Tier documentation system | vibe-coding: File size standards

Version: claude-pilot 4.4.14