simplicity-audit

Flag complexity not earned by a stated requirement.

Trigger on

• "is this overcomplicated"
• "simplify this"
• "does this need X"
• "review for over-engineering"
• "flatten this"
• "too many layers"

Universal patterns to flag

Language-specific patterns

Process

1. Scan file for each pattern.
2. For each hit, estimate lines saved by flattening.
3. Compute complexity ratio: (lines serving stated purpose) / (total lines).
4. Pick the worst offender by savings. Write its minimal equivalent.
5. Rank all flags by absolute line savings.

Output

file: {name}
language: {lang}
total lines: {n}
lines serving stated purpose: {n}
complexity ratio: {pct}

flagged patterns (ranked by savings):
1. {pattern} at line {n}: {description} — save ~{n} lines
2. {pattern} at line {n}: {description} — save ~{n} lines
3. ...

worst offender — minimal rewrite:
```{lang}
{the flattened version}

verdict: {lean | minor overbuild | significant overbuild | rewrite from scratch} reasoning: {one line}

## Verdict thresholds

| complexity ratio | verdict |
|------------------|---------|
| ≥ 70% | lean (may still have minor flags) |
| 50–69% | minor overbuild (apply top 2 flags) |
| 30–49% | significant overbuild (apply all flags) |
| < 30% | rewrite from scratch (bones are wrong) |

## Hard rules
- Complexity is suspect, not forbidden. If user states a requirement needing it, accept.
- Tests and fixtures never flag — test scaffolding is not production complexity.
- Type hints do not flag unless they are theatre (Union[X,X], unused TypeVar, bare Any on parameters).
- Never simplify code whose purpose you cannot read. Ask first.
- If complexity ratio > 70%, return "lean" and stop. Do not invent flags to fill output.
- If the file is a library / framework / SDK, apply looser thresholds — generalization there may be earned.
- Abstractions explicitly marked as extension points (`# extension point` comments, plugin interfaces) do not flag.
- If the file is under 30 lines, skip and say "too small to overbuild".
- When proposing a rewrite, preserve public signatures. The caller's code must not change.