From 293447d6a6bb8ea4c90f6bcafe4c7a4b283d572f Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Tue, 16 Dec 2025 08:34:50 -0600 Subject: [PATCH] fix: mandate AskUserQuestion for all exploration questions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- commands/gsd/discuss-milestone.md | 12 ++- commands/gsd/discuss-phase.md | 16 +-- commands/gsd/new-project.md | 47 +++++++-- get-shit-done/references/questioning.md | 101 ++++++++++++++----- get-shit-done/workflows/discuss-milestone.md | 27 +++-- get-shit-done/workflows/discuss-phase.md | 64 ++++++------ 6 files changed, 180 insertions(+), 87 deletions(-) diff --git a/commands/gsd/discuss-milestone.md b/commands/gsd/discuss-milestone.md index 8bb4046b6..43da5c9e8 100644 --- 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 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.** diff --git a/commands/gsd/discuss-phase.md b/commands/gsd/discuss-phase.md index bd97b5cea..34427b8c5 100644 --- 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) diff --git a/commands/gsd/new-project.md b/commands/gsd/new-project.md index 399a4650e..db32d7531 100644 --- a/commands/gsd/new-project.md +++ b/commands/gsd/new-project.md @@ -43,18 +43,46 @@ Silent setup - execute before any user output: -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. diff --git a/get-shit-done/references/questioning.md b/get-shit-done/references/questioning.md index f8e46d627..185bcc8b7 100644 --- 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. - -**1. Open:** "What do you want to build?" + +**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. + + + +**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" -**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 -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. diff --git a/get-shit-done/workflows/discuss-milestone.md b/get-shit-done/workflows/discuss-milestone.md index 47a0e0f96..44a801006 100644 --- a/get-shit-done/workflows/discuss-milestone.md +++ b/get-shit-done/workflows/discuss-milestone.md @@ -49,6 +49,8 @@ Continue to 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. diff --git a/get-shit-done/workflows/discuss-phase.md b/get-shit-done/workflows/discuss-phase.md index 6685114f4..51ca59c52 100644 --- a/get-shit-done/workflows/discuss-phase.md +++ b/get-shit-done/workflows/discuss-phase.md @@ -88,60 +88,60 @@ Continue to 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.