Universal audit pattern

Universal Audit Pattern

Category: Quality Time Saved: 4+ hours per audit Battle-tested: Yes — applied to docs, code, security, architecture

---

The Problem

You need to audit something — documentation accuracy, code quality, security compliance, architectural drift. You start checking things randomly, fix some issues, get distracted, lose track of what you've reviewed.

Why Ad-Hoc Audits Fail

• No systematic coverage — you miss things
• No severity ranking — you fix minor issues while critical ones wait
• No completion criteria — you don't know when you're done
• No reproducibility — next audit starts from scratch

The Rule

Inventory → Compare to Ground Truth → Severity-Classify → Fix All

This four-step pattern works for any domain where claims can drift from reality.

The Pattern

Step 1: Inventory

Create a complete list of items to audit. Be exhaustive.

## Inventory

| # | Item | Location | Status |
|---|------|----------|--------|
| 1 | Test count claim | README.md:45 | Pending |
| 2 | API endpoint list | docs/api.md | Pending |
| 3 | Version requirement | package.json | Pending |
| ... | ... | ... | ... |

Step 2: Compare to Ground Truth

For each item, verify against the authoritative source.

## Ground Truth Comparison

| # | Claim | Ground Truth | Match? |
|---|-------|--------------|--------|
| 1 | "47 tests" | `npm test` shows 89 | ❌ |
| 2 | "5 endpoints" | OpenAPI spec has 7 | ❌ |
| 3 | "Node 16+" | engines: ">=20" | ❌ |

Step 3: Severity-Classify

Prioritize by impact, not discovery order.

Severity	Criteria	Example
Critical	Breaks functionality, security risk	Wrong API URL
High	Misleads users significantly	Wrong version requirements
Medium	Inaccurate but not harmful	Outdated feature list
Low	Cosmetic, minor	Typos in comments

## Classified Findings

### Critical (fix immediately)
- [ ] #12: Security config example has hardcoded secret

### High (fix this sprint)
- [ ] #3: Version requirement mismatch
- [ ] #7: Deprecated API still documented

### Medium (fix when touched)
- [ ] #1: Test count outdated
- [ ] #2: Endpoint count wrong

### Low (backlog)
- [ ] #15: Typo in contributing guide

Step 4: Fix All

Work through findings by severity. Mark each as done.

## Resolution Log

| # | Finding | Fix | Commit |
|---|---------|-----|--------|
| 12 | Hardcoded secret | Replaced with env var | abc123 |
| 3 | Wrong Node version | Updated to >=20 | def456 |
| ... | ... | ... | ... |

Domain Applications

Documentation Audit

• Inventory: All claims with numbers, versions, paths
• Ground Truth: Code, configs, API specs, runtime output
• Severity: Accuracy impact on users

Security Audit

• Inventory: All auth flows, data handling, dependencies
• Ground Truth: OWASP checklist, CVE database
• Severity: Exploitability × Impact

Architecture Audit

• Inventory: All system components, integrations
• Ground Truth: Actual deployed infrastructure
• Severity: Drift from intended design

Code Quality Audit

• Inventory: All modules, functions, tests
• Ground Truth: Style guide, coverage targets
• Severity: Maintainability impact

Template

# [Domain] Audit Report

**Date**: YYYY-MM-DD
**Auditor**: Name
**Scope**: What's being audited

## Executive Summary

- Items audited: N
- Findings: X critical, Y high, Z medium
- Status: In progress / Complete

## Inventory

| # | Item | Location | Status |
|---|------|----------|--------|
| 1 | ... | ... | ... |

## Findings by Severity

### Critical
- [ ] ...

### High
- [ ] ...

### Medium
- [ ] ...

### Low
- [ ] ...

## Resolution Log

| # | Finding | Fix | Verified |
|---|---------|-----|----------|
| ... | ... | ... | ... |

## Recommendations

1. ...
2. ...

Verification Checklist

• Inventory is complete (not just obvious items)
• Ground truth is authoritative (not another doc)
• Severity based on impact, not effort
• Every finding has resolution or explicit deferral
• Audit is reproducible (someone else could re-run it)

Related Skills

• docs-decay-velocity — Why docs need auditing
• allowlist-over-blocklist — Audit approach for validation