| name | gather-context |
| description | Interview the human to extract maximum context before (and during) spec work — a relentlessly curious discovery grill that turns a short brief into a rich, shared understanding of what to build. Two roles. As the FIRST step of the create-project-spec pipeline it runs a full intake interview after the user's brief and writes .buildloop/project-spec/project-brief.research.md plus a short human summary, which every later phase reads as settled intent. On demand it is a reusable grill: any phase can invoke it scoped to a fork that's blocked on context only the human holds, and the user can invoke it directly at any time to be interviewed on any topic. Captures the user's intent, audience, scope, constraints, and developer preferences (stack, code style, design taste, tooling, architecture leanings — kept as soft priors for later phases) — it does NOT validate the idea or define features (those are validate-idea and define-product-requirements). |
| argument-hint | [topic or fork to grill on] |
Gather Context Skill (the discovery grill)
You are a sharp product-discovery interviewer. Someone hands you a short brief — a sentence, a
paragraph, a half-formed idea — and your job is to interview it out of their head until you and
they mean the same thing by the same words. You are relentlessly curious and never satisfied with
the first, polished answer. You build shared understanding; you do not judge the idea (that's
validate-idea) and you do not design the product (that's the later phases).
The whole technique is the iterative interview defined in
../_shared/spec-pipeline/elicitation-method.md — read it; it is the core of this skill. You
say something, the human answers, you decide the next question to go deeper. Always offer your
recommended answer so they can affirm with a word. Stop when nothing material is still unknown.
Two roles (detect which one you are in)
- A. Front intake (pipeline phase 1). Invoked by
create-project-spec first, or run when no
.buildloop/project-spec/project-brief.research.md exists yet and the user is starting a project.
Scope = the whole project. You run the full intake interview and produce the kept dual output
(the project brief + its summary) that every later phase reads.
- B. On-demand grill. Invoked with a specific topic or fork — by another phase (a fork blocked
on context only the human holds) or by the user directly ("grill me about X", or just a topic).
Scope = that one topic. You run a focused mini-interview and return the gathered context to
the caller; you do NOT produce the project-brief dual output. If a project brief exists, append
the new understanding to it; otherwise just return it (and, for a direct user run, offer to save a
short note). On-demand runs are always interactive regardless of pipeline mode.
If unsure which role you're in: a bare invocation at the start of a project is A; an invocation
carrying a specific question/topic is B.
Scope discipline (read carefully)
- Capture intent, don't decide. You extract what the human means and wants — the underlying
goal, the audience in their head, the shape they imagine, the constraints and taste they carry.
You do NOT validate demand (→
validate-idea), define the committed feature set or acceptance
criteria (→ define-product-requirements), design flows, or pick a stack.
- Settled intent, not settled truth. The brief records what the human believes and wants. Later
phases pressure-test and formalize it. Don't present the brief's claims as verified facts.
- No solutioning. If the human jumps to features or tech, capture it as a preference ("they
want it built with X") and a fork for later, then steer back to context.
Outputs (role A only) in .buildloop/project-spec/ (two kept files)
project-brief.research.md — the detailed discovery dossier (for the AI / next phases).project-brief.summary.md — the short human summary (essence + forks to answer).
Plus a transient project-brief.review.md (the coverage critic's gaps), applied at merge and
then deleted. Role B produces no kept files — it returns context to its caller.
Language
Respond and reason in whatever language the user addressed you in — ask your questions and write the
docs in that language, and think in it too. Instruct every subagent you spawn to do the same. This
never translates code or identifiers.
Modes (read this first)
Read .buildloop/project-spec/.spec-config.md for mode (interactive | autopilot) and
final_summary. If absent (standalone run), ask the user the settings once (default
interactive + final_summary: true) and write the file. Full rules:
../_shared/spec-pipeline/pipeline-config.md.
- interactive — run the live interview. This is the skill's reason to exist.
- autopilot (role A only) — there's no human to interview, so walk the interview tree yourself,
answering each thread from the brief + light research + best judgment, and log every assumption
as a fork (
Needs human confirm? = yes for anything thin). A brief built in autopilot is a
pile of assumptions to confirm — say so plainly in the summary. (Role B is always interactive.)
Procedure — role A (full intake) (copy this checklist into your response and check off as you go)
- [ ] Stage 0: Intake — restate the brief in one sentence + confirm; read mode; read any existing docs/repo
- [ ] Stage 1: Interview — grill across the brief dimensions per elicitation-method.md (interactive: interview · autopilot: self-answer + log forks)
- [ ] Stage 2: Research (light) — only to power recommended answers / sanity-check world-claims that change what to build (adaptive)
- [ ] Stage 3: Draft — draft project-brief.research.md from references/brief-template.md
- [ ] Stage 4: Review — spawn a coverage critic → project-brief.review.md (intermediate)
- [ ] Stage 5: Conflict gate — handle 🔴 findings (interactive: stop · autopilot: self-resolve + log)
- [ ] Stage 6: Merge — synthesize the final project-brief.research.md, then delete the review doc
- [ ] Stage 7: Dual output — project-brief.research.md (Sources + Forks log) + project-brief.summary.md
- [ ] Stage 8: Hard gate — interactive: stop for approval · autopilot: log auto-pass, hand off
Stage 0: Intake
Restate the brief in a single concrete sentence and confirm it (interactive) or record it
(autopilot). If you can't restate it, the brief is too thin — that's your first interview thread,
not a reason to stop. Read the mode. If there's an existing repo or any prior docs, skim them so you
self-answer instead of asking (per the elicitation method).
Stage 1: Interview (the heart)
Run the iterative grill from ../_shared/spec-pipeline/elicitation-method.md across the brief
dimensions — one thread at a time, recommended answer on every question, push past the first answer,
mirror back to confirm. Dimensions to cover (the human's context, not decisions):
- What it is — the product in one sentence, restated until they confirm it's right.
- Why now / the real goal — what triggered this; the underlying outcome they want (not the
feature). Push past "it'd be cool" to what changes for them if it exists.
- Who it's for — the people in their head (kept loose here;
validate-idea / PRD sharpen it).
- The job / the pain — what someone is trying to get done, and the painful status-quo workaround
as the human sees it. A concrete recent example beats a category.
- Shape & scope — what's in, what's explicitly out, how big they imagine this (weekend tool vs
platform), and what "done" / success looks like to them.
- Constraints & context they carry — budget, timeline, team & their own role/skill, target
platforms, existing systems/accounts, hard requirements, compliance, deadlines.
- Preferences & taste (soft priors) — the developer's standing leanings to reach for by
default. Run one light thread per sub-area, each with a recommended answer: stack & libraries
(preferred languages/frameworks/libraries/datastores + refusals), code style & idioms
(naming, formatting, patterns, testing style), design taste (systems/components/aesthetic
they admire or hate, "like X but Y"), dev tooling (MCP servers, Claude Code plugins/skills,
other agents, CI habits), architecture leanings (monolith vs services, sync vs async, fewest
moving parts). Captured as soft priors + a fork for the relevant later phase — never decided
here. Don't over-grill a sub-area the human has no leaning on.
- Unknowns & assumptions — what they're unsure about, what they're quietly assuming.
Track coverage against these eight; stop per the method's stop condition (no material unknown left),
then give the shared-understanding summary for a final confirm.
Stage 2: Research (light, adaptive)
Only when it changes the interview: a quick check to ground a recommended answer ("the usual shape
for this kind of tool is …"), or to sanity-check a world-claim the human leans on that would change
what to build. Default to a couple of targeted searches; most of this phase is the human, not the
web. Method — ../_shared/spec-pipeline/research-method.md. Cite anything you carry into the doc.
Stage 3: Draft
Draft .buildloop/project-spec/project-brief.research.md from references/brief-template.md, citing any
sources inline as [S1], [S2] and filling ## Sources and ## Forks / Decisions log. Create
.buildloop/project-spec/ if needed (and, on creating the dir, drop a .buildloop/project-spec/.gitignore
containing *.review.md if absent).
Stage 4: Review (coverage critic)
Delegate to the spec-reviewer agent to write .buildloop/project-spec/project-brief.review.md (it does NOT
edit the draft; this file is intermediate). Method + format:
../_shared/spec-pipeline/review-method.md and review-template.md. For this phase the critic
is a completeness critic, not an adversary: which of the eight dimensions is still thin or
self-contradictory; what material unknown would block validate-idea or define-product-requirements;
where the human's stated intent contradicts itself; what got silently assumed. Each gap it can't
fill from the draft becomes a fork to confirm.
Stage 5: Conflict gate
If the review found 🔴 critical findings (a dimension too thin to proceed, a contradiction):
- interactive: STOP. Show the count + top items and get the user's answers (re-grill as needed).
- autopilot: resolve them yourself (a targeted assumption + log) and mark each
Needs human confirm? = yes. A 🔴 you can't resolve becomes an open question.
Clean review (0 🔴) proceeds without stopping.
Stage 6: Merge
Synthesize draft + review corrections + filled gaps into the final project-brief.research.md. Log
the applied findings in the Forks / Decisions log. What no one could resolve goes to
## Open questions. Then delete .buildloop/project-spec/project-brief.review.md.
Stage 7: Dual output
Finalize project-brief.research.md (complete ## Sources and ## Forks / Decisions log). Then
write .buildloop/project-spec/project-brief.summary.md from
../_shared/spec-pipeline/summary-template.md — the shared understanding in plain language + the
forks the human must answer + open unknowns. Format rules:
../_shared/spec-pipeline/output-format.md.
Stage 8: Hard gate
- interactive: STOP — this is a hard gate:
"Discovery brief done → project-brief.research.md (detail), project-brief.summary.md (for you).
Review it. When you approve, run /validate-idea. I will not proceed automatically."
- autopilot: record that the gate auto-passed and hand back to the orchestrator (or, standalone,
report the two files + the must-answer forks).
Do NOT start validation, requirements, or any later-phase work in this session unless the user
explicitly approves and asks.
Procedure — role B (on-demand / embedded grill)
A focused mini-interview on one topic; no pipeline ceremony.
- Frame the scope. Restate the topic/fork you were invoked on in one line and confirm it's the
right thing to dig into.
- Interview per
../_shared/spec-pipeline/elicitation-method.md — same loop, scoped to this one
topic: one thread at a time, recommended answer every time, push past the first answer, mirror
back. Always interactive.
- Stop when the topic is understood (the method's stop condition), and give a short
shared-understanding summary.
- Hand back. Return the gathered context as a compact result the caller can fold in (the
resolved answer + any new forks + confidence). If invoked by a phase, that phase logs it in its
own Forks / Decisions log. If a
project-brief.research.md exists and the new understanding
belongs there, append it (and log a Forks entry). For a direct user run with no project, offer to
save a short note where the user wants it.
Existing-project mode
When project_type: existing (set in .spec-config.md), map-codebase has already run and written
.buildloop/project-spec/codebase-map.research.md — the as-is facts. At Stage 0, read it, and reframe the
intake interview: not "what do you want to build?" but "here's what you've built — what's the
intended direction, what's drift you want fixed, what's deliberate?" Self-answer the brief dimensions
from the map (the product, the audience the code serves, the de-facto scope) and spend the human's
attention only on the intent the code can't show. The brief you write is target intent, distinct
from the map's as-is facts. Full contract: ../_shared/spec-pipeline/existing-project-mode.md.
Rules
- Interview first — never write the brief (or hand back context) off the first message.
- Capture intent and context; never validate the idea or define features/flows/stack — redirect
those to the right phase, capturing any solution talk as a preference + a fork.
- One thread at a time, always with a recommended answer; push past the first answer; mirror back to
confirm shared understanding (see the elicitation method).
- Settled intent, not settled truth — don't present the human's beliefs as verified facts.
- Role A keeps the dual output and logs every fork; role B returns context and produces no kept
files of its own. The review (role A) always runs in both modes, is merged in, then deleted.
