fix: mandate AskUserQuestion for all exploration questions

All questioning workflows now require AskUserQuestion tool for every question, not just decision gates. Inline text questions are prohibited. Updated: questioning.md, new-project.md, discuss-phase.md, discuss-milestone.md, and their workflow files. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-16 08:34:50 -06:00
parent e41d71c9a8
commit 293447d6a6
6 changed files with 180 additions and 87 deletions
--- a/commands/gsd/discuss-milestone.md
+++ b/commands/gsd/discuss-milestone.md
@@ -27,12 +27,14 @@ Output: Context gathered, then routes to /gsd:new-milestone
 <process>
 1. Verify previous milestone complete (or acknowledge active milestone)
 2. Present context from previous milestone (accomplishments, phase count)
-3. Follow discuss-milestone.md workflow:
-   - Ask: "What do you want to add, improve, or fix?"
-   - Dig into features they mention
-   - Help them articulate what matters most
-   - Present decision gate (ready / ask more / let me add context)
+3. Follow discuss-milestone.md workflow with **ALL questions using AskUserQuestion**:
+   - Use AskUserQuestion: "What do you want to add, improve, or fix?" with feature categories
+   - Use AskUserQuestion to dig into features they mention
+   - Use AskUserQuestion to help them articulate what matters most
+   - Use AskUserQuestion for decision gate (ready / ask more / let me add context)
 4. Hand off to /gsd:new-milestone with gathered context
+
+**CRITICAL: ALL questions use AskUserQuestion. Never ask inline text questions.**
 </process>

 <success_criteria>
--- a/commands/gsd/discuss-phase.md
+++ b/commands/gsd/discuss-phase.md
@@ -30,17 +30,19 @@ Phase number: $ARGUMENTS (required)
 1. Validate phase number argument (error if missing or invalid)
 2. Check if phase exists in roadmap
 3. Check if CONTEXT.md already exists (offer to update if yes)
-4. Follow discuss-phase.md workflow:
+4. Follow discuss-phase.md workflow with **ALL questions using AskUserQuestion**:
   - Present phase from roadmap
-   - Ask: "How do you imagine this working?"
-   - Follow their thread — dig into what excites them
-   - Sharpen the core — what's essential for THIS phase
-   - Find boundaries — what's explicitly out of scope
-   - Present decision gate (ready / ask more / let me add context)
+   - Use AskUserQuestion: "How do you imagine this working?" with interpretation options
+   - Use AskUserQuestion to follow their thread — probe what excites them
+   - Use AskUserQuestion to sharpen the core — what's essential for THIS phase
+   - Use AskUserQuestion to find boundaries — what's explicitly out of scope
+   - Use AskUserQuestion for decision gate (ready / ask more / let me add context)
   - Create CONTEXT.md capturing their vision
 5. Offer next steps (research or plan the phase)

-CRITICAL — User is the visionary, you are the builder:
+**CRITICAL: ALL questions use AskUserQuestion. Never ask inline text questions.**
+
+User is the visionary, you are the builder:
 - Ask about vision, feel, essential outcomes
 - DON'T ask about technical risks (you figure those out)
 - DON'T ask about codebase patterns (you read the code)
--- a/commands/gsd/new-project.md
+++ b/commands/gsd/new-project.md
@@ -43,18 +43,46 @@ Silent setup - execute before any user output:
 </step>

 <step name="question">
-Start: "What do you want to build?"
+**CRITICAL: ALL questions use AskUserQuestion. Never ask inline text questions.**

-Let them talk. Then follow the conversation arc from `questioning.md`:
-1. **Follow the thread** — dig into what they said, what excites them
-2. **Sharpen the core** — essential vs nice-to-have
-3. **Find boundaries** — what is it NOT
-4. **Ground in reality** — only constraints that actually exist
+**1. Open:**

-Be a thinking partner, not an interviewer. Help them discover and articulate their vision.
+Use AskUserQuestion:
+- header: "Vision"
+- question: "What do you want to build?"
+- options: Contextual options if you have any hints, otherwise ["New app/tool", "Feature for existing project", "Let me describe it"]

-When you feel you understand it, use AskUserQuestion:
+**2. Follow the thread:**

+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"
+
+**3. Sharpen the core:**
+
+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"
+
+**4. Find boundaries:**
+
+Use AskUserQuestion:
+- header: "Scope"
+- question: "What's explicitly NOT in v1?"
+- options: Things that might be tempting + "Nothing specific" + "Let me list them"
+
+**5. Ground in reality:**
+
+Use AskUserQuestion:
+- header: "Constraints"
+- question: "Any hard constraints?"
+- options: Relevant constraint types + "None" + "Yes, let me explain"
+
+**6. Decision gate:**
+
+Use AskUserQuestion:
 - header: "Ready?"
 - question: "Ready to create PROJECT.md, or explore more?"
 - options (ALL THREE REQUIRED):
@@ -62,7 +90,8 @@ When you feel you understand it, use AskUserQuestion:
  - "Ask more questions" - I'll dig deeper
  - "Let me add context" - You have more to share

-If "Ask more questions" → check coverage gaps from `questioning.md` → ask naturally → return to gate.
+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.
 </step>

--- a/get-shit-done/references/questioning.md
+++ b/get-shit-done/references/questioning.md
@@ -9,68 +9,113 @@ The user often has a fuzzy idea. Your job is to help them sharpen it. Ask questi
 Don't interrogate. Collaborate.
 </philosophy>

-<conversation_arc>
-**1. Open:** "What do you want to build?"
+<critical_rule>
+**ALL questions MUST use AskUserQuestion.**

-Let them talk. Don't interrupt with clarifying questions yet.
+Never ask questions inline as plain text. Every exploration question uses the AskUserQuestion tool with thoughtful options that help the user articulate their vision.
+
+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?")
+
+The AskUserQuestion format helps users think by presenting concrete options to react to, rather than facing a blank text field.
+</critical_rule>
+
+<conversation_arc>
+**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.

 **2. Follow the thread**

-Whatever they said — dig into it. What excited them? What problem sparked this? Follow their energy, not a checklist.
+Whatever they said — dig into it. What excited them? What problem sparked this?

-"You mentioned [X] — what would that actually look like?"
-"When you imagine using this, what happens?"
+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"

 **3. Sharpen the core**

 Help them distinguish the essential from the nice-to-have.

-"If you could only have one thing working, what would it be?"
-"What's the simplest version that would make you happy?"
+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"

 **4. Find the boundaries**

 What is this NOT? Explicit exclusions prevent scope creep later.

-"What are you specifically NOT building in v1?"
-"Where does this stop?"
+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**

 Only ask about constraints that actually exist. Don't invent concerns.

-"Any hard constraints — tech stack you must use, deadline, platform requirements?"
-"Does this need to work with anything existing?"
+Use AskUserQuestion:
+- header: "Constraints"
+- question: "Any hard constraints?"
+- options: Common constraint types relevant to context + "None" + "Yes, let me explain"
 </conversation_arc>

 <good_vs_bad>
-**BAD — Interrogation mode:**
- "What is your target audience?" (form field)
- "What are your success criteria?" (corporate speak)
- "Have you done X before?" (irrelevant — Claude builds)
- "What's your budget?" (asked before understanding the idea)
+**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

-**GOOD — Thinking partner mode:**
- "You said [X] — do you mean [interpretation A] or more like [interpretation B]?"
- "What would make you actually use this vs abandoning it?"
- "That's ambitious — what's the core that matters most?"
- "Is [Y] essential or just how you're imagining it currently?"
+**GOOD — AskUserQuestion with options:**
+- header: "Audience"
+- question: "Who is this for?"
+- options: ["Just me", "My team", "Public users", "Let me describe"]
+
+**BAD — Corporate speak:**
+- "What are your success criteria?"
+- "What's your budget?"
+- "Have you done X before?" (irrelevant — Claude builds)
+
+**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"]

 **BAD — Checklist walking:**
 - Ask about audience → ask about constraints → ask about tech stack (regardless of what user said)

-**GOOD — Following threads:**
- User mentions frustration with current tools → dig into what specifically frustrates them → that reveals the core value prop → then explore how they'd know it's working
+**GOOD — Following threads with targeted options:**
+- User mentions frustration → AskUserQuestion with specific frustration interpretations as options → their selection reveals the core value prop
 </good_vs_bad>

 <probing_techniques>
-When answers are vague, don't accept them. Probe:
+When answers are vague, don't accept them. Probe with AskUserQuestion:

-**"Make it good" → "What does good mean to you? Fast? Beautiful? Simple?"**
+**"Make it good"** →
+- header: "Good"
+- question: "What does 'good' mean here?"
+- options: ["Fast", "Beautiful", "Simple", "Reliable", "Let me describe"]

-**"Users" → "Which users? You? Your team? A specific type of person?"**
+**"Users"** →
+- header: "Users"
+- question: "Which users?"
+- options: ["Just me", "My team", "Specific type of person", "Let me describe"]

-**"It should be easy to use" → "Easy how? Fewer clicks? No learning curve? Works on mobile?"**
+**"It should be easy to use"** →
+- header: "Easy"
+- question: "Easy how?"
+- options: ["Fewer clicks", "No learning curve", "Works on mobile", "Let me describe"]

 Specifics are everything. Vague in = vague out.
 </probing_techniques>
--- a/get-shit-done/workflows/discuss-milestone.md
+++ b/get-shit-done/workflows/discuss-milestone.md
@@ -49,6 +49,8 @@ Continue to intake_gate.
 </step>

 <step name="intake_gate">
+**CRITICAL: ALL questions use AskUserQuestion. Never ask inline text questions.**
+
 The primary question is: **What do you want to build/add/fix?**

 Everything else (scope, priority, constraints) is secondary and derived from features.
@@ -58,11 +60,16 @@ Check for inputs:
 - Known gaps or pain points from usage
 - User's ideas for what's next

-Start: "What do you want to add, improve, or fix in this milestone?"
+**1. Open:**

-Then use AskUserQuestion to explore features. After each response, dig deeper with follow-up questions about specifics.
+Use AskUserQuestion:
+- header: "Next"
+- question: "What do you want to add, improve, or fix in this milestone?"
+- options: [Deferred issues from STATE.md if any] + ["New features", "Improvements to existing", "Bug fixes", "Let me describe"]

-**Feature exploration questions (use as needed):**
+**2. Explore features:**
+
+Based on their response, use AskUserQuestion:

 If they named specific features:
 - header: "Feature Details"
@@ -79,6 +86,13 @@ If they're not sure:
 - question: "What's been frustrating or missing?"
 - options: [Deferred issues from STATE.md + pain point categories + "Let me think about it"]

+**3. Prioritize:**
+
+Use AskUserQuestion:
+- header: "Priority"
+- question: "Which of these matters most?"
+- options: [Features they mentioned + "All equally important" + "Let me prioritize"]
+
 After gathering features, synthesize:

 ```
@@ -93,8 +107,9 @@ Based on what you described:
 **Theme suggestion:** v[X.Y] [Name]
 ```

-Use AskUserQuestion for decision gate:
+**4. Decision gate:**

+Use AskUserQuestion:
 - header: "Ready?"
 - question: "Ready to create the milestone, or explore more?"
 - options (ALL THREE REQUIRED):
@@ -102,8 +117,8 @@ Use AskUserQuestion for decision gate:
  - "Ask more questions" - Help me think through this more
  - "Let me add context" - I have more to share

-If "Ask more questions" → dig into features they mentioned → return to gate.
-If "Let me add context" → receive input, update synthesis → return to gate.
+If "Ask more questions" → return to step 2 with new probes.
+If "Let me add context" → receive input → return to step 2.
 Loop until "Create milestone" selected.
 </step>

--- a/get-shit-done/workflows/discuss-phase.md
+++ b/get-shit-done/workflows/discuss-phase.md
@@ -88,60 +88,60 @@ Continue to questioning.
 </step>

 <step name="questioning">
-Present initial context from roadmap:
+**CRITICAL: ALL questions use AskUserQuestion. Never ask inline text questions.**
+
+Present initial context from roadmap, then immediately use AskUserQuestion:

 ```
 Phase ${PHASE}: ${PHASE_NAME}

 From the roadmap: ${PHASE_DESCRIPTION}
-
-How do you imagine this working?
 ```

-Let them talk. Don't interrupt with clarifying questions yet.
+**1. Open:**

-Then follow the conversation arc:
+Use AskUserQuestion:
+- header: "Vision"
+- question: "How do you imagine this working?"
+- options: 2-3 interpretations based on the phase description + "Let me describe it"

-**1. Follow the thread**
+**2. Follow the thread:**

-Whatever they said — dig into it. What excites them? What matters most?
+Based on their response, use AskUserQuestion:
+- header: "[Topic they mentioned]"
+- question: "You mentioned [X] — what would that look like?"
+- options: 2-3 interpretations + "Something else"

- "You mentioned [X] — what would that actually look like?"
- "When you imagine using this, what happens?"
- "Tell me more about [specific thing they mentioned]"
+**3. Sharpen the core:**

-**2. Sharpen the core**
+Use AskUserQuestion:
+- header: "Essential"
+- question: "What's the most important part of this phase?"
+- options: Key aspects they've mentioned + "All equally important" + "Something else"

-Help them distinguish essential from nice-to-have FOR THIS PHASE.
+**4. Find boundaries:**

- "What's the most important part of this phase?"
- "If we could only nail one thing here, what would it be?"
- "Is [Y] essential for this phase or could it come later?"
+Use AskUserQuestion:
+- header: "Scope"
+- question: "What's explicitly out of scope for this phase?"
+- options: Things that might be tempting + "Nothing specific" + "Let me list them"

-**3. Find boundaries**
+**5. Capture specifics (optional):**

-What is this phase NOT doing? Helps prevent scope creep during planning.
-
- "What's explicitly out of scope for this phase?"
- "Where does this phase end and the next begin?"
-
-**4. Capture specifics (only if they have them)**
-
-If they have specific ideas about look/feel/behavior, capture them. Don't force this.
-
- "Any specific things you have in mind for how this should work?"
- "Anything you've seen elsewhere that's close to what you want?"
+If they seem to have specific ideas, use AskUserQuestion:
+- header: "Specifics"
+- question: "Any particular look/feel/behavior in mind?"
+- options: Contextual options based on what they've said + "No specifics" + "Let me describe"

 CRITICAL — What NOT to ask:
 - Technical risks (you figure those out)
 - Codebase patterns (you read the code)
 - Success metrics (too corporate)
 - Constraints they didn't mention (don't interrogate)
- "What could go wrong?" (your job to identify)
- "What existing code should I follow?" (you read the code)

-When you feel you understand their vision, use AskUserQuestion:
+**6. Decision gate:**

+Use AskUserQuestion:
 - header: "Ready?"
 - question: "Ready to capture this context, or explore more?"
 - options (ALL THREE REQUIRED):
@@ -149,8 +149,8 @@ When you feel you understand their vision, use AskUserQuestion:
  - "Ask more questions" - Help me think through this more
  - "Let me add context" - I have more to share

-If "Ask more questions" → dig into areas that seem unclear → return to gate.
-If "Let me add context" → receive input → return to gate.
+If "Ask more questions" → return to step 2 with new probes.
+If "Let me add context" → receive input → return to step 2.
 Loop until "Create CONTEXT.md" selected.
 </step>