# Code Audit Prompt

You are performing a deep structural audit of this codebase. Your job is NOT to summarize what the code does. Your job is to find specific, concrete problems — with file paths, line numbers, and evidence.

Work through each section below. For every finding, provide:

- **File + line range**
- **What's wrong** (one sentence)
- **Evidence** (show the specific code or pattern)
- **Suggested fix** (concrete, not vague)

If a section has no findings, say "No issues found" and move on. Do not pad with praise.

## Part 1: API Surface Complexity

For every module that exports functions, types, or classes:

1. **Count the exports.** Flag any module with more than 7 public exports. List them.
2. **Check for "config object" sprawl.** Find functions that accept option objects with more than 5 keys, especially where most callers only use 2-3 of them. Show the function signature and a representative call site.
3. **Find unnecessary indirection.** Look for exported functions that are thin wrappers around one other function call with no meaningful transformation. Show both sides.
4. **Identify mixed abstraction levels.** Flag modules that export both low-level primitives AND high-level orchestration functions. List the exports grouped by abstraction level.
5. **Check for "stringly typed" APIs.** Find function parameters where a string is used but only a finite set of values is valid. Show the parameter and all the values it actually receives across the codebase.

## Part 2: Process Structure

Trace every multi-step workflow, pipeline, or state machine in the codebase:

1. **Map the actual execution order.** For each process, list the steps as they actually execute (not as comments or docs describe them). Flag any divergence between documented and actual order.
2. **Find unreachable steps.** Identify process branches guarded by conditions that can never be true given upstream logic. Show the guard condition and why it's dead.
3. **Check error handling completeness.** For each step in a process, verify: Does it handle the failure of the previous step? Or does it silently assume success? List gaps.
4. **Find "wishful thinking" patterns.** These are sequences where Step N+1 depends on a side effect of Step N that isn't guaranteed — e.g., assuming a database write succeeded without checking, assuming a queue message was delivered, assuming a file exists after a write call.
5. **Identify retry/recovery confusion.** Find places where retry logic exists but the operation isn't idempotent, or where recovery logic re-runs steps that have already committed side effects.

## Part 3: State Redundancy

For every stateful construct (database tables, state objects, Redux/Zustand stores, GenServer state, context objects):

1. **Find derived data stored as source data.** Identify any field that could be computed from other fields in the same state. Show the field and the derivation.
2. **Find synchronized duplicates.** Identify the same logical value stored in two places that must be kept in sync. Show both locations and whether there's a sync mechanism or if it's manual.
3. **Check for stale state.** Find fields that are set during initialization but never updated, even though the source they were derived from can change. Show the init path and the missing update path.
4. **Find "just in case" fields.** Identify state fields that are written but never read, or read only in dead code paths.
5. **Check state shape vs. access patterns.** Find nested state structures where consumers always destructure the same 2-3 fields. This suggests the state shape doesn't match how it's used.

## Part 4: Test Quality

### 4a: Complexity & Speed

1. **Find slow tests.** Any test file with setup logic that hits a real database, network, or filesystem — flag it. Show the setup code.
2. **Find over-mocked tests.** Tests where more than 50% of the test body is mock setup rather than assertions. List them with mock-to-assertion ratio.
3. **Find assertion-free tests.** Tests that execute code but never assert anything (or only assert that no error was thrown). These are "smoke tests pretending to be unit tests."
4. **Find tests with complex conditional logic.** Tests containing if/else, loops, or try/catch in the test body itself. Tests should be linear. List violations.

### 4b: Overlapping & Duplicate Tests

1. **Group tests by the code path they exercise.** Find sets of 3+ tests that all trigger the same function with similar inputs and check similar outputs. List the groups.
2. **Find copy-paste test patterns.** Tests that are structurally identical except for one or two values. Show the repeated structure and the varying parts.
3. **Find tests that are strict subsets.** Test A checks X. Test B checks X AND Y. Test A is redundant. List these pairs.

### 4c: Implementation Coupling

1. **Find tests that assert on internal state.** Tests that reach into private fields, check internal data structures, or assert on intermediate values that aren't part of the public contract. Show the assertion and what the public contract actually is.
2. **Find tests that mock internals.** Tests that mock private methods, internal helpers, or implementation-specific dependencies rather than boundary interfaces. Show the mock and what boundary it should mock instead.
3. **Find tests that break on refactor.** Tests that would fail if you changed the implementation without changing the behavior. The signal: the test asserts on HOW something happens rather than WHAT the result is.

### 4d: Dead Tests

1. **Find conditionally skipped tests** where the skip condition is always true. Show the condition and why.
2. **Find tests behind feature flags that are permanently off.** Trace the flag value.
3. **Find test files that aren't included in any test runner configuration.** Check test config files (jest.config, vitest.config, mix.exs, etc.) against actual test file paths.
4. **Find `describe` or `context` blocks where the setup creates a state that makes all inner tests follow the same path.** The tests look different but they're all testing the same thing.

## Part 5: Full-Stack Traceability

Pick every user-facing action (button click, form submit, API call from UI). For each one, trace the full round trip:

### 5a: Naming Consistency

Trace the name of every entity and field from UI → API call → route handler → service/business logic → database query → database schema, and back up through the response.

Flag every point where the name changes in a way that isn't a deliberate, documented convention. Specifically:

- **Case changes**: `userId` → `user_id` → `UserID` → `userid`. List the full chain with file + line for each hop.
- **Semantic drift**: `accountId` in the UI becomes `orgId` in the API becomes `tenantId` in the database. Same value, different names. List these.
- **Abbreviation inconsistency**: `transaction` in one layer, `txn` in another, `trans` in a third. List these.
- **Pluralization mismatches**: `user` in one place, `users` in another, for the same single record. List these.

### 5b: Type Consistency

Trace the type of every value through the full stack:

- **String-to-number mismatches**: A value that's a string in the URL/query param, parsed to a number in the handler, but compared to a string in the database. Show the full chain.
- **Nullable mismatches**: A field that's required in the UI form, optional in the API schema, nullable in the database. Show each layer's constraint.
- **Enum mismatches**: A value constrained to specific options in the UI (dropdown) but accepted as a free string in the API or DB. Show the UI constraint and the missing validation.
- **Date/time format mismatches**: ISO string in one layer, Unix timestamp in another, Date object in a third. Show the conversions (or missing conversions).

### 5c: Argument/Parameter Consistency

For every function call across a boundary (UI→API, API→service, service→DB):

- **Argument order mismatches**: Function defined as `(userId, orgId)` but called as `(orgId, userId)`. Check both named and positional args.
- **Missing arguments**: Function expects 4 params, caller sends 3. Check for silent `undefined` values.
- **Extra arguments**: Caller sends fields that the receiver ignores. These are often leftover from refactors.
- **Default value traps**: Function has a default that's subtly wrong for a specific caller's context (e.g., `limit = 10` when one caller actually needs all results).

### 5d: Error Propagation

For each traced action:

- **Does every layer handle errors from the layer below?** Or does a database constraint violation surface as a raw 500?
- **Are error codes/messages consistent?** Or does the same root cause produce different user-facing errors depending on which code path hit it?
- **Are there swallowed errors?** Empty catch blocks, `.catch(() => {})`, or error handlers that log but don't propagate.
- **Is validation at the right layer?** Find validation that exists in the UI but not in the API (bypassable), or in the API but not in the DB (race conditions).

## Output Format

Organize findings by severity:

### Critical (will cause bugs or data corruption)

### Major (will cause confusion, tech debt accumulation, or test unreliability)

### Minor (cleanup opportunities, style inconsistencies)

Within each severity, group by the Part number above. Every finding must have a file path and line range. No finding should be vague or theoretical — show the code.