gather-requirements

/gather-requirements — Decision-Grade Question interview

Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.

Ask the questions one at a time.

If a question can be answered by exploring the codebase, explore the codebase instead.

This is the /grill-me engine, pointed at a stakeholder data ask. The <what-to-do> block above is the whole interview loop — run it as written. "The plan" is the ask you're interrogating; shared understanding is reached when you can write a Decision-Grade Question (DGQ) that survives the action-change kill-switch. Everything below tells you what the grill must resolve, the one place it must not recommend an answer, and what to write when understanding lands. It is an interview, not a template — a generic requirements form fills in blanks; this skill recommends killing the ask when the kill-switch trips.

Soul: the action-change kill-switch

The one branch this skill exists to force:

If the answer to this came back the opposite of what you expect, what would change about what you build, ship, or decide?

This is the single exception to "for each question, provide your recommended answer" — never propose the action-change yourself. Recommending one coaches the user past the exact gap the skill exists to surface. If their answer is abstract ("we'd act on it", "it'd inform the roadmap"), push with concrete scenarios drawn from the ask — "Suppose it lands right at the threshold — then what?", "Suppose it splits sharply by segment — per-segment or aggregate?" — but let the user supply the reaction.

Three ways this branch resolves:

• Concrete action-change. A named actor does something different ("above 5% we hire a retention lead; below, we don't"). Record it; keep grilling the rest of the tree.
• Vague gesture. Push once for a specific actor and behaviour. If none comes, the DGQ is needs-follow-up — the answer has to come from the stakeholder, not your imagination.
• Nothing. No decision shifts, nobody acts differently. Trip the kill-switch: stop grilling, write the DGQ status: rejected / action_change: nothing, and record who was asked and what they couldn't name. A rejected DGQ is a durable record of a deliberate non-build, not a TODO to revisit. Surface this without apology — recommending against a build is the differentiator.

Resumability — check before you start

Before opening a fresh grill, scan docs/requirements/. If DGQs exist, pause and offer to (1) continue a draft/needs-follow-up file, (2) start new, or (3) list all — one line each: <path> — <status> — <decision>. Treat accepted/rejected as immutable. Create docs/requirements/ only on first write, not before.

Branches the grill must walk

"Shared understanding" for a DGQ means you can fill its contract. Walk the tree until each of these is resolved or explicitly deferred — adapt the order to the conversation, don't recite them as a checklist:

• Who's asking, and who consumes the result? Names or roles. The gap between asker and consumer is where action-change confusion usually hides — flag it. The asker drives the filename.
• What decision(s) is this? Listen for plural decisions hiding in one ask ("churn dashboard" unpacks into what counts as churn + which segments + refresh cadence). If several surface, have the user pick one to drill fully now and stub the rest (see below).
• The action-change — the kill-switch above.
• Signal → spec. Turn the felt need ("understand churn") into something buildable ("monthly churn by acquisition channel, rolling 90-day, excl. free-tier"): sources, metrics, dimensions, windows, exclusions. If they must check with the stakeholder first, mark needs-follow-up — don't invent the spec.
• The undercurrents — sensitivity, cadence, governance, cost envelope. Sweep these in one pass, not four separate interrogations. "Don't know" → a placeholder plus an open follow-up; never infer silently.

When you explore instead of asking, also read CONTEXT.md's glossary, sibling DGQs, and docs/adr/. If a stakeholder term collides with the glossary, call it the moment you notice: "the glossary defines churn as X, but you seem to mean Y — which is it?" See references/dgq.md for the exact frontmatter fields, enum domains, and body section order — consult it; don't reproduce it into the grill.

ADR-moment — route out, don't absorb

If the decision is a cross-cutting platform commitment — tooling choice, modelling convention, governance posture, architectural shape, or anything spanning teams/pipelines rather than one ask — stop the grill. That's an ADR, not a DGQ:

This isn't a per-stakeholder ask — it's a platform commitment. Run /write-adr to capture it in docs/adr/, then link it from any related DGQ via related_adrs.

Don't inline an ADR scaffold — one skill, one artefact. If the user insists on a DGQ anyway, write it but note in ## Open follow-ups that it likely should be promoted to an ADR.

When understanding lands: write the DGQ

Write one file per decision at docs/requirements/<stakeholder>-<slug>.md, shaped exactly as references/dgq.md specifies — frontmatter and body. <stakeholder> is the asker kebab-cased; <slug> is a 2–4-word condensation of the decision. related_dgqs/related_adrs start [].

For a multi-decision ask: fully drill the chosen decision, and stub each sibling now — status: draft, the decision recorded one-line in ## Question(s), other fields TBD (linter-safe defaults sensitivity: internal, cadence: TBD), and a ## Open follow-ups note to resume. Tell the user the stubs are saved; don't abandon them silently.

After writing, run the bundled scripts/lint-dgq.sh from the consumer project root (or point it with DGQ_ROOT=<dir>) as a cheap structural check — best-effort: if a partial install dropped it, skip silently. Then:

• Print a one-line confirmation: Wrote … / status / action_change. Don't read the DGQ body back — they just answered it.
• If needs-follow-up: name the specific question to take to the stakeholder. Vague follow-ups rot; named ones get answered.
• If a sibling stub is queued: offer to drill the next one. If an ADR-moment was parked: remind once to run /write-adr for that topic.

Vocabulary

• Decision-Grade Question (DGQ). A stakeholder ask interrogated until it names the decision being made, the action that changes if the answer flips, the signals needed to answer it, and the governance/cadence/cost envelope it lives inside. Stage 0's deliverable; one file per decision.
• Action-change kill-switch. What behaves differently if the answer flips. If the honest answer is "nothing", the ask doesn't deserve a build. The soul above.
• Signal vs spec. The fuzzy felt need ("we need to understand churn") vs the concrete data request it resolves to ("monthly churn rate by acquisition channel, rolling 90-day window, excluding free-tier users").

Optional deeper reading

Not required to run this skill (a per-skill install works without them): the full repo worldview in CONTEXT.md and the lifecycle reference in docs/data-engineering-101.md.