// Disciplines for software design work. Load when designing APIs, type systems, features, or system boundaries. Counters the tendency to retrieve familiar patterns instead of discovering what the problem actually needs. Has full (8-persona) and lightweight (5-persona) modes.
| name | pony-software-design |
| description | Disciplines for software design work. Load when designing APIs, type systems, features, or system boundaries. Counters the tendency to retrieve familiar patterns instead of discovering what the problem actually needs. Has full (8-persona) and lightweight (5-persona) modes. |
| disable-model-invocation | false |
Load this skill when doing design work — APIs, type systems, features, system boundaries. The core problem it addresses: LLMs default to retrieving familiar patterns from training data rather than discovering what a specific problem needs. The result is designs that look right (they have the right nouns) but weren't derived from the problem.
Design is the act of discovering what is needed. It's about finding surprising affordances and avoiding candy-machine interfaces riddled with footguns.
Design is not a phase. It's a continuous loop: observe what you have, orient against what you know, decide, act, then observe again. Every decision you make reveals new information. That information might confirm prior decisions or invalidate them. Either way, you have to look. "I already decided that" is never a reason to skip re-evaluation — it was decided with less information than you have now.
The skill has two modes: full and lightweight. The orchestrator selects the appropriate mode based on the criteria below and proceeds. Report the mode choice when presenting results — the human can request full mode if lightweight was used and they want deeper coverage.
Full mode is the default. Use it when:
Lightweight mode is for bounded design work within established patterns:
When in doubt, use full mode. Lightweight is appropriate when there's a clear existing pattern being extended and the boundaries are already decided.
Design work is where pattern-matching failures are most costly and hardest to self-detect. A single agent applying design disciplines will still pattern-match — the disciplines become post-hoc rationalizations for a retrieved design rather than actual constraints on the exploration.
The full design process runs in two stages with a feedback loop. Load
pony-ensemble for the mechanical process; the personas defined in this skill
replace the generic attention focuses.
This skill uses the ensemble workflow with domain-specific customizations. Stage 1 (design) runs as a standard ensemble with 3 personas. Stage 2 (evaluation) runs as a second ensemble with 5 personas, using the Stage 1 synthesis output as its input. The two-stage loop and finding categorization (Rejection/Adjustment/Tension) are additions specific to this skill — the base ensemble protocol handles agent spawning, triage, and synthesis mechanics.
Before spawning design personas, the orchestrator must decompose the problem statement. Ask: "What are we trying to accomplish? What pain point does this address?"
If the problem statement implies a solution rather than stating a problem — "add convenience wrapper methods for X" rather than "users struggle with X because Y" — peel it back to the underlying pain point. If you can't confidently identify the pain point, ask the human. This is not a failure; it's the most valuable question the orchestrator can ask, because every persona will anchor on whatever framing they receive.
Brief personas with the actual problem. The original problem statement can be included as context, but the briefing should lead with the pain point: what the user is struggling with and why. This gives personas room to explore different solutions rather than anchoring on the solution implied by the problem statement.
Three design personas explore the problem space in parallel. Each applies all
the disciplines below but enters the problem from a different direction. The
decorrelation comes from where they start, not what they know. Persona
definitions are in personas/design/.
| File | Focus |
|---|---|
consumer-first.md | Starts from usage code, derives API from what makes call sites clean |
skeptic.md | Questions every abstraction, tries to subtract, proposes the smallest design |
principle-checker.md | Hard verification of each design principle with evidence |
When personas return, the orchestrator evaluates the quality of exploration before forwarding outputs to synthesis. Check:
If exploration quality is poor — narrow interpretation, insufficient alternatives, weak rejection reasoning — don't forward to synthesis. Refine the briefing: restate the problem more broadly, point out the anchoring you observed, and ask the human to clarify if needed. Then re-spawn.
Stage 1 synthesis produces a candidate design using the standard ensemble synthesis process. The synthesis should pay special attention to:
Five evaluation personas stress-test the candidate design in parallel. Their
input is the Integrated Result from Stage 1 synthesis — the candidate design
with its consumer sketches, type definitions, and boundary decisions. They
evaluate these design artifacts, not implementation code. Persona definitions
are in personas/evaluation/.
| File | Focus |
|---|---|
security.md | Trust boundaries, attack surfaces, resource bounds in the design |
performance.md | Architectural bottlenecks, coordination points, data structure choices |
adversarial.md | Concrete usage scenarios that lead to bad outcomes |
testability.md | Whether the design is verifiable — observable effects, isolatable components |
wildcard.md | What all the other personas missed |
For the wildcard persona specifically: include the identity statement (first paragraph) from each of the other personas so the wildcard knows what territory is already covered.
Before spawning evaluation personas, create a temporary directory for evidence
files (~/tmp/design-eval-<timestamp>/). Each persona writes its detailed
analysis to a file in this directory and returns a structured summary to the
orchestrator. The synthesizer works from summaries and digs into evidence
files only when it needs to examine a finding more closely. This prevents
context overload during synthesis.
Evaluation personas identify problems and assess impact — they do not categorize their own findings as Rejection/Adjustment/Tension. Categorization is the synthesis step's responsibility.
Each evaluation persona produces two artifacts:
Evidence file — written to the path provided by the orchestrator. Contains the full detailed analysis: every finding with complete evidence, full design element excerpts, detailed reasoning, and complete pass/fail evaluations. This is the authoritative record.
Summary (returned to orchestrator) — a structured summary for the synthesizer to work from:
Findings — ordered by impact (Structural > Significant > Minor). Each:
The impact assessment helps the synthesizer with categorization without pre-empting it. A persona's "structural" assessment is a strong signal toward Rejection, but the synthesizer may disagree if it sees the concern addressed by another persona's suggestion.
Passes — things checked that look correct. Brief.
Uncertainties — things the persona couldn't determine, and why.
Stage 2 synthesis works from the persona summaries and categorizes each finding. Provide the paths to each persona's evidence file so the synthesizer can dig in when it needs more context — when impact assessments conflict, when a finding's summary is ambiguous, or when it needs to verify the evidence supports the concern.
Stage 2 synthesis categorizes each finding:
After stage 2 synthesis:
The orchestrator monitors the loop for signs that it isn't converging:
When a convergence failure is detected, the orchestrator stops the loop and escalates to the human: "Here's the fundamental tension — these concerns pull in opposite directions, and we need you to decide which matters more." This is not a failure of the process. Surfacing genuine tensions is one of its primary outputs.
The final output includes:
If the loop terminated via convergence failure rather than a clean evaluation, there is no accepted design — only the history of attempts, the rejections, and the tensions.
Lightweight mode uses fewer personas and a single pass. It keeps all three
design personas but reduces evaluation to two personas and drops the
feedback loop. Load pony-ensemble for the mechanical process.
Same as full mode. Before spawning personas, decompose the problem statement to the underlying pain point. If the problem statement implies a solution, peel it back or ask the human. Brief personas with the actual problem.
Three design personas explore the problem in parallel — the same as full mode. The same disciplines apply; the decorrelation still comes from different entry points.
| File | Focus |
|---|---|
consumer-first.md | Starts from usage code, derives API from what makes call sites clean |
skeptic.md | Questions every abstraction, tries to subtract, proposes the smallest design |
principle-checker.md | Hard verification of each design principle with evidence |
Same as full mode. Evaluate whether personas explored meaningfully different approaches before forwarding to synthesis. If all three anchored on the same narrow interpretation, re-brief and re-spawn.
Stage 1 synthesis produces a candidate design using the standard ensemble synthesis process. The same synthesis guidance as full mode applies: consumer-first vs skeptic tensions reveal boundaries, principle-checker violations the others missed are the highest-value findings, and convergence from different starting points is strong signal.
Two evaluation personas stress-test the candidate. The adversarial evaluator always runs. The second slot is context-dependent — if the human specifies which evaluator to use, use that. Otherwise the orchestrator picks whichever lens is most relevant to the task:
| When | Pick |
|---|---|
| Design touches trust boundaries or external input | security.md |
| Design is on a hot path or introduces coordination points | performance.md |
| Design has complex state or will be hard to test in isolation | testability.md |
Pick whichever is closest — every design has some risk profile. If multiple conditions apply, pick the most relevant one. If the reason for picking a particular evaluator is a characteristic that also appears in the full-mode selection criteria, that's a signal the task warrants full mode — don't use the persona pick to compensate for a wrong mode selection.
Before spawning evaluation personas, create a temporary directory for
evidence files (~/tmp/design-eval-<timestamp>/), same as full mode.
Each persona writes its detailed analysis to a file in this directory and
returns a structured summary. Evaluation personas use the same output
format as full mode (evidence file + summary with findings ordered by
impact, passes, uncertainties).
Stage 2 synthesis categorizes each finding as Rejection, Adjustment, or Tension using the same scheme as full mode.
Lightweight mode does not iterate. After Stage 2 synthesis:
If the review produces an unexpectedly high density of findings relative to the change size, if a finding reveals the approach is fundamentally wrong, or if a finding reveals the change touches more subsystems or has more complex interactions than the mode selection assumed, the orchestrator presents this to the human. The human decides what to do — the same options apply.
The final output includes:
When principles conflict, these values set the priority. We value the left side over the right — but the right side still matters when the left isn't at stake.
API safety over API minimality — an error-prone API should be fixed even if the fix adds surface. Prefer solutions that don't expand the API, but never leave a footgun to preserve minimality.
Correctness over performance — never sacrifice correctness for speed. Get it right first, then optimize. A faster wrong answer is still wrong.
Correctness over concision — correct but verbose beats concise but wrong. Don't simplify code or APIs at the cost of correct behavior.
Security over performance — never skip validation at trust boundaries for speed. Optimize how you validate, not whether you validate. Security is correctness.
Interface simplicity over implementation simplicity — accept a harder implementation to give users a clean interface. The consumer's experience matters more than the implementer's convenience.
Performance over interface simplicity — runtime speed matters more than programmer convenience. It's acceptable to make things harder on the user to improve performance, but never at the cost of correctness.
Simplicity over consistency — don't force artificial consistency when it makes things harder to use. If two similar things genuinely need different interfaces, let them be different.
Explicitness over implicitness — when the language allows something to work by magic (implicit conversions, convention-based wiring, unnamed dependencies), prefer the version that states what's happening. The cost of a few extra characters is less than the cost of reconstructing hidden knowledge.
Type safety over convenience — use the type system to encode constraints even when it's more work. Distinct types for distinct semantics, validated wrappers over raw primitives, explicit error vocabularies over generic errors. "We could just use a String here" is almost always wrong.
Changeability over predictive design — make designs modular and replaceable so future needs can be accommodated, but don't add abstractions, extension points, or features for changes that haven't happened yet. Easy to modify beats designed for a specific predicted modification.
These are the foundation each persona builds on. Every agent applies all of them.
State what problem the user has before proposing any types, traits, or APIs.
"The user needs X" comes before "here's a SessionStore trait." If you can't
articulate the problem without referencing your solution, you don't understand
the problem yet.
If you only have one idea, you don't have any. The first interpretation of a problem statement is pattern retrieval — the LLM equivalent of "this looks like a thing I've seen before." Design starts when you generate a second interpretation that's genuinely different, not a variation on the first.
Before committing to a direction, explore the design space. Generate multiple approaches internally — different framings of what the problem is asking for, not just different implementations of the same framing. Include wild ideas. They're valuable not because you'll use them, but because they reveal what matters about the problem. An idea you reject teaches you something about why you rejected it — that "why" is design knowledge.
Present your best idea, not your first idea. The output is the winner of an internal competition. The ensemble output format has a "Key decisions: alternatives considered" section — use it to document what you explored, what you picked, why, and why you rejected the alternatives. This isn't bookkeeping; it gives the orchestrator visibility into whether real exploration happened.
The problem statement is where exploration starts, not where it ends. "Add convenience wrapper methods" is a hint about a pain point, not a design specification. What pain? Why is the current approach painful? What would "convenience" actually mean to the user? Different answers to those questions lead to genuinely different designs — one of which might be "thin wrappers" and another might be "a unified API that abstracts away the underlying complexity." Both are valid interpretations of "convenience"; only exploration reveals which one earns its keep.
Before designing any API, write the code that uses it. The handler, the call site, the configuration — the actual application code a user would write. Not as an afterthought example, but as the first artifact. The consumer sketch is the specification. It reveals:
If the consumer code is awkward, the API is wrong. Fix the API, not the consumer code.
When claiming consistency between two APIs (e.g., "guards use the same API as handlers"), write both consumer sketches side by side. If the method names, signatures, or interaction patterns differ, the claim is false — address the discrepancy before proceeding.
Before proposing a new type, trait, or abstraction, write down what already exists that addresses the same need: in the codebase, in the language's stdlib, in the ecosystem. If nothing exists, say so explicitly. If something exists, start from it — extend, adapt, or compose it rather than building a parallel structure.
On a greenfield project, "what already exists" means the language's built-in types, stdlib, and idioms. A new type that duplicates what the language provides is a smell.
This is not "reuse for reuse's sake." It's a forcing function against the pattern-matching tendency to invent new abstractions when the problem doesn't require them.
Don't design the whole thing at once. Start with the smallest coherent piece. Validate it with a consumer sketch. Then add the next piece and see if it fits.
At each step, ask:
This is how you discover the shape of the problem. A big-bang design papers over these tensions. Incremental exploration surfaces them while they're cheap to fix.
Every design decision is made with incomplete information. As you explore further, the territory expands. At step B you could see one option and picked it. At step D you can see two options that weren't visible from B. Step C might provide evidence that the option you didn't pick is actually better. None of this means B was wrong at the time — it means the landscape changed and you need to look again.
The way you discover this is by constantly pushing on the design: "what if we did it this other way?" "Does this conform to our principles?" "This doesn't feel right — why?" These aren't idle questions. They're how you explore more of the map. Each question might reveal new options, new evidence, or new connections between decisions you thought were independent.
When the landscape changes, trace back through prior decisions. Not to check whether they were "disproved" — that's too binary. Check whether the option space has expanded. Maybe at step B you picked X because it was the only option you could see. Now at step D you can see X and Y. Which is better given everything you've learned? Maybe X is still right. Maybe Y is clearly better. Maybe you need to explore further to tell. All three of those outcomes require you to actually go back and look rather than assuming B is settled.
This is the core of the design loop. Skipping it is how you end up with designs that look coherent on the surface but have quiet contradictions baked in — an app-level-only registration model sitting next to a radix tree that already knows the route hierarchy, because nobody went back to check whether "app-level only" still made sense after discovering what the tree could do.
The cost of revisiting decisions is real but bounded. The cost of building on a decision that should have been revisited compounds with every step forward.
For each type, trait, or interface in your design, ask: is this here because the problem requires it, or because other systems have it? "Sessions usually have a SessionStore" is not a reason. "The framework needs to persist session data" is a reason — but only if the framework actually needs to own that responsibility.
The strongest signal that you're importing rather than discovering: your design has the same nouns as Rails/Phoenix/Express/Django and you're working in a language with fundamentally different idioms.
Names are the primary interface of a design — they're how it communicates intent to every future reader. A design that's structurally sound can still fail in practice because a name suggested something different from what the thing actually does, and the user built a wrong mental model from it.
This discipline earns its keep at boundaries: public API types, method names, parameter names, module names — anywhere a user encounters a name and forms an expectation about what it means. Internal names matter too, but the cost of a misleading public name is much higher because it shapes how every consumer understands the system.
At each design step, ask:
UserStore that also sends email notifications lies about its
responsibilities. A name that categorizes without specifying is a name that
lets scope creep in without anyone noticing.Cache that also writes through to the database is misleading because the
name suggests read-only caching.Session
and SessionState, Token and TokenData, Route and Router — when
names differ by a suffix or prefix, users will assume the relationship is
systematic. If SessionState is not the state of a Session, the naming
implies a relationship that doesn't exist.user in one place and account in another for the same
concept, readers will assume these are different things and spend effort
trying to understand the distinction. One concept, one name — everywhere.
This is about vocabulary consistency, not boundary-qualified variants like
UserInput and UserRecord — those are distinct types that need distinct
names per "Distinguish values with distinct semantics.""Distinguish values with distinct semantics" ensures different concepts get different types. This discipline ensures those types get names that communicate what they actually are. A type can be correctly distinct and still misleading if its name suggests the wrong thing.
When this discipline pushes for more precise names and the skeptic questions whether the named concepts need to exist at all, surface the tension — both are needed. Good names make abstractions easier to evaluate: a precisely named type reveals its purpose, which either justifies or undermines its existence.
For every capability in the design, ask: does the framework/library own this, or does the user own this? The answer should come from analysis of the consumer sketch, not from "frameworks usually own this."
The test: if you removed this from the framework and the user did it themselves, would anything break? Would anything get worse? If the user can do it better (more type-safe, more flexible, more natural in the language), the framework shouldn't own it.
This discipline draws the line between framework and user — the external boundary. For application-level design where the question is how to organize within the user's code, see "Separate layers."
"Reason about ownership boundaries" asks whether the framework or the user should own a capability — the external boundary. This discipline asks the internal question: within the application, does each piece of logic live in the right layer?
Layered applications have three layers: domain logic (pure business rules, zero infrastructure dependencies), orchestration (combines domain logic with infrastructure — databases, caches, queues), and presentation (adapts orchestration for a specific protocol — HTTP, GraphQL, CLI). This discipline operationalizes that separation as design-time questions.
Scope: This discipline applies when the skill is used for application-level design — systems with distinct domain, orchestration, and presentation concerns. For library or API design where there's no application layering, this discipline is not relevant. The ownership boundary discipline covers the framework/library boundary instead. Note that "infrastructure" in the questions below means infrastructure relative to the application's domain — a deployment tool's domain vocabulary naturally includes container and orchestration concepts, and "infrastructure" for that tool means the specific database or message queue it uses to do its work, not the deployment concepts it operates on.
At each design step, ask:
PaginatedResult type in the domain layer exists because the
database returns paginated results — that's infrastructure leaking into domain
vocabulary. The domain might need "a bounded subset of results" but shouldn't
know that the bound comes from database cursor limits.The test for clean layer separation: can you describe the domain logic without mentioning any infrastructure technology? If explaining a business rule requires saying "database," "HTTP," "cache," or "queue," the rule has infrastructure dependencies that should live in orchestration instead.
"Check cohesion" asks whether things belong together within a type. This
discipline asks a related but distinct question: do things belong together
within a layer? A type can be internally cohesive but live in the wrong
layer — a well-structured UserService that's cohesive in its
responsibilities but mixes domain rules with database queries. Cohesion
would call it fine (all methods serve "user management"); layer separation
would flag the infrastructure
dependency in domain logic.
"Reason about ownership boundaries" draws the line between framework and user. This discipline draws lines within the user's code. The two work at different scales but share a principle: clear boundaries make it obvious where each concern lives and prevent responsibilities from migrating to the wrong side.
When this discipline pushes toward extracting infrastructure from domain types and the skeptic questions whether the indirection is worth it, surface the tension. For small applications or early-stage code, the cost of clean separation may exceed the benefit — the answer depends on the scale and expected evolution of the application. But be honest about the tradeoff: coupling that's cheap today gets expensive as the application grows, and untangling it later costs more than separating it now. The skeptic's role here is to prevent ceremony — extracting an interface that has exactly one implementation and no prospect of a second is indirection without value. The discipline's role is to prevent entanglement — domain logic that can't be tested, reused, or understood without its infrastructure context. When both concerns are real, that's a tension worth presenting to the human.
State is where most design complexity hides. Boolean flags, nullable fields, and implicit modes are all state — just state without a name. Unnamed state can't be reasoned about systematically: you can't enumerate its transitions, verify its invariants, or ask what happens when an input arrives in a state you didn't consider.
This discipline earns its keep when a component has multiple interacting pieces of state, or when state determines which operations are valid. A single flag that independently tracks one condition doesn't need a state machine — it needs a good name. For everything else, answer these questions:
The test for whether you've mapped state well: can someone new to the design draw the state diagram from your description? If not, the state model isn't explicit enough.
Every design establishes contracts — things that must always be true for the system to work correctly. Callers rely on ordering guarantees, components depend on data relationships, operations assume structural properties hold. When these contracts are implicit, nobody can verify them, nobody knows when they've been violated, and future changes break them without anyone realizing what happened until the symptoms surface far from the cause.
State modeling asks "what states can this component be in?" Invariant articulation asks the broader question: what must always be true across the entire design? Some invariants are specific to individual states within a single component (and "Map state explicitly" covers those). But many span the design — relationships between components, ordering guarantees across sequences of operations, structural properties that the system maintains by construction or by convention.
At each design step, ask:
The test for whether invariants are well-articulated: can a new team member, reading only the design, list the contracts they must not violate? If any contract requires reading the implementation to discover, it's implicit.
When this discipline pushes toward articulating more invariants and the skeptic questions whether those contracts are necessary, surface the tension — both are needed. The skeptic prevents over-specification (inventing invariants the design doesn't actually need), while invariant articulation prevents under-specification (leaving real contracts unstated). The design process should make the tension visible so it gets an explicit decision.
Note that the skeptic's standard subtraction test — "what breaks if we remove this?" — is misleading for invariants. Removing an invariant breaks nothing now. The cost is deferred: it shows up when a future change violates a contract nobody knew existed. The right skeptic test for invariants is "what does this prevent?" — not what breaks today, but what incorrect states or sequences does this contract make impossible.
The skeptic asks "should we remove this?" — the subtraction lens. Cohesion is the complementary grouping lens: do the things that survived subtraction belong together?
A type or module can pass every other discipline and still be a grab-bag of loosely related functionality. Each piece is justified individually — the skeptic couldn't remove any of them, the names are precise, the state is mapped, the invariants are articulated. But the pieces don't cohere. They ended up in the same type because they were discovered at the same time, or because they operate on the same data, or because nobody asked whether "same type" was the right grouping.
The cost of low cohesion is indirect: changes to one responsibility ripple into code that deals with an unrelated responsibility, because they share a type. Tests for one responsibility drag in setup for the other. The type's name becomes either dishonest (describing only one of its jobs) or vague (describing the grab-bag with a word like "service" or "utils").
At each design step, ask:
utils, common, misc) has
the same problem at a larger scale — the types don't cohere, they just
cohabitate.The test for cohesion: if you split this type along the cluster boundaries, would either half need to reach back into the other to function? If yes, the coupling is real and the grouping may be justified. If no, the grouping is accidental and the type should be split. For data types whose fields represent attributes of a single domain concept and co-travel through the system, cohesion comes from domain identity, not field interdependence — the split test applies to behavioral clusters, not to attribute groupings.
"Distinguish values with distinct semantics" can independently reach the same conclusion — different responsibilities often mean different semantic guarantees, which that discipline would flag as needing separate types. When both disciplines point at the same split, it's a strong signal — but validate even strong signals against consumer sketches, because two disciplines agreeing on the wrong split is still the wrong split. When only one does, surface the tension.
"Name things precisely" often reveals cohesion failures: a type that can't be named without "and" or that requires a vague name like "context" or "manager" is usually doing too much. The naming discipline catches the symptom; this discipline identifies the structural cause.
When this discipline pushes toward splitting a type and the skeptic resists because each piece is too small to justify its own type, surface the tension. Small pieces that don't cohere are still better separated — a small focused type is easier to understand than a large incoherent one. But the skeptic's resistance may also signal that the pieces genuinely belong together and the cohesion check is being too aggressive. The design process should make the tension visible.
Every design has directions that are cheap to extend and directions that are expensive to change. When you decide "variants are types implementing a trait" or "data flows through a pipeline of transforms" or "each handler owns its own state," you create a grain. Adding another type to the trait family is with the grain. Changing the data flow from push to pull is against it. Neither direction is inherently right — what matters is knowing which is which so the tradeoff is deliberate.
This is not speculation about future needs. It's understanding the shape of what you're building now. A design where adding a new output format requires touching every handler is fine — if the team knows that and decided the tradeoff was worth it. A design where that same coupling exists but nobody noticed it is a future surprise.
At each design step, ask:
The consumer-first discipline naturally reveals grain: sketching what "add one more variant" looks like as consumer code shows whether the grain runs in a useful direction. If the sketch for a new variant is clean and minimal — just implement the trait, register it, done — the grain is favorable. If the sketch requires the consumer to understand and modify internals scattered across the codebase, it isn't. When applying grain awareness, extend the consumer sketch beyond just current usage to include at least one "what would adding X look like?" scenario. Pick the most mundane addition — one more variant of the same kind the design already handles, not a fundamentally different kind of thing. If even mundane additions are expensive, the grain is genuinely misaligned. If only exotic additions are expensive, that's usually the correct tradeoff — designs can't be cheap in every direction.
The test for whether you've surfaced the grain: can you state, for each major structural decision, what it makes cheap and what it makes expensive? If you can't answer that for a decision, you don't yet understand its consequences.
"Check cohesion" asks whether things belong together. This discipline asks what the grouping makes cheap or expensive. A cohesive type can still have grain that's misaligned with the domain — the grouping is right, but the extension point runs in the wrong direction. Conversely, grain analysis might reveal that a type with good cohesion should be structured differently to align extension costs with the domain's variation points — which feeds back into whether the current grouping is actually the right one.
"Map state explicitly" makes grain decisions concrete. A choice between a flat enum and a trait-based state machine is fundamentally a grain choice: the enum makes adding transitions cheap (one match in each method) but adding states expensive (touch every match site); the trait-based machine makes adding states cheap (new class, implement the trait) but adding transitions expensive (new method on every state class). Neither is better in the abstract — the right choice depends on whether the domain's variation is in new states or new transitions.
When grain analysis and the skeptic point in different directions, surface the tension — don't silently rework the design. The misalignment may be an acceptable tradeoff given other constraints. The distinction between the two lenses: grain awareness observes the structural consequences of decisions already made; the skeptic guards against acting on predicted needs that haven't materialized. If the tension forces you to articulate why the grain observation matters independent of any specific prediction, that's the process working correctly.
After sketching a design, look for ways a user could do something that looks correct but fails silently or in non-obvious ways:
The questions above target specific failure modes — things that go wrong. But a design can also fail by requiring knowledge it doesn't encode. Implicit mechanisms — setup ordering, required conventions, context-dependent behavior — create knowledge that exists only in the designer's head. After checking for concrete footguns, probe for implicit design knowledge:
The last question is a forcing function — it surfaces every piece of implicit knowledge the design depends on. Each answer is either an acceptable documentation requirement or a design problem to fix. If the list is long, the design is too implicit.
A candy-machine interface is one where the user can put the money in the slot and push the button and get something other than what they expected. Good design makes the right thing easy and the wrong thing impossible (or at least loud).
Two values that look similar but carry different guarantees, different lifetimes,
or different validation states are not the same thing. Sharing a type between
them forces callers to use out-of-band knowledge to tell them apart — which
guarantee does this String carry? Is this User from input or from the
database? Did this Config pass validation?
This discipline is an active counterbalance to subtraction. The skeptic asks "what breaks if we remove this type?" and the answer may be "nothing breaks right now." But that's the wrong test when two values have different semantics. The right test is: can a caller distinguish them without context they shouldn't need? If collapsing two types into one means the caller must remember which kind they're holding, the types should stay separate — even if the fields are identical today.
At each design step, ask:
When this discipline and the skeptic's subtraction pull in opposite directions, that's a tension worth surfacing — not a conflict to resolve silently. Both are needed: subtraction prevents unnecessary abstraction, distinct-semantics prevents premature unification. The design process should make the tension visible so it gets an explicit decision.
Error types are not just return values — they're an API. "Distinguish values with distinct semantics" asks the general question: do any values in this design have different meanings but share a representation? This discipline applies that question specifically to error types, where the consequences of getting it wrong are distinct: a caller that can't tell errors apart can't handle them correctly, and context lost at a wrapping boundary is gone forever.
At each layer or boundary in the design:
The consumer-first discipline sketches what error handling looks like from outside — it reveals what distinctions the caller needs. This discipline designs the error types themselves, ensuring they carry the right distinctions and enough context. Both are needed: the consumer sketch is the specification, this discipline is the implementation check.
When this discipline pushes toward more error variants and the skeptic's subtraction pushes toward fewer, surface the tension — don't resolve it silently. Each error variant added to a public API is hard to remove later; the consumer sketch shows which distinctions the caller actually needs versus which are internal detail.
Design is full of decision points where two reasonable paths diverge. When you hit one — when a design choice could go either way and you don't have a clear reason to prefer one — stop and ask. Present the tradeoff, say what you're uncertain about, and get input before committing to a direction.
The instinct to keep moving and produce a complete design is the enemy here. An unasked question that leads to a wrong turn costs more than the pause. The whole point of collaboration is that the human has context and judgment that the model doesn't. Use it.
This applies especially to:
Design explores the territory — the full space of what could exist, how pieces relate, where the constraints are. A plan picks one path through explored territory to implement within a specific scope. The map doesn't stop being useful once you pick a path. Keep mapping while you walk, because what you learn during implementation changes your understanding of the territory.
Design insights that go beyond the current plan's scope are still valuable. They inform constraints on what you build now (don't build something incompatible with where you're headed) and get recorded (discussions, issues, plan notes) so future work can use them. "This is the right design" and "we implement all of it now" are separate decisions.
The disciplines in this skill — consumer sketches, abstraction questioning, footgun scanning — are not a checklist you run once during a "design phase." They're lenses you keep applying. Every time the design changes, run them again on the changed parts and on the parts that depend on what changed. A discipline that only runs once is a ritual, not a practice.
These are the specific failure modes this skill exists to prevent. If you catch yourself doing any of these, stop and reorient.
Designing the complete system at once. If your first artifact is a full design document with all types, all interactions, all edge cases — you skipped the discovery process. Back up. What's the smallest piece?
Starting from solution shape instead of problem statement. If your design document opens with type definitions rather than "the user needs to..." — you're retrieving, not designing.
Committing to the first interpretation. When the problem statement implies an approach ("add convenience wrapper methods"), treating that as the design rather than as a hint about a pain point. If every persona produced the same kind of solution, nobody explored — they all pattern-matched on the problem statement and dressed up the first idea. The tell: the "alternatives considered" section is empty or lists only variations on the same approach, not genuinely different framings of what the problem is asking for.
Importing patterns without questioning fit. String-keyed maps, middleware chains, context objects, store traits — these exist in many frameworks. Their presence elsewhere is not evidence that your system needs them. Evaluate each one against the actual consumer code.
Consumer code as an afterthought. If the example usage appears at the end of the design document (or not at all), the API was designed without its primary constraint. Move the consumer code to the beginning.
Giving the framework too much responsibility. When in doubt, the user owns it. The framework can always take on more responsibility later; taking it back is a breaking change.
Claiming consistency without verifying it. "This uses the same API as X" is a testable claim. Write both usages side by side. If they don't match, the design has a problem — either make them actually match or drop the claim and design each on its own merits.
Naming from the solution domain instead of the problem domain. If you
can't explain what a type does without restating its name — "it manages
connections," "it handles requests," "it processes events" — the name is a
solution-domain label, not a problem-domain description. The tell is that the
name describes the type's role in the code structure rather than what it means
to the user. A ConnectionManager might be fine as an internal implementation
detail, but if it's in the public API, the user has to open the docs to find
out what it manages and how.
Inventing when extending would suffice. Proposing a new type when the codebase, language, or stdlib already has something that serves the same purpose. The new type may feel cleaner in isolation but adds a concept the user must learn and the codebase must maintain.
Collapsing distinct semantics into a shared type. Using one type for two values that carry different guarantees — user input and a validated record, a database row and an API response, a request and a stored entity. The fields may look identical, but the values mean different things at different boundaries. The skeptic's "what breaks if we remove this?" may not catch it because nothing breaks structurally — the breakage is semantic, showing up as a caller that treats an unvalidated input as a trusted record or vice versa.
Treating error types as an afterthought. Designing the happy-path types and interactions first, then bolting on generic error types at the end. Error vocabularies designed this way tend to be too coarse — one error type for many distinct failure modes — because they weren't part of the design exploration. Error types should emerge alongside the domain types; they're part of the API, not an appendage.
Skipping evaluation. Producing a design from the design personas and going straight to implementation without running the evaluation stage. The evaluation personas catch structural problems — security gaps, performance ceilings, untestable interfaces, adversarial usage scenarios — that the design personas aren't looking for.
Representing state implicitly through field combinations. When multiple fields interact — boolean flags, optional fields, status enums paired with counters — the component has an implicit state machine. Boolean flags are the most common form: n interacting flags create 2^n combinations, most invalid (authenticated-but-not-connected is probably illegal). But any set of fields whose valid combinations are a proper subset of all possible combinations has the same problem: no transitions, no invariants, no handling for illegal combinations. Name the states instead: the valid combinations are the actual states, and making them explicit lets the type system enforce which transitions are legal.
Leaving invariants implicit. When a design establishes contracts between components — ordering requirements, data relationships, structural properties — but never states them. The contracts exist whether or not they're documented: callers depend on them, implementations preserve them, and future changes break them. The difference between a stated invariant and an unstated one is that when the stated one breaks, you know what went wrong and why. When the unstated one breaks, you get symptoms far from the cause and no trail to follow.
Committing to structure without understanding its grain. Making structural decisions — "variants are enum cases," "handlers are registered at startup," "data flows through a transform pipeline" — without asking what those decisions make cheap and what they make expensive. Every structural choice creates a grain; ignoring the grain means discovering the tradeoff only when you need to go against it, at which point the cost is high and the decision is baked in. The result is designs where the expensive direction turns out to be the one the domain actually needs, and nobody knew until the first extension attempt.
Embedding infrastructure in domain types. When a domain type directly uses database clients, HTTP types, cache interfaces, or other infrastructure. The domain type might be correct about the business logic, but it can't be tested without the infrastructure, can't be reused in a different deployment context, and can't survive an infrastructure swap. This is distinct from "accumulating unrelated responsibilities" — the type may be cohesive in purpose but coupled to the wrong layer.
Accumulating unrelated responsibilities in a type. When a type grows by accretion — each new responsibility is too small to extract on its own, so it gets added to the nearest existing type. The result is a type that does five things, none of which is its primary purpose, because no single addition was large enough to trigger extraction. The tell: methods or fields that cluster into subsets that don't interact with each other, or a type whose name has drifted to something vague ("manager," "context," "helper") because no precise name can describe everything it does. Unlike "collapsing distinct semantics," which is about values sharing a type they shouldn't, this is about responsibilities sharing a type they shouldn't.
When designing Pony APIs, libraries, or framework features:
Any val is almost always a sign that
the design is avoiding a harder type-safety question — answer that question
instead.pony-ref. Marker primitives with scattered
match _state / if _state is checks are a step above boolean flags but
still fragment behavior across the actor's methods — use them only for
simple guards within a single behavior, not for routing different behavior
across multiple events. The test: if more than one behavior needs to check
the state to decide what to do, the actor needs a trait-based state machine.val but the consumer
naturally produces ref, there's a friction point worth examining.Load the Pony language reference (capabilities, PonyCheck, stdlib pitfalls, mort pattern). Load it before Pony coding sessions.
Ensemble code review with specialized reviewer personas. Has full (8-persona) and lightweight (3-persona) modes. Load when conducting a code review of a PR, branch, or local changes.
Ensemble documentation review with specialized reviewer personas. Has full (8-persona) and lightweight (3-persona) modes. Load when reviewing documentation-only changes where code-focused personas don't apply.
Ensemble workflow for producing higher-confidence outputs through decorrelated reasoning paths. Load when the human explicitly requests the ensemble approach.
Property-based and generative testing patterns. Load when writing property-based tests, generators, or generative test suites.
Two-stage ensemble for planning meaningful tests. Load when writing tests for new features or reviewing test quality. Counters the tendency to write tests that exercise the stdlib instead of your code. Has full (8-persona) and lightweight (5-persona) modes.