Solid

SOLID

Overview

Apply SOLID so behavior is easy to change and to test without a pile of mocks.

Companion skills: shape the product with grill; prove behavior with tdd + test-design. This skill is only structure and dependency direction.

Core principle: hard to test usually means hard to use — fix the boundaries, don't paper over them with mocks.

When to Use

• During grill design sections (architecture / components / interfaces)
• Before tdd when introducing new types, packages, or dependency edges
• Reviewing a PR that adds coupling or "needs 5 mocks to unit-test"
• Refactors aimed at testability

When NOT to use: pure glue scripts with no domain logic; drive-by renames; user explicitly asked for a throwaway spike.

The Iron Law (non-negotiable)

1. New non-trivial behavior lives behind a boundary you can name (SRP).
2. Domain/policy does not depend on IO/framework details (DIP).
3. Fake abstractions invented only to satisfy a test are forbidden (no theater).

Violating the letter is violating the spirit. "Just mock the world" and "God class is fine for now" do not count.

The five, as engineering checks

S — Single Responsibility

• One unit → one reason to change
• If the name needs "and" / "manager of everything" → split
• Separate: orchestration vs policy vs IO vs formatting

O — Open/Closed

• Prefer extending via new types/strategies/composition over editing a core switch forever
• YAGNI: don't pre-build plugin systems; do stop smearing new cases into a blob

L — Liskov Substitution

• Subtypes must honor the caller's contract (pre/postconditions, errors)
• No "inherits for reuse" that surprises callers; prefer composition

I — Interface Segregation

• Small, caller-shaped ports — not one mega-interface
• Callers shouldn't depend on methods they never use

D — Dependency Inversion

• High-level policy depends on abstractions (ports), not on DB/HTTP/FS/SDK concretes
• Adapters at the edge; core stays pure/fakeable
• Signal: unit test needs ≥3 mocks → likely DIP/SRP failure (see test-design)

Workflow (when invoked)

Announce "Using solid to …", then:

1. Name the units — what each does, how you use it, what it depends on
2. Draw dependency arrows — domain → ports ← adapters (never domain → SQL/HTTP client directly)
3. SRP pass — split "and" responsibilities
4. ISP pass — trim fat interfaces
5. DIP pass — push IO out; inject ports
6. Theater check — every new interface must have a product reason, not only a test reason
7. Hand off — resume grill approval or tdd with test-design

Red Flags

• God class / package that "knows the whole feature"
• Domain imports ORM, HTTP client, or UI kit
• Subclass overrides that weaken invariants
• Interface with 15 methods for one caller that uses 2
• New interface used only in tests (no production adapter)
• Unit test mocks half the system to "isolate"

Rationalization Table

Excuse	Reality
"Split later when it hurts"	It already hurts when you need 4 mocks.
"Concrete is simpler than a port"	Until the second IO path. Port + one adapter is cheaper than rewrites.
"Inheritance reuses code"	Inheritance couples hierarchies; compose instead.
"One service interface keeps it tidy"	Fat interfaces force fake methods and ISP debt.
"Mocks prove DIP"	Mocks hide DIP failure. Fewer mocks after a real port is the proof.

Checklist

• Each unit has one clear purpose and a name without "and"
• Dependency arrows point inward to policy, not out to IO
• Ports are small; adapters own frameworks
• No test-only abstractions
• Ready for tdd/test-design without mock piles

Hand-off

• Product decisions still open → grill
• Implementing → tdd + test-design
• Shipping → commit-and-push