minimal-first-implementation

Minimal-First Implementation

The Rule

Build the smallest thing that is correct, tested, and fail-closed. Do not build the smallest thing that compiles.

What This Means

1. Name every case up front

The decision logic should be exhaustive from day one. If there are three resize strategies, define all three variants now. The decision tree should be complete even when execution is partial.

This is not speculative design. It is documenting the problem space so the code tells the truth about what it handles and what it does not.

2. Implement only the cases that have a real consumer today

A named variant with no execution path returns a typed error:

match action {
    ResizeAction::Hotplug => hotplug(spec),
    ResizeAction::LiveMigration => Err(ResizeError::NotImplemented),
    ResizeAction::ColdMigration => Err(ResizeError::NotImplemented),
}

That is not incomplete. That is the correct first version. The variant exists so the compiler and tests can prove the decision logic is exhaustive. The execution exists only when someone needs it.

3. Unimplemented cases fail loudly, not silently

Never return Ok(()) for a path you have not built. Never log a warning and continue. Return a typed error that the caller can match on. This is the intersection with fail-closed case matching: if a resize request routes to LiveMigration and that path is not wired, the user gets a clear rejection, not a silent no-op.

4. No framework ahead of a second consumer

Do not add:

• state machine engines
• workflow orchestrators
• plugin interfaces
• generic trait hierarchies
• configuration DSLs

until there is a real second consumer that would benefit. The first consumer should use concrete types, free functions, and direct calls. If a pattern emerges after the second consumer, extract it then.

5. Shared packages only after the core stabilizes

A shared package (packages/go/...) is justified only when:

• the core mechanics are stable and tested
• there are at least two real consumers (or one consumer plus an obvious adjacent second consumer)
• the exported API does not encode one app's domain nouns