OGT Docs - Audit

Root skill for running documentation and project audits.

Overview

Audits verify that documentation matches reality and that project standards are being followed. This skill routes to specialized audit types.

flowchart TB
    AUDIT["ogt-docs-audit"] --> TASK["ogt-docs-audit-task"]
    AUDIT --> DEF["ogt-docs-audit-define"]
    AUDIT --> RULES["ogt-docs-audit-rules"]
    AUDIT --> CODE["ogt-docs-audit-code"]
    AUDIT --> DRIFT["ogt-docs-audit-drift"]

    TASK --> |verify| DONE["done/ tasks"]
    DEF --> |validate| DEFS["definitions"]
    RULES --> |check| ENFORCEMENT["rule enforcement"]
    CODE --> |scan| CODEBASE["codebase"]
    DRIFT --> |compare| SYNC["docs vs code"]

When to Use

• Before releases to validate project health
• Periodically (weekly/monthly) for maintenance
• When onboarding to understand current state
• After major changes to verify consistency
• When bugs suggest documentation drift

Audit Types

Quick Commands

# Full project audit
ogt audit all

# Specific audit types
ogt audit tasks              # Verify done/ tasks
ogt audit definitions        # Check definition completeness
ogt audit rules              # Verify rule enforcement
ogt audit drift              # Find docs/code mismatches

Audit: Tasks

Verify that completed tasks have working implementations.

Delegate to: ogt-docs-audit-task

ogt audit tasks

See ogt-docs-audit-task for complete documentation.

Audit: Definitions

Validate that definitions are complete and consistent.

What It Checks

Folder Audit

# Audit all definitions
find docs/define -type d -mindepth 2 | while read dir; do
  if [ ! -f "$dir/definition.md" ] && [ ! -f "$dir/feature.md" ]; then
    echo "MISSING: $dir needs primary document"
  fi
done

Completeness Audit

Check that definitions have required sections:

# For each definition.md, check for required sections
for file in $(find docs/define -name "definition.md"); do
  missing=""
  grep -q "## Summary" "$file" || missing+="Summary "
  grep -q "## Details\|## The " "$file" || missing+="Details "

  if [ -n "$missing" ]; then
    echo "INCOMPLETE: $file missing: $missing"
  fi
done

Example Output

Auditing definitions...

docs/define/features/
  ✓ user_auth/feature.md - Complete
  ✓ search/feature.md - Complete
  ✗ notifications/ - MISSING feature.md

docs/define/code/services/
  ✓ auth_service/definition.md - Complete
  ✗ api_client/definition.md - Missing: Examples section

Summary:
  Total: 24
  Complete: 21
  Incomplete: 2
  Missing: 1

Audit: Rules

Verify that rules are enforced and up-to-date.

What It Checks

Enforcement Audit

# For each rule, verify enforcement mechanism exists
for rule_dir in $(find docs/rules -type d -mindepth 2); do
  enforced_by="$rule_dir/.enforced_by"

  if [ ! -f "$enforced_by" ]; then
    echo "MISSING: $rule_dir has no .enforced_by"
    continue
  fi

  # Check each enforcement mechanism
  while read mechanism; do
    case "$mechanism" in
      eslint*)
        grep -q "eslint" package.json || echo "  NOT CONFIGURED: eslint"
        ;;
      commitlint*)
        grep -q "commitlint" package.json || echo "  NOT CONFIGURED: commitlint"
        ;;
      husky*)
        test -d .husky || echo "  NOT CONFIGURED: husky"
        ;;
    esac
  done < "$enforced_by"
done

Compliance Audit

Check if codebase follows rules:

# Example: Check naming convention compliance
# Rule: React components must be PascalCase

find src -name "*.tsx" -type f | while read file; do
  basename=$(basename "$file" .tsx)
  if [[ ! "$basename" =~ ^[A-Z] ]]; then
    echo "VIOLATION: $file - Component not PascalCase"
  fi
done

Example Output

Auditing rules...

docs/rules/code/typescript/
  ✓ strict_mode - Enforced by: tsc
  ✓ no_any - Enforced by: eslint

docs/rules/git/commits/
  ✓ conventional - Enforced by: commitlint
  ✗ conventional - NOT ENFORCED: husky not installed

docs/rules/code/naming/files/
  ✗ kebab_case - 3 violations found

Summary:
  Rules: 12
  Enforced: 10
  Unenforced: 1
  Violations: 3

Audit: Drift

Find mismatches between documentation and code.

What It Checks

File Reference Audit

# Find file paths in docs and verify they exist
grep -roh "src/[^[:space:]\"'\`]*\.\(ts\|tsx\|js\)" docs/ | sort -u | while read path; do
  if [ ! -f "$path" ]; then
    echo "DRIFT: $path referenced in docs but doesn't exist"
  fi
done

API Drift Audit

# Compare documented endpoints to actual routes
# Extract from docs
grep -roh "POST\|GET\|PUT\|DELETE /api/[^[:space:]]*" docs/ | sort -u > /tmp/doc-endpoints

# Extract from code
grep -roh "router\.\(post\|get\|put\|delete\)(['\"][^'\"]*" src/routes/ | sort -u > /tmp/code-endpoints

# Compare
diff /tmp/doc-endpoints /tmp/code-endpoints

Example Output

Auditing for drift...

File References:
  ✗ docs/define/code/services/auth.md references:
    - src/services/AuthService.ts (EXISTS)
    - src/services/TokenManager.ts (MISSING - was renamed to TokenService.ts)

API Endpoints:
  ✗ docs/define/code/api/users.md documents:
    - POST /api/users (EXISTS)
    - GET /api/users/:id (EXISTS)
    - DELETE /api/users/:id (MISSING - not implemented)

Type Definitions:
  ✗ docs/define/code/data_models/user.md shows:
    - User.email: string (MATCHES)
    - User.role: 'admin' | 'user' (DRIFT - code has 'admin' | 'user' | 'guest')

Summary:
  Checked: 45 references
  Valid: 41
  Drift: 4

Full Project Audit

Run all audits at once:

#!/bin/bash
# audit-all.sh

echo "=== OGT Full Project Audit ==="
echo "Date: $(date)"
echo ""

echo "## Task Audit"
ogt audit tasks
echo ""

echo "## Definition Audit"
./scripts/audit-definitions.sh
echo ""

echo "## Rules Audit"
./scripts/audit-rules.sh
echo ""

echo "## Drift Audit"
./scripts/audit-drift.sh
echo ""

echo "=== Audit Complete ==="

Audit Report Format

docs/todo/audit_log/{date}/summary.md

# Audit Summary: 2026-02-06

## Overview

| Audit Type  | Passed | Failed | Total  |
| ----------- | ------ | ------ | ------ |
| Tasks       | 15     | 3      | 18     |
| Definitions | 21     | 2      | 23     |
| Rules       | 10     | 1      | 11     |
| Drift       | 41     | 4      | 45     |
| **Total**   | **87** | **10** | **97** |

## Pass Rate

89.7%

## Critical Issues

1. **Task: spell_routes** - Never implemented (moved to pending/)
2. **Rule: commit format** - Husky not installed
3. **Drift: User.role** - Type mismatch between docs and code

## Recommendations

1. Install husky: `npm install -D husky`
2. Update User type documentation
3. Re-implement spell_routes task

## Next Audit

Scheduled: 2026-02-13

Scheduling Audits

CI Integration

# .github/workflows/audit.yml
name: Weekly Audit

on:
  schedule:
    - cron: "0 9 * * 1" # Monday 9am
  workflow_dispatch:

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run audits
        run: ./scripts/audit-all.sh > audit-report.md

      - name: Check for failures
        run: |
          if grep -q "FAIL\|MISSING\|DRIFT" audit-report.md; then
            echo "Audit found issues"
            cat audit-report.md
            exit 1
          fi

      - name: Upload report
        uses: actions/upload-artifact@v4
        with:
          name: audit-report
          path: audit-report.md

Local Cron

# Add to crontab
0 9 * * 1 cd /path/to/project && ./scripts/audit-all.sh >> logs/audit.log 2>&1

Signal Files Reference

Audit Checklist

Before considering an audit complete:

• All task audits run
• All definition folders checked
• All rules enforcement verified
• Drift check completed
• Failed items moved/documented
• Audit log created
• Summary generated
• Critical issues flagged
• Next audit scheduled