diff --git a/commands/gsd/new-project.md b/commands/gsd/new-project.md
index f30a20c70..d9fc373c2 100644
--- a/commands/gsd/new-project.md
+++ b/commands/gsd/new-project.md
@@ -12,7 +12,7 @@ allowed-tools:
Initialize a new project through comprehensive context gathering.
-This is the most leveraged moment in any project. Deep questioning here means better plans, better execution, better outcomes.
+This is the most leveraged moment in any project. Deep questioning here means better plans, better execution, better outcomes. The quality of PROJECT.md determines the quality of everything downstream.
Creates `.planning/` with PROJECT.md and config.json.
@@ -90,52 +90,48 @@ Exit command.
-**1. Open (FREEFORM — do NOT use AskUserQuestion):**
+**Open the conversation:**
-Ask inline: "What do you want to build?"
+Ask inline (freeform, NOT AskUserQuestion):
-Wait for their freeform response. This gives you the context needed to ask intelligent follow-up questions.
+"What do you want to build?"
-**2. Follow the thread (NOW use AskUserQuestion):**
+Wait for their response. This gives you the context needed to ask intelligent follow-up questions.
-Based on their response, use AskUserQuestion with options that probe what they mentioned:
-- header: "[Topic they mentioned]"
-- question: "You mentioned [X] — what would that look like?"
-- options: 2-3 interpretations + "Something else"
+**Follow the thread:**
-**3. Sharpen the core:**
+Based on what they said, ask follow-up questions that dig into their response. Use AskUserQuestion with options that probe what they mentioned — interpretations, clarifications, concrete examples.
-Use AskUserQuestion:
-- header: "Core"
-- question: "If you could only nail one thing, what would it be?"
-- options: Key aspects they've mentioned + "All equally important" + "Something else"
+Keep following threads. Each answer opens new threads to explore. Ask about:
+- What excited them
+- What problem sparked this
+- What they mean by vague terms
+- What it would actually look like
+- What's already decided
-**4. Find boundaries:**
+Consult `questioning.md` for techniques:
+- Challenge vagueness
+- Make abstract concrete
+- Surface assumptions
+- Find edges
+- Reveal motivation
-Use AskUserQuestion:
-- header: "Scope"
-- question: "What's explicitly NOT in v1?"
-- options: Things that might be tempting + "Nothing specific" + "Let me list them"
+**Check context (background, not out loud):**
-**5. Ground in reality:**
+As you go, mentally check the context checklist from `questioning.md`. If gaps remain, weave questions naturally. Don't suddenly switch to checklist mode.
-Use AskUserQuestion:
-- header: "Constraints"
-- question: "Any hard constraints?"
-- options: Relevant constraint types + "None" + "Yes, let me explain"
+**Decision gate:**
-**6. Decision gate:**
+When you could write a clear PROJECT.md, use AskUserQuestion:
-Use AskUserQuestion:
- header: "Ready?"
-- question: "Ready to create PROJECT.md, or explore more?"
-- options (ALL THREE REQUIRED):
- - "Create PROJECT.md" — Finalize and continue
- - "Ask more questions" — I'll dig deeper
- - "Let me add context" — You have more to share
+- question: "I think I understand what you're after. Ready to create PROJECT.md?"
+- options:
+ - "Create PROJECT.md" — Let's move forward
+ - "Keep exploring" — I want to share more / ask me more
+
+If "Keep exploring" — ask what they want to add, or identify gaps and probe naturally.
-If "Ask more questions" → check coverage gaps from `questioning.md` → return to step 2.
-If "Let me add context" → receive input via their response → return to step 2.
Loop until "Create PROJECT.md" selected.
@@ -303,24 +299,20 @@ Project initialized:
## ▶ Next Up
-**Research the domain** (recommended)
+Choose your path:
+
+**Option A: Research first** (recommended for new domains)
+Research the ecosystem before creating roadmap. Discovers standard stacks, expected features, architecture patterns, and common pitfalls.
`/gsd:research-project`
-Discovers standard stacks, expected features, architecture patterns, and common pitfalls. Then define requirements and create roadmap.
+**Option B: Create roadmap directly** (for familiar domains)
+Skip research if you know this domain well or have a clear spec.
+
+`/gsd:create-roadmap`
`/clear` first → fresh context window
-**Full flow:** research-project → define-requirements → create-roadmap
-
----
-
-**Skip research** (familiar domains only)
-
-If you know this domain well, skip directly to defining requirements:
-
-`/gsd:define-requirements`
-
---
```
@@ -337,7 +329,7 @@ If you know this domain well, skip directly to defining requirements:
-- [ ] Deep questioning completed (not rushed)
+- [ ] Deep questioning completed (not rushed, threads followed)
- [ ] PROJECT.md captures full context with evolutionary structure
- [ ] Requirements initialized as hypotheses (greenfield) or with inferred Validated (brownfield)
- [ ] Key Decisions table initialized
diff --git a/get-shit-done/references/questioning.md b/get-shit-done/references/questioning.md
index 185bcc8b7..3794e7c91 100644
--- a/get-shit-done/references/questioning.md
+++ b/get-shit-done/references/questioning.md
@@ -1,162 +1,166 @@
-The initialization phase is dream extraction, not requirements gathering. You're helping the user discover and articulate what they want to build. This isn't a contract negotiation — it's collaborative thinking.
+
+Project initialization is dream extraction, not requirements gathering. You're helping the user discover and articulate what they want to build. This isn't a contract negotiation — it's collaborative thinking.
+
**You are a thinking partner, not an interviewer.**
The user often has a fuzzy idea. Your job is to help them sharpen it. Ask questions that make them think "oh, I hadn't considered that" or "yes, that's exactly what I mean."
-Don't interrogate. Collaborate.
+Don't interrogate. Collaborate. Don't follow a script. Follow the thread.
+
-
-**ALL questions MUST use AskUserQuestion.**
+
-Never ask questions inline as plain text. Every exploration question uses the AskUserQuestion tool with thoughtful options that help the user articulate their vision.
+By the end of questioning, you need enough clarity to write a PROJECT.md that downstream phases can act on:
-This applies to:
-- Opening questions ("What do you want to build?")
-- Follow-up questions ("You mentioned X — what would that look like?")
-- Sharpening questions ("What's essential vs nice-to-have?")
-- Boundary questions ("What's out of scope?")
-- Decision gates ("Ready to proceed?")
+- **research-project** needs: what domain to research, what the user already knows, what unknowns exist
+- **create-roadmap** needs: clear enough vision to decompose into phases, what "done" looks like
+- **plan-phase** needs: specific requirements to break into tasks, context for implementation choices
+- **execute-phase** needs: success criteria to verify against, the "why" behind requirements
-The AskUserQuestion format helps users think by presenting concrete options to react to, rather than facing a blank text field.
-
+A vague PROJECT.md forces every downstream phase to guess. The cost compounds.
-
-**1. Open**
+
-Use AskUserQuestion:
-- header: "Vision"
-- question: "What do you want to build?"
-- options: Contextual starting points if available, otherwise broad categories + "Let me describe it"
+
-Let them respond. Then follow up based on what they said.
+**Start open.** Let them dump their mental model. Don't interrupt with structure.
-**2. Follow the thread**
+**Follow energy.** Whatever they emphasized, dig into that. What excited them? What problem sparked this?
-Whatever they said — dig into it. What excited them? What problem sparked this?
+**Challenge vagueness.** Never accept fuzzy answers. "Good" means what? "Users" means who? "Simple" means how?
-Use AskUserQuestion with options that probe what they mentioned:
-- header: "[Topic they mentioned]"
-- question: "You mentioned [X] — what would that actually look like?"
-- options: 2-3 interpretations of what they might mean + "Something else"
+**Make the abstract concrete.** "Walk me through using this." "What happens when X?" "What does that actually look like?"
-**3. Sharpen the core**
+**Surface assumptions.** "You haven't mentioned Y — is that intentional?" "When you say Z, do you mean A or B?"
-Help them distinguish the essential from the nice-to-have.
+**Find the edges.** "What would make this feel bloated?" "What's the simplest version that's still useful?"
-Use AskUserQuestion:
-- header: "Core"
-- question: "If you could only nail one thing, what would it be?"
-- options: Key features/aspects they've mentioned + "All equally important" + "Something else"
+**Reveal motivation.** "What prompted this?" "What are you doing today that this replaces?"
-**4. Find the boundaries**
+**Know when to stop.** When you could write a clear PROJECT.md that downstream phases can act on, offer to.
-What is this NOT? Explicit exclusions prevent scope creep later.
+
-Use AskUserQuestion:
-- header: "Scope"
-- question: "What's explicitly NOT in v1?"
-- options: Things that might be tempting to include + "Nothing specific" + "Let me list them"
+
-**5. Ground in reality**
+Use these as inspiration, not a checklist. Pick what's relevant to the thread.
-Only ask about constraints that actually exist. Don't invent concerns.
+**Motivation:**
+- "What prompted this?"
+- "What are you doing today that this replaces?"
+- "What would you do if this existed?"
+- "Why does this need to exist?"
-Use AskUserQuestion:
-- header: "Constraints"
-- question: "Any hard constraints?"
-- options: Common constraint types relevant to context + "None" + "Yes, let me explain"
-
+**Concreteness:**
+- "Walk me through using this"
+- "What happens when [edge case]?"
+- "You said X — what does that actually look like?"
+- "Give me an example"
-
-**BAD — Inline text questions:**
-- Asking "What is your target audience?" as plain text
-- Free-form "Tell me more about X" without options
-- Any question that leaves the user staring at a blank input
+**Boundaries:**
+- "What would make this feel bloated?"
+- "What's the simplest version that's still useful?"
+- "What would you cut if you had to ship tomorrow?"
-**GOOD — AskUserQuestion with options:**
-- header: "Audience"
-- question: "Who is this for?"
-- options: ["Just me", "My team", "Public users", "Let me describe"]
+**Assumptions:**
+- "You haven't mentioned Y — is that intentional?"
+- "When you say Z, do you mean A or B?"
+- "What are you assuming I already know?"
-**BAD — Corporate speak:**
-- "What are your success criteria?"
-- "What's your budget?"
-- "Have you done X before?" (irrelevant — Claude builds)
+**Reality:**
+- "What exists already that this touches?"
+- "What's already decided?" (tech, platform, integrations)
+- "What would make this impossible?"
-**GOOD — Concrete options that help them think:**
-- header: "Done"
-- question: "How will you know this is working?"
-- options: ["I'm using it daily", "Specific metric improves", "Replaces current workflow", "Let me describe"]
+**Success:**
+- "How will you know this is working?"
+- "What does done look like?"
+- "What would make this obviously successful?"
-**BAD — Checklist walking:**
-- Ask about audience → ask about constraints → ask about tech stack (regardless of what user said)
+
-**GOOD — Following threads with targeted options:**
-- User mentions frustration → AskUserQuestion with specific frustration interpretations as options → their selection reveals the core value prop
-
+
-
-When answers are vague, don't accept them. Probe with AskUserQuestion:
+Use AskUserQuestion to help users think by presenting concrete options to react to.
-**"Make it good"** →
-- header: "Good"
-- question: "What does 'good' mean here?"
-- options: ["Fast", "Beautiful", "Simple", "Reliable", "Let me describe"]
+**Good options:**
+- Interpretations of what they might mean
+- Specific examples to confirm or deny
+- Concrete choices that reveal priorities
-**"Users"** →
-- header: "Users"
-- question: "Which users?"
-- options: ["Just me", "My team", "Specific type of person", "Let me describe"]
+**Bad options:**
+- Generic categories ("Technical", "Business", "Other")
+- Leading options that presume an answer
+- Too many options (2-4 is ideal)
-**"It should be easy to use"** →
-- header: "Easy"
-- question: "Easy how?"
-- options: ["Fewer clicks", "No learning curve", "Works on mobile", "Let me describe"]
+**Example — vague answer:**
+User says "it should be fast"
-Specifics are everything. Vague in = vague out.
-
+- header: "Fast"
+- question: "Fast how?"
+- options: ["Sub-second response", "Handles large datasets", "Quick to build", "Let me explain"]
-
-By the end of questioning, you should understand:
+**Example — following a thread:**
+User mentions "frustrated with current tools"
-- [ ] What they're building (the thing)
-- [ ] Why it needs to exist (the motivation)
+- header: "Frustration"
+- question: "What specifically frustrates you?"
+- options: ["Too many clicks", "Missing features", "Unreliable", "Let me explain"]
+
+
+
+
+
+Use this as a **background checklist**, not a conversation structure. Check these boxes mentally as you go. If gaps remain near the end, weave questions naturally — don't suddenly switch to checklist mode.
+
+- [ ] What they're building (concrete enough to explain to a stranger)
+- [ ] Why it needs to exist (the problem or desire driving it)
- [ ] Who it's for (even if just themselves)
-- [ ] What "done" looks like (measurable outcome)
-- [ ] What's NOT in scope (boundaries)
-- [ ] Any real constraints (tech, timeline, compatibility)
-- [ ] What exists already (greenfield vs brownfield)
+- [ ] What "done" looks like (observable outcomes)
-If gaps remain, weave questions naturally into the conversation. Don't suddenly switch to checklist mode.
-
+That's it. Four things.
+
+**NOT your job to extract:**
+- Scope boundaries → research and roadmapping determine this
+- Constraints → emerge from implementation
+- Tech stack → research decides this
+- What they already know → irrelevant, Claude researches regardless
+
+If they volunteer this information, capture it. Don't ask for it.
+
+
-When you feel you understand the vision, use AskUserQuestion:
+
+When you could write a clear PROJECT.md, offer to proceed:
- header: "Ready?"
-- question: "Ready to create PROJECT.md, or explore more?"
-- options (ALL THREE REQUIRED):
- - "Create PROJECT.md" - Finalize and continue
- - "Ask more questions" - I'll dig into areas we haven't covered
- - "Let me add context" - You have more to share
+- question: "I think I understand what you're after. Ready to create PROJECT.md?"
+- options:
+ - "Create PROJECT.md" — Let's move forward
+ - "Keep exploring" — I want to share more / ask me more
-If "Ask more questions" → identify gaps from coverage check → ask naturally → return to gate.
+If "Keep exploring" — ask what they want to add or identify gaps and probe naturally.
Loop until "Create PROJECT.md" selected.
+
-- **Interrogation** - Firing questions without building on answers
-- **Checklist walking** - Going through domains regardless of conversation flow
-- **Corporate speak** - "What are your success criteria?" "Who are your stakeholders?"
-- **Rushing** - Minimizing questions to get to "the work"
-- **Assuming** - Filling gaps with assumptions instead of asking
-- **User skills** - NEVER ask about user's technical experience. Claude builds — user's skills are irrelevant.
-- **Premature constraints** - Asking about tech stack before understanding the idea
-- **Shallow acceptance** - Taking vague answers without probing for specifics
+
+- **Checklist walking** — Going through domains regardless of what they said
+- **Canned questions** — "What's your core value?" "What's out of scope?" regardless of context
+- **Corporate speak** — "What are your success criteria?" "Who are your stakeholders?"
+- **Interrogation** — Firing questions without building on answers
+- **Rushing** — Minimizing questions to get to "the work"
+- **Shallow acceptance** — Taking vague answers without probing
+- **Premature constraints** — Asking about tech stack before understanding the idea
+- **User skills** — NEVER ask about user's technical experience. Claude builds.
+
+