comprehensive-audit

---
name: comprehensive-audit
description: >
  Exhaustive whole-codebase logic audit performed simultaneously through the lenses of a senior
  architect, staff engineer, QA lead, security engineer, and performance engineer. Hunts for
  incorrect behavior, hidden bugs, missing edge cases, race conditions, data-integrity risks,
  insecure logic, performance traps, architectural flaws, and inconsistencies — then produces a
  structured written report with severity, evidence, recommended fixes, confidence, and a final
  scorecard (code quality / production readiness / technical debt). Use this whenever the user
  wants a deep or "complete" review of a codebase rather than a quick look — triggers on
  "comprehensive audit", "full codebase audit", "complete logic audit", "audit the whole codebase",
  "find all the bugs", "deep code review", "exhaustive review", "review everything", "what's wrong
  with this codebase", "production readiness review", "code quality audit", "technical debt
  assessment", or any request to thoroughly analyze a codebase for correctness, security,
  performance, and architecture at once. Prefer this over a casual review whenever the user signals
  they want depth, breadth, or a written findings report.
---

# Comprehensive Codebase Logic Audit

## Role

Act as a senior software architect, staff engineer, QA lead, security engineer, and performance
engineer **simultaneously**. The job is a *complete logic audit* of the codebase — not a style or
formatting pass. The primary objective is to discover incorrect behavior, hidden bugs, missing
edge cases, architectural flaws, inconsistencies, and concrete opportunities for improvement.

## Operating Principles

These shape every decision below — internalize them rather than treating them as a checklist:

- **Analyze every file that could influence application behavior.** Coverage is the point; a
  partial audit hides exactly the bug the user needed found.
- **Follow execution paths across modules.** Bugs live in the seams between components, not inside
  any single tidy function. Trace data and control from entrypoint to side effect.
- **Never assume code is correct because tests pass.** Tests encode the author's assumptions; if
  those assumptions are wrong, green tests are false comfort. Verify behavior against *intended*
  behavior, not against the test suite.
- **Think like someone trying to break the application.** Adversarial framing surfaces edge cases
  that defensive reading glides past.
- **Treat TODOs, FIXMEs, disabled code, feature flags, and commented-out blocks as in-scope.**
  They mark known-fragile areas and half-finished logic — prime bug territory.
- **Never stop after finding one issue.** Keep going until you have exhaustively analyzed every
  reachable part of the codebase and can no longer identify meaningful improvements. A short
  report on a large codebase usually means the audit stopped early, not that the code is clean.

## How to Work

1. **Map the codebase first.** Identify entrypoints, modules, layers, external boundaries (HTTP,
   DB, queues, filesystem, third-party APIs), and the main execution paths. Read configuration,
   build files, and dependency manifests — runtime behavior often hides there.
2. **Audit through each lens below in turn.** The lenses overlap on purpose; a single line can be
   a correctness bug *and* a security hole *and* a performance trap. Record it under whichever lens
   makes the impact clearest, but don't skip a lens because "something else probably covers it."
3. **For large codebases, fan out.** If the codebase is too large to hold in one pass, dispatch
   parallel exploration agents — e.g. one per lens or one per module — to read and report findings,
   then consolidate. This preserves coverage without exhausting a single context. Keep the report
   format identical regardless of how the work was split.
4. **Verify before reporting.** Every finding must be grounded in the actual source and a
   *reachable* code path — not dead code and not a hypothetical. Trace the path that triggers it.
5. **Write the report** using the exact output format below.

---

## Audit Lenses

Work through each of these. For each bullet, ask "where could this go wrong here, and what input
or sequence would expose it?"

### Business Logic
Incorrect algorithms · broken workflows · missing validation · incorrect assumptions · missing
error handling · infinite loops · dead code · impossible conditions · race conditions · state
corruption · invalid state transitions · data-loss risks · hidden edge cases · incorrect default
values · incorrect fallbacks · duplicate or contradictory business rules · logic duplicated across
multiple places. **Verify the implementation matches the intended behavior**, not just that it
parses.

### Control Flow
Conditional branches · nested logic · early returns · exception paths · retry logic · timeouts ·
cancellation handling · async execution · parallel execution · event ordering · queue processing ·
background jobs · scheduling logic. Look specifically for paths that are **never executed** or
**unexpectedly executed**.

### State Management
Global state · cache consistency · persistence · session handling · user state · synchronization ·
state mutations · rollback behavior · transaction boundaries. Ensure state remains valid after
*every* operation, including partial failures.

### Data Integrity
Input validation · output validation · DTO mapping · serialization · deserialization · database
writes · database reads · migrations · foreign-key assumptions · duplicate records · null handling ·
type conversions. Ensure no data corruption is possible.

### API Logic
For every endpoint: input validation · authentication · authorization · correct HTTP status codes ·
error responses · pagination · filtering · sorting · idempotency · rate limiting · retry safety ·
version compatibility. Ensure every endpoint behaves consistently.

### UI Logic
Component state · navigation · routing · loading states · empty states · error states · race
conditions · form validation · accessibility behavior · responsive behavior · feature availability.
Ensure the UI always reflects the actual application state.

### Security Logic
Authentication flow · authorization rules · permission inheritance · secret handling · token
lifecycle · session expiration · CSRF · XSS · injection · SSRF · path traversal · file uploads ·
validation bypasses · business-logic abuse · privilege escalation. **Assume an attacker is actively
trying to exploit the application** and reason about what they could reach.

### Performance Logic
N+1 queries · repeated work · unnecessary allocations · blocking operations · inefficient
algorithms · cache misuse · memory leaks · resource leaks · large object creation · excessive
rendering · excessive network requests · lock contention. Recommend concrete optimizations, not
vague "make it faster."

### Architecture
Module boundaries · layering · separation of concerns · dependency direction · circular
dependencies · tight coupling · feature cohesion · code duplication · missing abstractions ·
over-engineering · under-engineering. Recommend architectural improvements with reasoning.

### Test Coverage
Determine whether every branch is tested · every feature has tests · edge cases are tested · error
paths are tested · security behavior is tested · performance assumptions are tested · concurrency
is tested · regression tests exist. Recommend the specific tests that are missing.

### Hidden Bugs (actively hunt for these)
Off-by-one errors · overflow/underflow · integer conversion issues · floating-point issues ·
timezone bugs · date-arithmetic bugs · locale assumptions · encoding problems · Unicode bugs ·
platform-specific issues · environment-specific bugs. These rarely announce themselves — probe for
them deliberately.

### Inconsistencies (compare and highlight every mismatch)
Documentation vs implementation · UI vs backend behavior · API vs database · tests vs
implementation · configuration vs runtime behavior · feature flags vs actual features.

### Improvements
Wherever possible propose simpler logic · safer logic · better algorithms · better abstractions ·
better validation · better naming · better error messages · better resilience · better
maintainability. **Explain why each improvement matters** — the reasoning is what makes it
actionable.

---

## Output Format

Report **every** issue using this exact template:

```
## Issue: <concise title>

### Severity
Critical / High / Medium / Low

### Location
File(s), function(s), class(es), or module(s) — with line numbers where possible.

### Description
What the problem is.

### Why it matters
The potential impact (data loss, breach, outage, wrong results, etc.).

### Evidence
The relevant code path or the reasoning that proves the issue is real and reachable.

### Recommended Fix
A concrete implementation strategy.

### Confidence
High / Medium / Low
```

Order issues by severity (Critical first). Group related issues if it aids clarity, but never drop
the per-issue fields.

---

## Final Summary

After the issues, close with:

- **Total issues by severity** (counts of Critical / High / Medium / Low)
- **Most dangerous logic flaw**
- **Highest-risk architectural issue**
- **Biggest maintainability problem**
- **Largest performance opportunity**
- **Biggest security concern**
- **Estimated overall code quality** (0–10)
- **Estimated production readiness** (0–10)
- **Estimated technical debt** (0–10)

Finally, identify the **single highest-impact improvement** — the one change that, if implemented
first, would most increase the codebase's correctness, reliability, and maintainability. Explain
why it ranks above the others.

Do not stop after a few issues. Continue until the reachable codebase is exhausted and no further
meaningful improvement can be identified.