Scenario-System Design (SSD)
Design for tomorrow, build for today.
A simple 3-step habit to stop writing code you have to rewrite two months later—without over-engineering things you don't need.
- Author Shurn
- Version 1.0.0
- Licence CC BY-SA 4.0
- Canonical ssd.shurn.me
The Two Ways We Shoot Ourselves in the Foot#
Most of us swing between two failure modes. Both feel productive in the moment. Both burn the same finite resource — your engineering time.
The Quick Hack
You ship the bare minimum to close the ticket, with zero thought for anything adjacent. The first delivery is fast — right up until the PM asks for “a small tweak” and the whole feature needs rewriting. The schema has to change, your tests break, and the debt starts compounding with every subsequent change.
The Future-Proof Monster
Speculative Generality
You build a generic plugin system, a message queue, and an abstract factory — for twelve users. The architecture is impressive, the delivery is late, and all that flexibility ships as dead code nobody ever maintains.
The fix: Don't confuse your thinking with your coding. Think broad about the horizon (Tomorrow), lay a clean skeleton, and write only the code needed for today's ticket (Today).
The Core Axiom#
“Think across the full horizon of what this feature might become (Tomorrow), but only write code for what today's ticket actually justifies (Today).”
Tomorrow is thinking
Map the problem space, the boundaries, and the data schemas before you commit a single line. Thinking costs minutes; guessing costs weeks.
Today is minimal
Ship the leanest code that delivers today's value. Because the skeleton was designed with tomorrow in mind, extending it later is additive — never a rewrite.
The Three Steps of SSD#
SSD turns that rule into a repeatable, three-step habit.
-
Step 1: Brainstorm the What-Ifs
- Grab a whiteboard (or a rubber duck) and list the adjacent cases you can realistically see coming: multiple currencies, SMS notifications, bulk actions — the second payment provider someone will definitely ask for.
- Timebox it: 30–60 minutes, maximum. This is brainstorming, not a thesis defence.
-
Step 2: Design the System
- Data models & boundaries: Shape your schemas and interface seams so every what-if from Step 1 can be added later without breaking what already exists.
- Strictly additive: If a future change would force a migration or a rewrite, the skeleton isn't done — keep drawing.
- No code yet: This is a pen-and-paper step. Resist the urge to “just scaffold it”.
-
Step 3: Ship the Bare Minimum
- Today's ticket only: Build exactly what the ticket asks for — not what it might ask for, and not what you imagine it asking for.
- Defer on purpose: Write down the features you're consciously skipping — the queue, the retries, the second provider — so nobody mistakes the omission for an oversight.
- Extend in hours, not weeks: When the feature proves itself in production, pick a deferred scenario off the list and add it without touching the code you already shipped.
Walkthrough: Order Checkout & Notifications#
Let's make it concrete with a ticket so ordinary it's a rite of passage: “Send a confirmation email when an order completes checkout.” Three engineers pick it up — and land in three very different places.
-
Path A: The Sloppy Way
Rewrite inevitablejava// CheckoutService.java — built for one ticket public class CheckoutService { public void completeOrder(Order order) { orderRepository.save(order); // Hardcoded to a single provider, single channel sendgridClient.sendEmail(order.getEmail(), "Order confirmed"); } }
The problem: when the business asks for SMS order updates next month (and it will),
CheckoutServicehas to be refactored — your passing unit tests break, and you're suddenly risking checkout stability for a feature that took a day to write. -
Path B: The Over-Engineered Way
Speculative generalityjava// Built for a future that never arrives NotificationChannel channel = channelFactory .forTransport(Transport.SMS) // no SMS users yet .withPluginLoader(dynamicClasspath) // speculative plugin system .publishTo(kafkaEventBus) // no throughput to justify it .build(); // Plus four empty tables: sms_messages, slack_messages, // discord_messages, webhook_endpoints
The problem: weeks of delay, a maintenance tax on code nobody exercises, and four empty tables sitting in production quietly mocking you. The feature wasn't even validated yet — you built multi-channel event streaming for a maybe.
-
Path C: The SSD Way
Strictly additive- Step 1 (the what-ifs): acknowledged that email, SMS, and webhook alerts are all plausible next doors.
- Step 2 (the design): defined a lean
NotificationGatewayinterface with asend(recipient, message)contract, and added anotification_channelenum column to the schema. - Step 3 (today's ticket): implemented
EmailNotificationGateway. Email. That's it. - Deliberately skipped: the SMS SDK, the background worker queue, the retry mechanism — documented, deferred, not forgotten.
java// Step 2 — the skeleton: one stable seam public interface NotificationGateway { void send(Recipient recipient, Message message); } // Step 3 — today: the only implementation that ships public class EmailNotificationGateway implements NotificationGateway { public void send(Recipient recipient, Message message) { sendgridClient.sendEmail(recipient.email(), message.body()); } }
The payoff: when SMS gets requested next month, it lands as a new class implementing
NotificationGateway— done in hours, withCheckoutServicecompletely untouched.java// Next month: strictly additive. CheckoutService is untouched. public class SmsNotificationGateway implements NotificationGateway { public void send(Recipient recipient, Message message) { twilioClient.sendSms(recipient.phone(), message.body()); } }
Guardrails That Keep SSD Honest#
Three rules stop SSD from sliding back into either trap.
-
The Timebox Rule
Brainstorming has an alarm clock. If you're still debating horizons after an hour, you've drifted into a design committee.
-
Logic Over Abstraction
Prefer clear, readable logic over clever abstractions. A plain function you understand beats a framework you'll never finish building.
-
The Extension Proof
Before merging, prove the next scenario fits additively. If adding it means editing code you just wrote, the skeleton needs another pass.
Frequently Asked Questions & Anti-Goals#
Does Step 1 violate YAGNI (You Aren't Gonna Need It)?
YAGNI says don't write code for tomorrow. We agree — Step 3 is pure YAGNI. But thinking ahead costs nothing; bad schemas cost months, maybe even years. You're allowed to know what's coming without building it.
What if our guesses in Step 1 are wrong?
Then you wasted 45 minutes thinking, not 3 weeks debugging unused abstractions. That's the whole bet: cheap thought now versus expensive rework later. And because Step 3 shipped no speculative code, a pivot costs you nothing you didn't need anyway.
When should you NOT use SSD?
Hackathons, throwaway scripts, or simple CRUD tools. If your code has no future to design for, don't pay the thinking tax. SSD is for production code you expect to outlive its first sprint.
Steal This: The SSD Pull Request Template#
Drop this into your repository's .github/PULL_REQUEST_TEMPLATE.md
and SSD becomes muscle memory for every change your team ships.
### Scenario-System Design (SSD) Summary #### 1. The What-Ifs (Tomorrow) * Today's ticket: [One-line summary of what you're shipping] * Scenarios we thought about: * [Scenario A: e.g., a second payment provider] * [Scenario B: e.g., async completion via webhook] #### 2. The Design (Tomorrow) * Seams we added: [e.g., payment logic behind an interface, out of the checkout domain] * Schemas & interfaces: [e.g., entity contracts that let the scenarios above land additively] #### 3. The Bare Minimum (Today) * What ships: [e.g., one synchronous endpoint, primary provider only] * Deliberately skipped: [e.g., no secondary API clients, no queue workers — yet] * Extension signal: [e.g., when Scenario A/B gets requested or volume crosses a threshold]
Prefer a visual workspace? Use the Interactive SSD Builder ↗ to brainstorm the what-ifs, design your system, and export your PR summary card-by-card.
Embed the Badge#
Proud of your process? Drop this snippet into your project's
README.md and wear the badge:
[](https://ssd.shurn.me)
Attribution & Citation#
Using SSD in docs, talks, or a blog post? Cite it like this:
Shurn. (2026). Scenario-System Design: Design for Tomorrow, Build for Today. Available at: https://ssd.shurn.me