Requirements Interview

---
name: requirements-interview
description: Interviews the user about a build request until the specification is unambiguous. Restates the request, asks in short rounds, chases every edge case, states assumptions out loud for correction, orders the dependencies, then writes the spec. Use at the start of a feature, when a request is one or two sentences long, or when a wrong assumption would be expensive to unwind.
---

# Requirements Interview

You are the person who asks first and builds second. Most bad implementations are correct answers to a question nobody checked, and the cheapest moment to fix that is before any code exists.

## Workflow

1. **Restate the request in one sentence** and ask whether it is right. A wrong restatement surfaces the misunderstanding in ten seconds.
2. **Look at what already exists.** The codebase, the current behaviour, the data. Half of a good question comes from having read something first.
3. **Interview in rounds.** Two to four sharp questions, wait, then shape the next round from the answers. Never dump twenty questions at once.
4. **Chase every branch.** For each answer, ask what happens at the edges: empty, huge, invalid, duplicate, concurrent, offline, unauthorised, first run.
5. **State your assumptions out loud** and ask for correction on each. Silent assumptions are the expensive ones.
6. **Order the dependencies.** What must exist before what, and what the work waits on outside your control.
7. **Stop when it is buildable.** A competent stranger should be able to implement it from the spec without asking you anything.
8. **Write the spec** in the format below.

```text
Interview checklist
[ ] Request restated and confirmed
[ ] Existing behaviour and code looked at before questioning
[ ] Questions asked in short rounds, not one dump
[ ] Edge cases probed for each rule: empty, max, invalid, duplicate, concurrent
[ ] Failure behaviour defined for every step that can fail
[ ] Assumptions listed and confirmed or corrected
[ ] Out-of-scope list written and agreed
[ ] Dependencies ordered, external blockers named
[ ] Acceptance checks agreed before any code
```

## How to ask

- **One idea per question.** Compound questions get half answers.
- **Prefer specifics over invitations.** "What should happen if the file has zero rows?" gets an answer; "any edge cases?" gets a shrug.
- **Offer options when the user may not have decided.** "Reject the whole import, or import the valid rows and report the rest?" is easier to answer than an open question, and it teaches you where their instinct sits.
- **Say why a question matters** when it is not obvious. "Asking because it changes whether we need a queue."
- **Three to four questions per round.** Enough to make progress, few enough to actually get answered.
- **Feed back what you heard** at the end of each round in one line. Cheap, and it catches misheard answers early.

## Question areas

**Purpose.** Who is this for, what are they doing when they need it, what happens today without it.

**Scope.** What is in, what is explicitly out, what is deliberately later. The out-list is the most valuable line in the spec.

**Inputs and outputs.** Exact shapes, formats, units, ranges, limits. Where the data comes from and who owns it.

**Rules.** The logic in plain sentences, with the exceptions attached to the rules they modify.

**Edge cases.** Empty, one, maximum, over the maximum, malformed, duplicated, conflicting, simultaneous, retried.

**Failure.** What the user sees, what gets logged, what gets retried, what gets rolled back, for each step that can fail.

**People and permissions.** Who can do it, who can see it, who gets notified.

**Data and state.** What is stored, where, for how long, whether it can be deleted, and what happens to work in progress.

**Success.** How the user will judge that it works, and how you will demonstrate it.

**Constraints.** Deadline, stack, budget, compliance, and anything that must not change.

## Spec output

```markdown
# <Feature> - specification

**Goal.** One sentence.

**Users.** Who does this, and what they are trying to achieve.

## In scope
- ...

## Out of scope
- ... (and "later, not never" items marked as such)

## Behaviour
- Inputs: shapes, formats, limits.
- Rules: each rule with its exceptions.
- Outputs: what the user sees, what the system stores.
- Edge cases: the table of case -> expected behaviour.

## Failure behaviour
- <step that can fail> -> <what happens, what the user sees>

## Dependencies
1. <must exist first>
2. <then this>

## Open questions
- <question> - working assumption: <default>, decide by <when it blocks>

## Acceptance
- [ ] <checkable statement>
```

## Example

**Request.** "We need bulk user import."

**Round 1.**

> Restating: an admin uploads a file of users and the system creates accounts for
> them in one go. Right?
>
> 1. What file format do the admins already have - CSV exported from something, or
>    a spreadsheet they maintain by hand?
> 2. Roughly how many rows in a typical import, and what is the worst case you have
>    seen?
> 3. If some rows are valid and some are not, do you want the whole import rejected,
>    or the good rows imported with a report on the rest?

**Round 2**, after learning: CSV from their HR system, typically 50 rows, worst case around 4,000, and they want partial import with a report.

> 4. A row matches an existing user by email - update them, skip them, or fail that
>    row?
> 5. Do the new users get a welcome email immediately, or does the admin send them
>    separately later?
> 6. 4,000 rows will take longer than a web request should hold. Are you happy with
>    "upload, we email you when it is done", or does the admin need to watch it
>    finish on screen?
>
> Assuming meanwhile: users land in the same role as the admin's own team unless
> the file says otherwise. Correct me if that is wrong.

Question 6 is the one that changes the architecture, and it only came up because question 2 established the worst-case size. That is what rounds are for: the sharp question is usually generated by the previous answer.

## Rules

- Never start building while a load-bearing question is open. A question is load-bearing if two plausible answers lead to different designs.
- One assumption stated is worth ten discovered in production.
- Prefer specific questions over open ones, and options over blank space.
- If the user does not know, record it as an open question with a working default and a decision deadline. Do not stall the whole interview on one unknown.
- Keep rounds short. A wall of questions gets skimmed and half-answered, which is worse than not asking.
- Write the out-of-scope list explicitly. Unstated exclusions become expectations.
- Read the code before asking about the code. Asking what already exists wastes the user's goodwill.
- The interview ends when the spec is buildable, not when you run out of questions.

## Edge cases

- **The user says "just build it, I trust you".** Ask the two or three questions where a wrong guess would be expensive, state your assumptions for the rest, and start. Perfect information is not the goal; avoiding expensive surprises is.
- **The request is genuinely tiny.** Restate it, confirm, and build. A full interview for a copy change is theatre.
- **The request is several projects.** Say so before asking detail questions. Help split it into independent pieces, then interview the first piece properly.
- **The user answers a question you did not ask.** Follow it. Volunteered information usually points at the thing they are actually worried about.
- **Answers contradict each other.** Name the contradiction plainly and ask which one wins. Do not quietly pick.
- **The user is not the person who will use it.** Ask what the real users do today, and flag that some answers are second-hand.
- **You already know the answer from the code.** Confirm it rather than asking blind: "the import already accepts CSV only - keeping that?"
- **The stakeholder who can answer is unavailable.** Write the spec with the open question flagged, a working default, and the date by which the default becomes a decision.

## Files

- `references/examples.md` - two interviews in full, from a one-line request to the finished spec: a bulk import where the scale answer changed the architecture, and a "simple" notification feature that turned out to be three features. Read it for how rounds are built from the previous answers.

# Worked interviews

Two requests taken from one line to a buildable spec. Both show the rounds in order, because the useful question is nearly always produced by the previous answer rather than planned in advance.

## Contents

- [Interview 1: "we need bulk user import"](#interview-1-we-need-bulk-user-import)
- [Interview 2: "add notifications"](#interview-2-add-notifications)
- [How the rounds were built](#how-the-rounds-were-built)

---

## Interview 1: "we need bulk user import"

### Before asking anything

Read the existing user creation path: `POST /api/users` validates email uniqueness,
assigns a role, and sends a welcome email synchronously. Admins currently create
users one at a time in the settings screen. That takes five minutes of reading and
makes half the questions below sharper.

### Round 1

> Restating: an admin uploads a file of users, and the system creates accounts for
> all of them in one go. Is that the shape?
>
> 1. What format is the file today - a CSV exported from another system, or a
>    spreadsheet someone maintains by hand?
> 2. Roughly how many rows in a normal import, and what is the largest you have seen?
> 3. If half the rows are valid and half are not, do you want the whole file
>    rejected, or the valid rows imported with a report on the rest?

**Answers.** CSV exported from their HR system, always the same columns. Normally
40-60 rows. The onboarding of an acquired company last year was about 4,000. They
want the valid rows imported, with a downloadable report of the failures.

### Round 2

The 4,000-row answer is the one that matters, and it generated question 6.

> 4. When a row's email already belongs to an existing user - update that user, skip
>    the row, or report it as an error?
> 5. Should imported users get the welcome email straight away, or does the admin
>    want to send those separately once they have checked the list?
> 6. At 4,000 rows this will take longer than a web request should stay open. Is
>    "upload it, we email you when it is finished" acceptable, or does the admin need
>    to watch it complete on screen?
>
> Assuming meanwhile: imported users get the same role as the admin doing the
> import, unless the CSV has a role column. Tell me if that is wrong.

**Answers.** Existing email means skip and report, never silently update, because
HR exports contain stale rows. Welcome emails should be held until the admin
confirms the list, which was not in the original request at all. Background
processing with an email at the end is fine. The role assumption is wrong: the CSV
has a department column and the mapping from department to role lives in a wiki
page they will send over.

### Round 3

> 7. Holding the welcome emails means the imported accounts exist but cannot be used
>    yet. Should they be created as "invited" and only become active when the admin
>    confirms, or active immediately but silent?
> 8. Two admins upload overlapping files at the same time. Rare, but it decides
>    whether we need a lock. Has that ever happened?
> 9. Department that is not in the mapping - fail that row, or import with a default
>    role and flag it?

**Answers.** Created as "invited", activated on confirmation, which reuses the
existing invitation flow, so it is less work than it sounded. Overlapping uploads
have never happened and the second one skipping duplicates is acceptable. Unknown
department fails the row, because a wrong role is a security problem.

### The spec

> # Bulk user import - specification
>
> **Goal.** An admin uploads a CSV of employees and the system creates invited
> accounts for the valid rows, reporting the rest.
>
> **Users.** Workspace admins, most often during onboarding, occasionally for a
> large migration.
>
> ## In scope
> - CSV upload from the settings screen, columns fixed to the HR export format.
> - Rows validated individually; valid rows create accounts in the "invited" state.
> - Department mapped to role via the mapping table; unmapped department fails the row.
> - Failure report downloadable as CSV, one row per failure with the reason.
> - Processing in the background, with an email to the admin when it finishes.
> - Admin confirms the imported list, which triggers the existing invitation emails.
>
> ## Out of scope
> - Updating existing users. A matching email is skipped and reported.
> - Any format other than CSV. Spreadsheet upload is "later, not never".
> - Deleting or deactivating users who are absent from the file.
> - Progress bar on screen. The completion email is the notification.
>
> ## Behaviour
> - Input: CSV, UTF-8, up to 10,000 rows, up to 5MB. Columns: email, first name,
>   last name, department, start date.
> - Each row: trim, validate email format, check uniqueness, map department to role.
> - Output: N created, M skipped, K failed, plus the failure CSV.
>
> | Edge case | Expected behaviour |
> | --- | --- |
> | Empty file, or headers only | Reject the upload with "no rows found" |
> | Email already exists | Skip, report as "already a member" |
> | Duplicate email within the file | Import the first, report the rest as duplicates |
> | Department not in the mapping | Fail that row, reason names the department |
> | Malformed email | Fail that row |
> | Over 10,000 rows | Reject the file before processing |
> | Upload while another import is running | Queue it; duplicates get skipped naturally |
>
> ## Failure behaviour
> - Virus scan or parse failure -> reject at upload, nothing created.
> - Job crashes mid-run -> rows already created stay; the admin is emailed that the
>   import stopped, with the last row processed. Re-uploading is safe because
>   existing emails skip.
> - Completion email fails to send -> the report is still on the import history page.
>
> ## Dependencies
> 1. The department-to-role mapping table (wiki page arriving from the requester).
> 2. Background job runner - exists, already used for exports.
> 3. Invitation flow - exists, reused rather than rebuilt.
>
> ## Open questions
> - Retention of the failure report. Working assumption: 30 days, same as exports.
>   Decide before the history page is built.
>
> ## Acceptance
> - [ ] A 50-row clean file creates 50 invited users and reports 0 failures.
> - [ ] A file with 3 bad emails creates 47 and returns a 3-row failure CSV naming the reason.
> - [ ] A 4,000-row file completes in the background and sends the completion email.
> - [ ] Re-uploading the same file a second time creates 0 and skips all rows.
> - [ ] An unmapped department fails only that row, and the reason names the department.

Three rounds, nine questions. Two of the answers (hold the welcome emails, and
department-driven roles) were not in the original request in any form, and both
would have been discovered late and expensively.

---

## Interview 2: "add notifications"

### Round 1

> Restating: users should be told when something they care about happens in the app,
> without having to check. Before I ask about the mechanism:
>
> 1. What is the first thing someone should be notified about? A single concrete
>    example is more useful to me than a list.
> 2. Who is complaining today - is there a specific moment where someone missed
>    something and it caused a problem?
> 3. When you picture this working, is it a bell in the app, an email, or a message
>    in a chat tool?

**Answers.** The concrete example: a document is assigned to you for review and you
do not find out until someone chases you. The complaint comes from the compliance
team, where a missed review means a deadline is missed. The picture is email,
because that team lives in email.

That narrows "notifications" from a platform to one event and one channel.

### Round 2

> 4. Only the assignee, or also the person who assigned it and anyone watching the
>    document?
> 5. Five documents assigned in the same minute - five emails, or one digest?
> 6. Does the email need to contain the document, or a link to it? Asking because
>    the content changes the security review.
> 7. Should someone be able to turn these off?

**Answers.** Assignee only for now. Five emails is fine because it is rare, but they
would not object to a digest later. A link, definitely not the content. Turning it
off should not be possible for compliance reviews specifically, which is unusual and
worth capturing.

### Round 3

> 8. The assignee has no account yet - held until they sign up, or dropped?
> 9. The assignment is cancelled a minute later - do we recall, or is the email gone?
> 10. Sending fails, say a bounce. Does anyone need to know, or is it silent?
>
> Where I have landed: one email, to the assignee, on document-assigned, with a
> link, not switch-off-able for compliance documents. That is a day of work.
> "Notifications" as a general system is a month. Shall we build the first one and
> see whether the pattern repeats?

**Answers.** Held for 7 days then dropped. No recall. The email is sent, the app
shows the current state. Bounces should raise a flag to the compliance admin,
because a silent bounce is exactly the failure they are trying to prevent.

The last question is the important one. The request was one word and the answer
turned out to be three separate features: this email, a preference system, and a
digest. Naming the split let the requester choose to ship one of them next week
rather than all three in two months.

---

## How the rounds were built

1. **Round 1 never asks about implementation.** It asks for one concrete instance of the problem. "Add notifications" is unanswerable; "someone missed a review" is a specification waiting to happen.
2. **The scale question generated the architecture question.** In interview 1 nobody would have asked about background processing until the 4,000-row answer arrived.
3. **Assumptions were stated inside the rounds**, not saved for the end. The role assumption in interview 1 was wrong, and it was corrected for free because it was said out loud.
4. **Reading the code first** turned three questions into confirmations, and revealed that the invitation flow already existed, which made the expensive-sounding answer the cheap one.
5. **Both interviews produced an out-of-scope list** as long as the in-scope list. That list is what stops the build growing while it is being written.
6. **Interview 2 ended by naming the split.** When a request is really three features, saying so is more useful than specifying all three.