Discovery Questions

Discovery questions

Discovery fails quietly. Nobody skips it on purpose — they answer three questions, feel like they understand the problem, and start designing. gate.discovery exists because a design built on three answered questions and forty silent assumptions looks identical to one built on real discovery, right up until it ships.

How this skill is used

The discovery-analyst agent runs this skill to interview the person requesting the system (or to work through the questions directly, when no interview is possible) and writes 01-discovery.md. 00-frame.md comes first — this skill assumes an outcome sentence and non-goals already exist.

Do not ask every question in the bank. Select the questions relevant to this goal, in this section order, and stop each section once you have a real answer — depth beats coverage.

The answer-tagging convention

Every question in 01-discovery.md gets one of two tags on its answer line. There is no third tag.

• [answered] — someone stated this, or it was verified against a system, document, or repo. Cite the source inline: who said it, or the evidence pointer (path/to/file.ts:L42, or a command and its output).
• [unknown] — asked, and genuinely not known yet. This is allowed. Say so plainly and name who could answer it or what would need to happen to find out.

Never write [assumed]. An assumption dressed as an answer is worse than a gap, because a gap is visible and an assumption is not — it survives into 02-user-flows.md and 04-roi.md as if it were fact. If you do not know, the tag is [unknown], not a guess with a hedge word in front of it.

### 31. What data do you collect today?
[answered] Order history and support tickets, both in the CRM
(`crm-export/schema.sql:L14-L40`). Product usage events are not collected.

### 61. What's your current tech stack?
[unknown] — no one on the call owns infrastructure. Follow up with the
platform team before `flow`.

Gate check

gate.discovery is green when every section used has at least one [answered] question and there are zero [assumed] tags anywhere in the file. [unknown] does not block the gate — it blocks nothing except pretending you know something you don't. A file that is honest about six unknowns passes; a file with one smuggled assumption does not, even if every other line is airtight.

Using the question bank

references/question-bank.md holds the full set, organized into the same eight sections used by 01-discovery.md: business context, process and operations, data and information, users and stakeholders, technical environment, AI-specific questions, project constraints, and follow-up deep dives. Pull questions from whichever sections the goal actually touches — a narrow internal tool will not need the full stakeholder-impact section; a customer-facing system usually needs all of it.

Three interviewing rules carried over from the source bank, because they are what makes an answer worth an [answered] tag instead of a polite deflection:

• Ask for the specific instance, not the generalization. "Walk me through the last time this happened" produces evidence; "does this happen often" produces an opinion.
• Get the artifact, not the description of the artifact. A sample export, a screenshot of the dashboard, or the actual failing ticket beats a paraphrase of what it contains.
• Notice what's not said. A section nobody has an answer for is a finding, not a gap to paper over — write the [unknown] and move on.

Writing 01-discovery.md

Structure the file as the eight sections, each holding only the questions you actually asked. End with a short "gaps" list that repeats every [unknown] in one place, so flow and decide know what they're building without.

Close with the stamp line: Generated by AI Architect · https://www.frankx.ai/ai-architect