elicit

name	elicit
description	Use when building a blueprint from scratch through conversation — specifying a new feature, capturing a planned system, or turning stakeholder descriptions into a structured living spec.

Build a blueprint through conversation. Surface ambiguities, establish shared vocabulary, trace real flows end-to-end, produce a document the whole team can reason about. Same principles whether talking to a product manager about a new feature or a founder describing a system.

A scenario without a trigger is a story without a beginning Happy paths alone are half a spec Defining a term using that term gives the reader nothing If you cannot name the policy, regulation or decision, mark it as an open question "The system sends an email" has a missing actor. Who triggers the send? Rephrase at the behaviour level. See core discipline. If you do not know, open a question and assign it. Do not invent an answer. Show captures, get confirmation, then continue Surface immediately when detected It is the location of a requirement. Ask: "Depends on what? Walk me through the cases." Elicitation is a conversation. Generating all at once produces confident-sounding fiction. Start every session with: 1. Establish goal: "We are going to capture how this works and what it must do — not how we will build it." 2. Establish scope: "What are we covering today? One flow, or the whole feature?" 3. One-sentence question: "In one sentence, what does this thing do?" The one-sentence answer reveals alignment before spending time on details. Ask one question. Wait for the answer. Probe the answer. Then ask the next. Bundled questions produce bundled answers that are hard to separate later. After each phase, show what has been captured and ask for confirmation: "Here's what I've captured so far. Does this match your understanding? Is anything missing or wrong?" Show only the section just captured — not the whole draft. Checkpoints prevent wrong work accumulating silently. Convert to an open question immediately: "That's fine — let me note that as an open question rather than assume. Who should resolve this? By when?" Then move on. Accumulate open questions; return to them at the end. Surface immediately: "I want to flag a conflict. Earlier you said [X]. Now you're saying [Y]. These cannot both be true. Which takes precedence? Or is there a condition?" Do not silently note both. Name the conflict, explore it, resolve or log as open question with owner.

Track contradictions actively. Keep a mental (or explicit) list of key facts stated: statuses, rules, actor capabilities. When a new statement touches the same area, check it against what was said before.

Park it: "That sounds important — let me note it. I'll add it to the out-of-scope list. For now, can we stay focused on [current topic]?" Scope creep produces blueprints that are accurate about many things but authoritative about nothing. Name transitions explicitly: "Good — I have the actors and terminology captured. Let me show you what I have, then we'll move to user stories." At the end of every session: 1. Show the full draft (or sections covered this session) 2. Read through open questions — assign owner and deadline to each 3. Record decisions made during the session in the decision log with rationale 4. State what is covered and what still needs follow-up "What is this blueprint about — one sentence?" — gets to the core without implementation. If the answer contains a tech stack, redirect. "Is this new, a change to something existing, or documentation of something that already works?" — new → elicit forward from intent. Change → start from existing behaviour before the delta. Existing → use the distill skill instead. "What is definitely out of scope?" — out-of-scope is as important as in-scope. Get both lists before proceeding. "Are there related systems we should know about but not specify here?" — establishes boundaries and identifies related blueprints to reference.

Capture answers in context.md and scope.md.

Phases are numbered for reference, not prescription. Order can adapt. Verification checkpoints and contradiction checks are invariants; sequence is default.

Goal: Understand why this exists before capturing what it does. "What problem does this solve? Who has this problem today?" "What happens if this doesn't get built?" "Is there an existing workaround? What is broken about it?" "Who asked for this — and what did they actually say they needed?" "Is there a deadline? Fixed or flexible?"

"Here's the context I've captured: [show paragraph]. Does this accurately describe the problem and why this exists?"

Output: Write context.md — a new team member could read it to understand why this feature exists.

Features described as solutions ("we need a dashboard"). Redirect: "What decisions does someone currently make without enough information?" Goal: Name every party who interacts with the system. "Who uses this?" "Are there different types of user? What distinguishes them?" "Are there system actors — automated processes, external services?" "What can each actor do that the others cannot?" "Is there a guest or unauthenticated state?"

For each actor: name, who they are, what they can do, what they cannot do.

"Here are the actors I've identified: [list]. Are any missing? Does any actor cover two different roles that should be split?"

"Admin" covering both billing admin and user admin — different permissions, should be named separately. Goal: Build the shared vocabulary before anything else. "What are the main things this system manages — the nouns?" "What do you call [thing]? Does engineering use the same word?" "Is [term A] and [term B] the same thing, or different?" "Are there terms that might mean something different to someone outside the team?"

For each term, write a precise one-sentence definition — what it means in this system.

"Here are the terms I've defined: [show glossary]. Are the definitions accurate? Are there terms we use that aren't here?"

Resolution rule: When two terms exist for the same concept, resolve now. Pick one. Define it. The other must not appear in the document.

Two words for the same concept ("booking" and "reservation") One word meaning two different things to different stakeholders Terms that only make sense to insiders Goal: Capture who needs what and why. Format: As a [actor], I want to [action], so that [outcome]. "Walk me through this from the user's perspective, not the system's." "What are they trying to accomplish? What does success look like for them?" "Do we have evidence this is what users actually need, or is this our assumption?"

For each story, ask for evidence: analytics, support tickets, user research, observed behaviour. If absent, note as open question: "We believe users need X, but we have not validated this."

"Here are the user stories: [show list]. Are any missing? Does any story assume a need we haven't validated?"

Stories from the system's perspective ("the system processes"). Reframe: who is the actor, what is their goal? Goal: Trace real end-to-end journeys, including error paths.

Happy path first: "Walk me through [scenario] from start to finish." "What triggers this? User action? Time passing? External event?" "What is the first thing that happens?" "Then what? And then?" "What has changed when this is complete? What is the end state?"

Then probe every branch: "You described [decision point]. What determines which path is taken?" "Is that decision made by the user, the system, or an admin?" "What if [step] fails or is unavailable?" "What if the user waits too long? Are there timeouts?" "What if this action is triggered twice?"

Contradiction check after tracing a flow: "Does anything conflict with what we said in actors or terminology?" After multiple flows: "Do any flows make assumptions about the domain model we haven't captured?"

"Here is the [scenario name] flow: [show it]. Does this match how it actually works? Steps missing? Branches wrong?"

Flows that assume capabilities not yet in scope Flows with no terminal state Decision points with no stated owner "And then it sends a notification" without specifying who, when, and through what channel Goal: Name the entities, their states, and their relationships. "What are the things this system creates, stores, and manages?" "What states can [entity] be in? What does each state mean?" "What triggers the transition from one state to another?" "How is [entity A] related to [entity B]?" "Who creates [entity]? Who can change it? Who can delete it?" "What must always be true about [entity], regardless of state?"

Use the structured entity card format from the section guide (Section 7).

"Here is the domain model: [show entities]. States right? Entities missing? Relationships wrong?"

Boolean fields or nullable timestamps encoding implicit states. is_active + is_verified = four unnamed states. Name them. Goal: Capture constraints — what the system must do and what it must prevent.

Functional requirements: "What must always happen when [event]?" "What must never be allowed?" "Are there limits — maximums, minimums, quotas?" "Are there time windows — deadlines, expirations, schedules?"

Business rules: "Are there eligibility conditions?" "Are there role restrictions?" "Are there compliance requirements?" "What are the exceptions — cases where the normal rule does not apply?"

For every rule: name its source. Source-less rules can be changed by anyone. If you cannot name the source, open a question.

Non-functional requirements: specific thresholds, not vague adjectives.

• Not "should be fast" → "p95 response under 2s at 1,000 concurrent users"
• Not "should be secure" → "must satisfy SOC 2 Type II access controls"
• Not "should be available" → "99.9% uptime, 8h RTO, 1h RPO"

"Here are the requirements: [show list]. Any missing? Sources correct? Non-functional thresholds right?"

At the end of every session:

Open questions — everything unresolved: "We talked about [X] but were not sure. Let me capture that: [precise statement]. Who owns this? By when? What does it block?"

Decision log — everything decided: "We decided [X]. The reason was [Y]. Let me record that." Include: what was decided, why, who decided, what alternatives were considered.

Every open question must have an owner and a deadline.

When something is created, changed or sent, ask where it comes from, where it goes, who can see it. "You said the user receives a confirmation email. Where does the email address come from? What does it contain? What if the send fails?" Every decision has downstream effects. Ask what each choice implies. "You said invitations expire after 7 days. What happens to the slots that were offered? What does the candidate see when they click an expired link?" Voice uncertainty: "I am not sure what happens here — let me note this as an open question rather than assume." Voiced ambiguity gets resolved; silent ambiguity becomes a bug. When a new term appears, pause and define it. "You said 'pipeline' — what do you mean by that in this context?" Add to Terminology immediately. If you catch yourself using two terms for the same concept, resolve it on the spot. Ask: "Does the system do this today, or is this how you want it to work?" Both are useful but go in different places — existing behaviour is a starting point; intended behaviour is a requirement. Mixing them silently produces a spec that is half-true and half-aspirational. Long chains without decision points. Probe every step with "always?" or "only if...?" "Obviously" marks an unstated assumption. Probe: "Obviously the admin approves it — are there cases where approval is automatic? What if the admin is unavailable?" Conversation drifts to implementation. Redirect: "At the behaviour level, what needs to happen and when?" Scenarios from one actor's perspective miss multi-party interactions. "You described the buyer's journey. Walk me through the same flow from the seller's perspective." Only success scenarios. Probe each step: "What happens if this fails?" Two terms for the same concept. Do not annotate as "also known as" — resolve it. Pick one, use everywhere. A business rule nobody can explain the origin of. Do not include as fact. Open a question: "This rule exists in the current system. Do we know where it came from? Is it a legal requirement, a product decision, or something else?" Verification checkpoint shown for every section captured this session All contradictions surfaced and either resolved or logged as open questions Every open question has an owner and a deadline Every decision made this session is in the decision log with rationale Changelog updated if meaningful changes were made README.md manifest updated with current section statuses Next session scope agreed