| name | design-interview |
| description | Runs a structured, relentless design interview to reach a shared understanding of a plan, feature, or system. Walks the design tree branch by branch, resolving decision dependencies one at a time. Activate when the user says "interview me", "let's design", "walk me through", "review my plan", or shares a spec/plan and asks for feedback.
|
Design Interview — Relentless Clarity
This skill governs a structured design session. The goal is a shared,
precise understanding of every decision in the design tree before any
implementation begins.
🎯 Session Goal
Reach a state where:
- Every key decision is explicit and reversible or documented.
- Fuzzy language has been replaced with precise, canonical terms.
- Edge cases and domain boundaries have been stress-tested with concrete scenarios.
- Hard, surprising, trade-off decisions are captured as ADRs.
📥 Phase 0 — Gather Context Sources
Before the interview begins, ask the user where existing context lives. The
agent should review this context before asking the first design question,
so the interview builds on what already exists rather than starting from
scratch.
Ask exactly once:
"Before we start the design interview: is there existing context I should
review? For example — a codebase (repo path or file), a document, a Notion
page, a spec draft, meeting notes, past ADRs, or an architecture diagram.
Point me at anything that's relevant and I'll read it first."
If the user provides sources:
- Read codebases via directory listing and key file inspection (focus on
existing models, architectural patterns, and domain boundaries).
- Fetch and read any linked documents or pages.
- Absorb the context, then begin the interview. Reference the reviewed
material during the session — e.g. "I see your existing
Order model
already handles partial refunds. Does the new feature extend that, or is
it separate?"
If the user says no context exists:
- Proceed directly to the interview. Make no assumptions about prior art.
If the user says "I'll tell you during":
- Respect that and proceed. Do not push.
🔁 Interview Protocol
One question at a time
Ask exactly one question, then wait for a response before continuing.
Never batch questions. Never move to the next branch until the current
one is resolved.
Always provide a recommended answer
For every question you ask, provide your own recommended answer first:
"My recommendation: [answer]. Reason: [one sentence]. Do you agree, or
would you adjust?"
This keeps the session moving and forces concrete reactions rather than
open-ended thinking.
Walk the design tree
Identify the top-level decisions first, then recurse into sub-decisions.
Resolve dependencies between decisions before moving to dependent ones.
🔬 During the Session
Sharpen fuzzy language
When the user uses vague or overloaded terms, propose a precise canonical
term immediately:
"You said 'account' — do you mean the Customer (the billing entity)
or the User (the person logging in)? I'll use whichever term you
confirm going forward."
Once a canonical term is agreed, use it consistently for the rest of the
session.
Stress-test with concrete scenarios
When discussing domain relationships or boundaries, invent specific
scenarios that probe edge cases:
"Scenario: a Customer has two Users. One User is deleted. What happens
to the Customer's billing history? Does it stay, transfer, or become
orphaned?"
Scenarios should force the user to be precise about behavior at the
boundaries — not just the happy path.
📋 ADRs — Offer Sparingly
Only offer to create an ADR when all three conditions are true:
| Condition | Question to ask yourself |
|---|
| Hard to reverse | Is the cost of changing this decision later meaningful? |
| Surprising without context | Will a future reader wonder "why did they do it this way?" |
| Real trade-off | Were there genuine alternatives, and was one chosen for specific reasons? |
If any condition is missing, skip the ADR. Do not offer one as a
courtesy or to signal thoroughness.
When all three are met:
"This feels like an ADR candidate — hard to reverse, non-obvious, and
the result of a real trade-off. Want me to draft one?"
🔗 Integration
pair-mode
When pair-mode is active, this skill runs naturally within that
collaboration contract — the user drives scope and priority, the agent
drives precision and structure. All pair-mode communication rules apply:
no silent pivots, no unilateral decisions.
problem-solving
Use the decision format from problem-solving when a design question
resolves into a concrete implementation choice:
Decision needed: [one sentence]
My pick: [choice] because [one reason]
Risk: [what could go wrong]
Test: [smallest scenario or question that validates it]
This bridges design decisions directly into implementation decisions
without losing context.
tdd-workflow
When the interview concludes and implementation begins, hand off directly
to tdd-workflow. Decisions made during the interview become the
acceptance criteria for the first failing tests.
premortem-this
After the interview produces a clear, agreed plan, run premortem-this to
stress-test it. The interview sharpens the plan; the premortem finds the
hidden assumptions, weak decisions, and missing risks before resources are
committed.
long-term-memory
After the session, key decisions — especially ADRs and canonical term
definitions — should be written to the project memory file per the
long-term-memory skill. This preserves the shared understanding across
sessions.
