audit-code-complexity git:20260906.ccd7eadA

Immutable. This exact content is served forever at /api/v1/blob/d489e4ffbfd7d2db.

---
name: audit-code-complexity
description: Find needless code complexity and suggest simpler designs that preserve behavior.
---

# Audit code complexity

Find what is materially harder to understand, change, or verify than the problem requires.

## Scope

Choose from the user's wording:

- **Current-state.** Audit the target as it exists, regardless of when complexity was introduced.
- **Change-scoped.** Report only complexity introduced or materially worsened by the named changes. Inspect surrounding code only for context.

Do not infer change scope merely because a repository has changes. If both modes are requested, report them separately. Ask only when genuine ambiguity would materially change the audit.

## Method

Inspect the target, repository instructions, callers, tests, configuration, and only the requirements or docs needed to understand behavior and constraints.

Look for:

- unjustified indirection, wrappers, genericity, extension points, dependencies, or infrastructure
- tangled control flow, flag combinations, implicit state, invalid states, or multiple sources of truth
- repeated transformations, leaky types, wide APIs, hidden side effects, or unclear ownership
- duplicated policy, scattered edits for one change, or modules with unrelated responsibilities
- misleading names, distant cause and effect, broad mutation, dense expressions, or clever code
- speculative guards, fallbacks, compatibility paths, or dead machinery
- test harnesses, fixtures, mocks, or setup that make production behavior harder to understand or change

Smell names are optional vocabulary for explaining a concrete mechanism, not a checklist to exhaust or evidence of a violation. Use labels such as Feature Envy, Data Clumps, Shotgun Surgery, or Speculative Generality only when they make a finding clearer.

Include a finding only when:

1. The code creates a concrete maintenance, comprehension, correctness, or operational cost.
2. The claim is supported by code, usage, tests, or requirements.
3. A simpler alternative is concrete and preserves required behavior and contracts.
4. The benefit outweighs migration and regression risk.

Line count, nesting, complexity metrics, and unfamiliarity are clues, not findings.

## Test boundary

Inspect tests when they establish a contract, explain intended behavior, or provide evidence for a complexity finding.

Report test-related complexity only when the test architecture creates or conceals a concrete cost. Examples include shared setup with hidden state, helper layers that obscure behavior, duplicated fixtures that encode policy in several places, test-only seams that force production indirection, or mocks that hide unclear ownership.

Do not turn this into a general review of test value, coverage, snapshots, assertions, or missing cases. When tests are the main subject, use `test-quality-audit` instead.

## Output

Lead with a verdict, then prioritized findings. For each finding include:

- impact and confidence
- exact location and evidence
- concrete cost
- simpler alternative
- behavior or contracts that must remain unchanged

Add justified complexity, simplification order, and validation only when useful. If no material findings exist, say so directly.

## Rules

- Audit only; do not edit unless explicitly asked.
- Prefer local simplification over rewrites.
- Do not create an abstraction solely to remove similar-looking code; require a shared concept.
- Preserve domain distinctions, data semantics, source of truth, identity, routing, validation, security, accessibility, and compatibility.
- Skip formatter, linter, naming, and style nits unless they materially obscure behavior.
- Do not present an ordinary correctness bug as a complexity or simplification finding. Report bugs, security, or performance issues only when caused or concealed by the complexity under review, and label them separately from simplification findings.