documentation-audit

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: documentation-audit
description: Use when documentation drift is detected. Comprehensively audits codebase and creates/updates Swagger, features docs, and general documentation to achieve full sync.
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash
  - Edit
  - Write
  - Task
  - mcp__github__*
model: opus
---

# Documentation Audit

## Overview

Comprehensive documentation sync when drift is detected. Analyzes codebase and creates or updates all documentation artifacts to achieve full synchronization.

**Core principle:** Documentation must reflect reality. This skill brings them into alignment.

**Announce at start:** "I'm using documentation-audit to synchronize all documentation with the current codebase."

## When This Skill Triggers

This skill is invoked when:

| Trigger | Source |
|---------|--------|
| API documentation drift | `api-documentation` skill |
| Features documentation drift | `features-documentation` skill |
| Missing documentation files | Any documentation check |
| Manual request | User or orchestrator |

## The Audit Process

### Phase 1: Discovery

```bash
echo "=== Documentation Audit: Discovery Phase ==="

# Find all documentation files
DOC_FILES=$(find . -name "*.md" -o -name "*.yaml" -o -name "*.json" | \
  grep -E "(doc|api|swagger|openapi|feature|guide|readme)" | \
  grep -v node_modules | grep -v .git)

echo "Found documentation files:"
echo "$DOC_FILES"

# Find API documentation
API_DOC=$(find . -name "openapi.yaml" -o -name "swagger.yaml" -o -name "openapi.json" | head -1)
echo "API Documentation: ${API_DOC:-MISSING}"

# Find features documentation
FEATURE_DOC=$(find . -name "features.md" -o -name "FEATURES.md" | head -1)
echo "Features Documentation: ${FEATURE_DOC:-MISSING}"
```

### Phase 2: API Audit

If API endpoints exist:

```bash
echo "=== Documentation Audit: API Phase ==="

# Detect API framework
detect_api_framework() {
  if grep -r "express" package.json 2>/dev/null; then echo "express"; return; fi
  if grep -r "fastify" package.json 2>/dev/null; then echo "fastify"; return; fi
  if grep -r "@nestjs" package.json 2>/dev/null; then echo "nestjs"; return; fi
  if grep -r "fastapi" requirements.txt 2>/dev/null; then echo "fastapi"; return; fi
  if grep -r "flask" requirements.txt 2>/dev/null; then echo "flask"; return; fi
  if [ -f "go.mod" ]; then echo "go"; return; fi
  echo "unknown"
}

FRAMEWORK=$(detect_api_framework)
echo "Detected framework: $FRAMEWORK"

# Extract all endpoints from code
extract_endpoints() {
  case "$FRAMEWORK" in
    express|fastify)
      grep -rh "app\.\(get\|post\|put\|delete\|patch\)" --include="*.ts" --include="*.js" | \
        sed "s/.*app\.\([a-z]*\)('\([^']*\)'.*/\1 \2/"
      ;;
    nestjs)
      grep -rh "@\(Get\|Post\|Put\|Delete\|Patch\)" --include="*.ts" | \
        sed "s/.*@\([A-Za-z]*\)('\([^']*\)'.*/\1 \2/"
      ;;
    fastapi)
      grep -rh "@app\.\(get\|post\|put\|delete\|patch\)" --include="*.py" | \
        sed "s/.*@app\.\([a-z]*\)(\"\([^\"]*\)\".*/\1 \2/"
      ;;
    *)
      echo "Unknown framework - manual inspection required"
      ;;
  esac
}

ENDPOINTS=$(extract_endpoints)
echo "Found endpoints:"
echo "$ENDPOINTS"
```

### Phase 3: Features Audit

```bash
echo "=== Documentation Audit: Features Phase ==="

# Find user-facing components
find_features() {
  # React components in pages/views
  find . -path "*/pages/*" -name "*.tsx" -o -path "*/views/*" -name "*.tsx" | \
    xargs -I {} basename {} .tsx 2>/dev/null

  # Feature flags
  grep -rh "featureFlag\|feature:" --include="*.ts" --include="*.tsx" | \
    sed "s/.*['\"]feature[':]\s*['\"]?\([^'\"]*\)['\"]?.*/\1/" 2>/dev/null

  # Config options exposed to users
  grep -rh "config\.\|settings\." --include="*.ts" | \
    grep -v "import\|require" | \
    sed "s/.*\(config\|settings\)\.\([a-zA-Z]*\).*/\2/" 2>/dev/null | sort -u
}

FEATURES=$(find_features)
echo "Discovered features:"
echo "$FEATURES"
```

### Phase 4: Generate Missing Documentation

#### Create OpenAPI