scan

doc-sentinel:scan

Deep scan that cross-references all documentation against the current state of the codebase. Unlike the hook (which checks only files changed in a commit), this scans everything.

This skill is read-only — it reports drift but does not modify files.

Phase 1: Load Configuration

cat .doc-sentinel.json 2>/dev/null || echo "No config — using defaults"

Defaults if no config:

• docs_root: docs
• watch_files: AGENTS.md, ARCHITECTURE.md, README.md, CLAUDE.md
• ignore_sources: *.test.*, *.spec.*, __tests__/**

Phase 2: Discover Documentation

Collect all doc files:

# docs/ directory
find docs/ -name '*.md' -type f 2>/dev/null | sort

# Top-level docs
for f in AGENTS.md ARCHITECTURE.md CLAUDE.md README.md CHANGELOG.md; do
  [ -f "$f" ] && echo "$f"
done

Plus any watch_files from config.

Phase 3: Extract References

For each doc file, extract references to source code:

3a: File Path References

Search for paths that look like source file references:

# Extract paths from backticks, links, and code blocks
grep -oE '`[a-zA-Z0-9_./-]+\.(ts|js|py|rb|go|rs|java|tsx|jsx)`' "$doc_file"
grep -oE '\b(src|lib|app|packages)/[a-zA-Z0-9_./-]+' "$doc_file"

3b: Command References

Extract shell commands documented in the file:

# Find code blocks with shell commands
grep -E '^\$|^pnpm |^npm |^yarn |^cargo |^go |^bundle |^python |^make ' "$doc_file"

3c: Port and URL References

grep -oE '(localhost|127\.0\.0\.1):[0-9]+' "$doc_file"
grep -oE ':[0-9]{4,5}\b' "$doc_file"

3d: Environment Variable References

grep -oE '\$\{?[A-Z_][A-Z0-9_]*\}?' "$doc_file"
grep -oE '`[A-Z_][A-Z0-9_]*`' "$doc_file"

Phase 4: Validate References

For each extracted reference, check if it still holds:

4a: File Paths — Do They Exist?

# For each extracted path
[ -f "$path" ] && echo "OK: $path" || echo "DRIFT: $path — file not found"

4b: Directory References — Do They Exist?