Scenario-System Design (SSD)

The Problem: The Waste Pendulum#

Most engineering teams oscillate between two destructive extremes. Both feel productive in the moment; both burn the same finite resource — engineering time. This oscillation is the Waste Pendulum.

The Core Axiom#

“Architect the system across the full scenario horizon (Tomorrow), but implement code only for the validated requirement (Today).”

The Three Phases of SSD#

SSD operationalises the axiom as a repeatable, three-phase workflow.

1. 1 Explore — Tomorrow

   Phase 1: Scenario Horizon

   • Brainstorm all probable scenarios, variations, edge cases, and adjacent capabilities — e.g., secondary payment providers, asynchronous queue processing, multi-tenancy.
   • Timebox rule: constrain this exercise to 1–2 hours to avoid analysis paralysis.
2. 2 Blueprint — Tomorrow

   Phase 2: Keel Architecture

   • Architectural Seams: Design stable data schemas, boundary contracts, and modular interfaces capable of supporting all identified scenarios.
   • Non-Breaking Foundations: Ensure primary entities and relationships can scale additively without requiring structural migrations later.
3. 3 Ship & Extend — Today

   Phase 3: Minimal Core Build

   • Minimal Functional Footprint: Implement only the synchronous logic and endpoints required for the validated immediate request.
   • Deliberate Omissions: Explicitly identify, document, and defer non-essential features, speculative abstractions, and secondary workflows from today's active pull request.
   • Rapid Extension Trigger: Define the production metric or business signal that validates initial success and unlocks the deferred scenarios.

A Concrete Walkthrough#

Consider a deceptively simple ticket: “Send a confirmation email when an order completes checkout.” Three engineers pick up the same ticket — and land in three very different places.

1. Path A: The Under-Engineered Trap

   Rewrite inevitable
   java Copy

   // 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 failure: when the business inevitably requests SMS order updates next month, CheckoutService must be refactored — breaking existing unit tests and risking checkout stability.

2. Path B: The Over-Engineered Trap

   Speculative generality
   java Copy

   // 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 failure: immense development delay, high maintenance overhead, and dead code solving problems that never materialise.

3. Path C: The SSD Approach

   Strictly additive
   1. Phase 1 (Horizon): acknowledged email, SMS, and webhook alerts as potential adjacent flows.
   2. Phase 2 (Keel Architecture): defined a lean NotificationGateway interface with a send(recipient, message) contract, and added a notification_channel enum column to the schema.
   3. Phase 3 (Minimal Core Build): implemented only EmailNotificationGateway.
   4. Deliberately Omitted: SMS third-party SDKs, background worker queues, and retry mechanisms.
   java Copy

   // Phase 2 — the keel: one stable seam
   public interface NotificationGateway {
       void send(Recipient recipient, Message message);
   }
   
   // Phase 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());
       }
   }

   Rapid extension: when SMS is requested later, it is delivered as a strictly additive class implementing NotificationGateway — with zero modifications to CheckoutService.

   java Copy

   // 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());
       }
   }

Operational Guardrails#

Three rules keep SSD from sliding back into either trap of the Waste Pendulum.

• The Timebox Rule

  Brainstorming is bounded. Avoid design committees and infinite horizons.

• Logic Over Abstraction

  Prefer clear, readable logic over premature design patterns.

• The Extension Proof

  Verify that future scenarios can be built purely additively before merging.

Frequently Asked Questions & Anti-Goals#

Practical Artefact: SSD Pull Request Template#

Drop this template into your repository's .github/PULL_REQUEST_TEMPLATE.md to make SSD a routine part of every change you ship.

### Scenario-System Design (SSD) Summary

#### 1. Scenario Horizon (Tomorrow)

* Immediate Request: [Brief summary of the primary ticket]
* Considered Scenarios:
  * [Scenario A: e.g., Support for secondary payment provider]
  * [Scenario B: e.g., Webhook-based asynchronous completion]

#### 2. Keel Architecture (Tomorrow)

* Structural Hooks: [e.g., Decoupled payment processing interface from checkout domain]
* Schemas & Interfaces: [e.g., Stable entity contracts and boundary definitions supporting all considered scenarios]

#### 3. Minimal Core Build (Today)

* Immediate Scope: [Single synchronous endpoint handling primary provider]
* Deliberately Deferred: [e.g., No secondary API clients or background queue workers implemented yet]
* Rapid Extension Signal: [Building Scenario A/B triggers when monthly transaction volume exceeds threshold]

Embed the Badge#

Signal that your repository follows the Scenario-System Design process. The snippet below renders a compliance badge in your project's README.md:

[![Scenario-System Design](https://img.shields.io/badge/SSD-Design_for_Tomorrow%2C_Build_for_Today-4F46E5?style=flat-square)](https://ssd.shurn.me)

Attribution & Citation#

When referencing SSD in documentation, talks, or publications, use the following citation:

Shurn. (2026). Scenario-System Design: Design for Tomorrow, Build for Today. Available at: https://ssd.shurn.me