architecture-planning

Installation
SKILL.md

Architecture Planning

Default stance: boring wins by default

The starting assumption for any architecture decision is the simplest, most boring option that could work — not the most scalable, not the most impressive, not the newest. Boring technology has a well-documented benefit that novel technology doesn't: its failure modes are already known. When Postgres breaks, thousands of people have hit that exact error before you. When a brand-new framework breaks, you're often the first.

This is the "innovation tokens" model (Dan McKinley, "Choose Boring Technology"): a project has a small budget for genuinely novel technical risk — maybe 2-3 tokens total. Spend them only where the novelty is the actual point of the project. Don't spend a token on the database, the queue, the deploy pipeline, or anything else that isn't the reason the project exists.

Concretely: default to Postgres over a novel database, a single binary/monolith over microservices, a cron job over a distributed job queue, synchronous calls over an event bus — until there's a specific, demonstrated reason the boring option breaks down at the actual scale/requirements in front of you. "It might not scale later" is not a demonstrated reason; a specific numeric requirement that the boring option can't hit is.

The process

  1. State the actual requirement first, in plain terms — not the architecture, the problem. What has to be true for this to work? (e.g., "needs to handle X writes/sec," "needs to survive a single server dying," "needs to be editable by a non-programmer.")
  2. Propose the boring option first, always, even if it's obviously going to be rejected. This isn't a formality — it forces the complex option to justify itself against a concrete baseline instead of against "nothing."
  3. Find where the boring option fails, honestly. This is the ATAM-style step: walk through specific realistic scenarios (load spikes, a dependency going down, a bad deploy, a malicious input) and ask "what happens here, specifically?" Don't hand-wave this — name the actual failure.
  4. Only then consider the more complex option, and only if it fixes a failure mode that the boring option genuinely can't handle. If the complex option introduces new failure modes of its own, name those too — complexity isn't free even when it fixes something.
  5. Recommend one option, not a menu. If the boring option holds up under step 3, recommend it and stop — don't list five architectures for the sake of thoroughness when one clearly wins.
  6. Every recommendation states the tradeoff explicitly, every time — what the simpler option would have been, why it wasn't enough (the specific failure mode from step 3), and what the chosen option costs in return (new complexity, new failure modes, harder to undo). Never present a recommendation without this — even a one-line "boring version was X, breaks at Y, so this instead" is required.

Deliverable: full front-to-back architecture, not fragments

Installs
1
GitHub Stars
32
First Seen
Oct 17, 2026