design_simplicity_audit v1.0.0

name: design_simplicity_audit description: Audits a design, architecture, or infra plan for overengineering. Inventories complexity smells with quoted evidence, pressure-tests each against the real requirements, scores the burden, and proposes simpler alternatives with honest cost notes. Triggers when reviewing a design doc, architecture proposal, codebase, or infra plan that feels heavier than the problem, when asked "is this overengineered", or before approving a design that adds layers, services, or machinery.

Design Simplicity Audit

Purpose

Give a design review that says "this is too complex" only with receipts. The audit inventories complexity smells tied to observed evidence, weighs each against the system's actual requirements, and proposes simpler alternatives where the simpler option wins on honest trade-offs. It also names what must not be simplified, so the audit never becomes a blunt hatchet job.

Workflow

1. Establish requirements first. Before touching the design, write down what the system must actually do: scale targets, availability objectives, team size, blast radius, and only future work with committed dates. Everything gets judged against this sheet, not against aesthetics.
2. Inventory the design as it is. Components, layers, interfaces, mappings, queues, services, infra pieces. No judgment in this step, just the map.
3. Run the smell rubric (references/rubric.md). For each smell, record the exact location (file, component, diagram box) and quote the evidence: a line of code, a config entry, a diagram connection. A smell without a location and a quote is an accusation, not a finding.
4. Pressure-test each finding against the requirements. Ask: does this layer buy a real trust, compatibility, transaction, observability, or test-seam boundary? Does this distributed piece serve an actual scale or ownership need? If yes, the complexity is justified: log it as cleared, with the requirement that justifies it.
5. Score the findings. Feed the findings JSON into bin/score.py. It computes a complexity burden score and returns the findings ordered by priority, so the report leads with what matters.
6. Propose simpler alternatives. For each confirmed finding: what the simpler version looks like, what it gains (fewer moving parts, faster onboarding, smaller change surface), what it loses (flexibility, observability, safety margin), and what the change itself costs (migration work, risk). Honest cost notes, both directions.
7. Name the untouchables. List the complexity that must stay: regulated redundancy, safety-critical margins, and the seams that make the cheap deletions in step 6 possible (tests, clean module edges). The tooling that keeps code easy to change is what makes deleting speculative code safe.
8. Deliver the report per the Output Contract below.

Output Contract

• Requirements sheet: the requirements the audit judged against (step 1).
• Findings table: smell | location | evidence (quote) | confirmed or cleared | requirement that clears it, if any.
• Complexity burden score from bin/score.py, with the input JSON attached.
• Simpler alternatives, each with: proposal, gains, losses, change cost.
• Untouchables list with why each stays.
• Verdict: the three changes with the best gain-to-change-cost ratio, in order.

Operating Rules

• Evidence first. Every claim ties to a location plus a quoted line, file, or diagram box. "Feels enterprisey" is not a finding.
• Judge against requirements, not shape. A monolith is not simple by default and microservices are not complex by default. The requirement decides.
• The audit cuts both ways. Simplicity that ignores real requirements is a defect too: flag under-engineered spots (missing retry where failure is real, missing a boundary where a trust seam is needed) right next to over-engineered ones.
• No invented numbers. Cost notes use ranges and the project's actual known costs: team size, deploy frequency, incident history. If you do not know a cost, say so and frame it as a question for the owner.
• YAGNI covers capabilities built for presumptive features. It never covers cutting tests, refactoring, or anything that keeps the code easy to change.
• When a finding could be read as a personal criticism of the designer, phrase it as a property of the design, not of the person. The audit reviews artifacts.