diff --git a/commands/gsd/discuss-phase.md b/commands/gsd/discuss-phase.md
index d173cdb80..bd97b5cea 100644
--- a/commands/gsd/discuss-phase.md
+++ b/commands/gsd/discuss-phase.md
@@ -4,10 +4,11 @@ argument-hint: "[phase]"
---
-Use adaptive questioning to gather comprehensive phase context before planning.
+Help the user articulate their vision for a phase through collaborative thinking.
-Purpose: Build deep understanding of objectives, constraints, risks, success indicators, and codebase state through structured intake flow. Creates CONTEXT.md file that informs high-quality planning.
-Output: {phase}-CONTEXT.md in phase directory with complete context documentation
+Purpose: Understand HOW the user imagines this phase working — what it looks like, what's essential, what's out of scope. You're a thinking partner helping them crystallize their vision, not an interviewer gathering technical requirements.
+
+Output: {phase}-CONTEXT.md capturing the user's vision for the phase
@@ -30,23 +31,27 @@ Phase number: $ARGUMENTS (required)
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:
- - Present initial context from roadmap
- - Analyze gaps in: objectives, constraints, risks, success indicators, codebase context
- - Ask 2-4 CLARIFYING questions (never suggest additions or expansions)
+ - 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)
- - Create CONTEXT.md using template
-5. Offer next steps (typically: plan the phase)
+ - Create CONTEXT.md capturing their vision
+5. Offer next steps (research or plan the phase)
-CRITICAL - NO SCOPE CREEP:
-- Questions clarify HOW to implement roadmap scope, not WHAT to add
-- Never ask "should we also..." or "do you want to add..."
-- If user adds scope, suggest updating ROADMAP first instead
+CRITICAL — 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)
+- DON'T ask about success metrics (too corporate)
+- DON'T interrogate about constraints they didn't mention
- Phase validated against roadmap
-- Context gathered through adaptive questioning
-- CONTEXT.md created in phase directory
-- User knows next steps (plan phase, review context, or done)
-
+- Vision gathered through collaborative thinking (not interrogation)
+- CONTEXT.md captures: how it works, what's essential, what's out of scope
+- User knows next steps (research or plan the phase)
+
diff --git a/commands/gsd/new-project.md b/commands/gsd/new-project.md
index eef77bdea..399a4650e 100644
--- a/commands/gsd/new-project.md
+++ b/commands/gsd/new-project.md
@@ -102,8 +102,9 @@ EOF
-```
+Present completion inline (not as a question):
+```
Project initialized:
- Project: .planning/PROJECT.md
@@ -114,11 +115,12 @@ What's next?
1. Research domain ecosystem (/gsd:research-project) - For niche/complex domains
2. Create roadmap (/gsd:create-roadmap) - Skip research, go straight to planning
3. Done for now
-
```
-If user selects "Research domain ecosystem" → invoke `/gsd:research-project`
-If user selects "Create roadmap" → invoke `/gsd:create-roadmap`
+Note: Commands are shown in the options above so the user can see what to run in a fresh context.
+
+**If user selects option 1:** invoke `/gsd:research-project`
+**If user selects option 2:** invoke `/gsd:create-roadmap`
diff --git a/get-shit-done/templates/context.md b/get-shit-done/templates/context.md
index cfb1909a6..56ad0ff35 100644
--- a/get-shit-done/templates/context.md
+++ b/get-shit-done/templates/context.md
@@ -1,8 +1,8 @@
# Phase Context Template
-Template for `.planning/phases/XX-name/{phase}-CONTEXT.md` - phase context documentation gathered before planning.
+Template for `.planning/phases/XX-name/{phase}-CONTEXT.md` - captures the user's vision for a phase.
-**Purpose:** Capture comprehensive context through adaptive questioning to inform high-quality planning.
+**Purpose:** Document how the user imagines the phase working. This is vision context, not technical analysis. Technical details come from research.
---
@@ -12,374 +12,150 @@ Template for `.planning/phases/XX-name/{phase}-CONTEXT.md` - phase context docum
# Phase [X]: [Name] - Context
**Gathered:** [date]
-**Status:** [For planning / Planning complete]
+**Status:** [Ready for research / Ready for planning]
-
-## What This Phase Accomplishes
+
+## How This Should Work
-[Clear, specific description of what this phase delivers]
+[User's description of how they imagine this phase working. What happens when someone uses it? What does it look/feel like? This is the "pitch" version, not the technical spec.]
-**Primary goal:**
-[Main objective from roadmap - what ships at the end]
+
-**Clarifications:**
-[Any clarified details about HOW the primary goal works - not additional features]
+
+## What Must Be Nailed
-**Out of scope:**
-[What this phase explicitly does NOT include - prevents scope creep]
-
+[The core of this phase. If we only get one thing right, what is it? What's the non-negotiable that makes this phase successful?]
-
-## Constraints
+- [Essential thing 1]
+- [Essential thing 2]
+- [Essential thing 3 if applicable]
-**Technical:**
-[Library choices, platform requirements, compatibility needs, existing architecture patterns to follow]
+
-**Timeline:**
-[Deadlines, urgency, sequencing dependencies]
+
+## What's Out of Scope
-**Resources:**
-[Budget limits, API rate limits, storage constraints, computational limits]
+[Explicit exclusions for this phase. What are we NOT building? Where does this phase end and the next begin?]
-**Dependencies:**
-[What must exist before this phase can start, external factors, waiting on other teams/services]
+- [Not doing X - that's Phase Y]
+- [Not including Z - deferred]
+- [Explicitly excluding W]
-**Other:**
-[Any other constraints affecting approach]
+
-[If no constraints: "None - flexible approach"]
-
+
+## Specific Ideas
-
-## Risks and Mitigation
+[Any particular things the user has in mind. References to existing products/features they like. Specific behaviors or interactions. "I want it to work like X" or "When you click Y, it should Z."]
-**Risk 1: [Risk description]**
-- **Likelihood:** [High / Medium / Low]
-- **Impact:** [High / Medium / Low]
-- **Mitigation:** [How to prevent or handle this]
+[If none: "No specific requirements - open to standard approaches"]
-**Risk 2: [Risk description]**
-- **Likelihood:** [High / Medium / Low]
-- **Impact:** [High / Medium / Low]
-- **Mitigation:** [How to prevent or handle this]
-
-[Continue for identified risks]
-
-[If no major risks: "No major risks identified - straightforward implementation expected"]
-
-
-
-## Success Indicators
-
-**How we'll know this phase is complete:**
-
-**Functional:**
-- [ ] [Specific feature works correctly]
-- [ ] [Tests pass for X functionality]
-- [ ] [Integration with Y system verified]
-
-**Quality:**
-- [ ] [Performance meets X threshold]
-- [ ] [No TypeScript errors]
-- [ ] [Test coverage >= X%]
-
-**Deployment:**
-- [ ] [Changes deployed to staging/production]
-- [ ] [Verification in live environment]
-
-**Documentation:**
-- [ ] [API documented]
-- [ ] [README updated]
-- [ ] [Migration guide if needed]
-
-**User-facing:**
-- [ ] [Visual verification complete]
-- [ ] [User testing passed]
-- [ ] [Acceptance criteria met]
-
-
-
-## Codebase State and Patterns
-
-**Current state:**
-[Fresh project / Established codebase / Legacy system / Mid-refactor]
-
-**Relevant files/systems:**
-- `path/to/relevant.ts` - [What this does and why it matters for this phase]
-- `path/to/another.ts` - [What this does and why it matters for this phase]
-
-**Patterns to follow:**
-[Existing conventions, architectural patterns, naming conventions, testing patterns]
-
-**External dependencies:**
-- [Library/service 1] - [How it's used, version constraints]
-- [Library/service 2] - [How it's used, version constraints]
-
-**Known issues to address:**
-[From ISSUES.md or prior phases - issues this phase should fix]
-
-**Prior decisions affecting this phase:**
-[From STATE.md - decisions from previous phases that constrain approach]
-
-
-
-## Decisions That Will Affect Implementation
-
-**Decision 1: [What needs deciding]**
-- **Context:** [Why this matters]
-- **Options:** [Brief list of approaches]
-- **When to decide:** [During planning / During task X / Before starting]
-
-**Decision 2: [What needs deciding]**
-- **Context:** [Why this matters]
-- **Options:** [Brief list of approaches]
-- **When to decide:** [During planning / During task X / Before starting]
-
-[If no decisions needed: "No open decisions - approach is clear from roadmap and context"]
-
+
## Additional Context
-[Any other relevant information gathered during context discussion]
+[Anything else captured during the discussion that doesn't fit above. User's priorities, concerns mentioned, relevant background.]
-[Questions asked during intake:]
-- Q: [Question asked]
-- A: [Answer received]
+[If none: "No additional notes"]
-[Clarifications:]
-- [Important points clarified during discussion]
-
-[References:]
-- [Links to relevant docs, prior art, examples]
-
-[If no additional notes: "No additional notes"]
---
*Phase: XX-name*
*Context gathered: [date]*
-*Ready for planning: [yes/no]*
```
```markdown
-# Phase 3: Authentication - Context
+# Phase 3: User Dashboard - Context
**Gathered:** 2025-01-20
-**Status:** For planning
+**Status:** Ready for research
-
-## What This Phase Accomplishes
+
+## How This Should Work
-Implement JWT-based authentication with secure session management.
+When users log in, they land on a dashboard that shows them everything important at a glance. I imagine it feeling calm and organized - not overwhelming like Jira or cluttered like Notion.
-**Primary goal:**
-Users can register, login, logout with JWT tokens stored in httpOnly cookies. Protected routes verify authentication.
+The main thing is seeing their active projects and what needs attention. Think of it like a "what should I work on today" view. It should feel personal, not like enterprise software.
-**Clarifications:**
-- Tokens stored as httpOnly cookies (not localStorage) per security requirements
-- "Protected routes" means API routes + page-level middleware redirects
-- Password reset included per roadmap scope
+
-**Out of scope:**
-- OAuth providers (Google, GitHub) - deferred to Phase 4
-- 2FA - deferred to Phase 5
-- Role-based access control - deferred to Phase 6
-
+
+## What Must Be Nailed
-
-## Constraints
+- **At-a-glance clarity** - Within 2 seconds of landing, user knows what needs their attention
+- **Personal feel** - This is YOUR dashboard, not a team dashboard. It should feel like opening your personal notebook.
-**Technical:**
-- Must use jose library (NOT jsonwebtoken - ESM compatibility requirement from Phase 1)
-- Must work in Edge runtime (Next.js middleware requirement)
-- Passwords must use bcrypt with minimum 10 salt rounds
-- Database already has User model from Phase 2 (extend, don't recreate)
+
-**Timeline:**
-- Target completion: End of week 3
-- Blocking Phase 4 (user profiles) and Phase 5 (product catalog)
+
+## What's Out of Scope
-**Resources:**
-- Email sending limited to 100/day on current SendGrid plan (affects password reset testing)
+- Team features (shared dashboards, permissions) - that's a future milestone
+- Analytics/reporting - just show what needs attention, not graphs
+- Customizable layouts - keep it simple, one good layout
+- Mobile optimization - desktop first for now
-**Dependencies:**
-- Phase 2 complete (database models)
-- Phase 1 complete (Next.js setup)
-- SendGrid API key obtained (checkpoint for email features)
+
-**Other:**
-None
-
+
+## Specific Ideas
-
-## Risks and Mitigation
+- I like how Linear's home screen highlights what's assigned to you without noise
+- Should show projects in a card format, not a list
+- Maybe a "Today" section at the top with urgent stuff
+- Dark mode is essential (already have this from Phase 2)
-**Risk 1: JWT token size causing cookie overflow**
-- **Likelihood:** Low
-- **Impact:** High (authentication breaks)
-- **Mitigation:** Keep JWT payload minimal (user ID only), store other data in database session table. Test with realistic tokens early.
-
-**Risk 2: Session timing causing UX issues**
-- **Likelihood:** Medium
-- **Impact:** Medium (user frustration)
-- **Mitigation:** Implement refresh token rotation, clear error messages on expiry, test user flows thoroughly.
-
-**Risk 3: Password reset token security**
-- **Likelihood:** Low
-- **Impact:** High (account takeover)
-- **Mitigation:** Use crypto.randomBytes(32) for tokens, short expiry (1 hour), single-use tokens, rate limiting on reset endpoint.
-
-
-
-## Success Indicators
-
-**How we'll know this phase is complete:**
-
-**Functional:**
-- [ ] User can register with email/password
-- [ ] User can login and receive JWT cookie
-- [ ] Protected routes redirect unauthenticated users
-- [ ] User can logout (cookie cleared)
-- [ ] Password reset flow works end-to-end
-
-**Quality:**
-- [ ] No passwords stored in plaintext
-- [ ] JWT tokens validated correctly
-- [ ] Tests pass for all auth endpoints
-- [ ] No TypeScript errors
-- [ ] Test coverage >= 80% for auth code
-
-**Deployment:**
-- [ ] Auth endpoints deployed to staging
-- [ ] Verified in staging environment
-- [ ] Production environment variables configured
-
-**Documentation:**
-- [ ] API endpoints documented
-- [ ] Authentication flow diagram added to README
-- [ ] Environment variables documented
-
-**User-facing:**
-- [ ] Login/logout flows tested manually
-- [ ] Error messages clear and helpful
-- [ ] Password reset tested with real email
-
-
-
-## Codebase State and Patterns
-
-**Current state:**
-Established codebase - Phase 2 complete with database models, Phase 1 has Next.js structure.
-
-**Relevant files/systems:**
-- `prisma/schema.prisma` - User model exists, need to add Session model
-- `src/app/api/*` - API route conventions established in Phase 2
-- `src/middleware.ts` - Next.js middleware file (create for protected routes)
-- `src/lib/db.ts` - Database connection helper from Phase 2
-
-**Patterns to follow:**
-- API routes return JSON with `{ success: boolean, data?: any, error?: string }`
-- Use Zod for request validation (established in Phase 2)
-- Database queries in try/catch with error logging
-- Tests colocated: `route.test.ts` next to `route.ts`
-
-**External dependencies:**
-- jose@5.2.0 - JWT library (decision from Phase 1)
-- bcrypt@5.1.1 - Password hashing
-- @sendgrid/mail - Email sending (need to add)
-- zod@3.22.4 - Validation (already installed)
-
-**Known issues to address:**
-- ISS-002 from Phase 2: Add rate limiting to API endpoints (include auth endpoints)
-
-**Prior decisions affecting this phase:**
-- Phase 1: Use jose for JWT (ESM-native, Edge-compatible)
-- Phase 2: API response format established (all endpoints must follow)
-- Phase 2: Zod validation pattern established (use for auth requests)
-
-
-
-## Decisions That Will Affect Implementation
-
-**Decision 1: Token expiry timing**
-- **Context:** Balance security (short expiry) vs UX (avoid frequent re-login)
-- **Options:** 15min access + 7day refresh / 1hr access + 30day refresh / 4hr access + 90day refresh
-- **When to decide:** During planning (affects implementation)
-
-**Decision 2: Remember me implementation**
-- **Context:** How to handle "remember me" checkbox on login
-- **Options:** Longer refresh token / Separate persistent token / Browser local storage flag
-- **When to decide:** During task breakdown (affects token strategy)
-
+
## Additional Context
-[Questions asked during intake:]
-- Q: Are there constraints I should know about?
-- A: Technical limitations - must use jose library, work in Edge runtime
+User mentioned they've abandoned several dashboards before because they felt too "corporate." The key differentiator is making it feel personal and calm.
-- Q: What could go wrong in this phase?
-- A: Security concerns - authentication vulnerabilities are critical
+Priority is clarity over features. Better to show less and make it obvious than show everything.
-- Q: Which files or systems should I examine for context?
-- A: Check prisma/schema.prisma for User model, src/app/api/* for API patterns
-
-[Clarifications:]
-- User stressed security is paramount - better to be overly cautious
-- Password reset is "nice to have" but not blocking for Phase 4
-- OAuth can wait - just email/password for now
-
-[References:]
-- OWASP Auth Cheatsheet: https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html
-- jose docs: https://github.com/panva/jose
---
-*Phase: 03-authentication*
+*Phase: 03-user-dashboard*
*Context gathered: 2025-01-20*
-*Ready for planning: yes*
```
-**When to create:**
-- Before planning a phase (via /gsd:discuss-phase command)
-- When roadmap description is too brief for quality planning
-- When phase involves complex decisions or risks
+**This template captures VISION, not technical specs.**
-**Structure:**
-- Use XML tags for section markers (matches GSD templates)
-- Five core sections: objectives, constraints, risks, success_indicators, codebase_context
-- Two supporting sections: decisions_needed, notes
-- All sections required (use "None" if truly not applicable)
+The user is the visionary. They know:
+- How they imagine it working
+- What it should feel like
+- What's essential vs nice-to-have
+- References to things they like
-**Content quality:**
-- Objectives: Specific and measurable (not "add auth" but "JWT auth with registration, login, logout, password reset")
-- Constraints: Technical/timeline/resource specifics (not "be fast" but "must work in Edge runtime")
-- Risks: Include likelihood, impact, mitigation (not just "might break")
-- Success indicators: Checklist format, specific criteria
-- Codebase context: Reference actual files and patterns
-- Decisions needed: Note when decision should be made (planning vs execution)
+The user does NOT know (and shouldn't be asked):
+- Codebase patterns (Claude reads the code)
+- Technical risks (Claude identifies during research)
+- Implementation constraints (Claude figures out)
+- Success metrics (Claude infers from the work)
-**Out of scope:**
-- Document what phase does NOT include (prevents scope creep)
-- Reference deferred items from roadmap
-- Note what's pushed to future phases
+**Content should read like:**
+- A founder describing their product vision
+- "When you use this, it should feel like..."
+- "The most important thing is..."
+- "I don't want it to be like X, I want it to feel like Y"
-**Integration with planning:**
-- CONTEXT.md loaded as @context reference in PLAN.md
-- Decisions inform task breakdown
-- Risks inform verification criteria
-- Success indicators become plan success criteria
-- Prior decisions become task action notes
+**Content should NOT read like:**
+- A technical specification
+- Risk assessment matrix
+- Success criteria checklist
+- Codebase analysis
**After creation:**
- File lives in phase directory: `.planning/phases/XX-name/{phase}-CONTEXT.md`
-- Referenced during planning workflow
-- Can be updated if context changes before planning
+- Research phase adds technical context (patterns, risks, constraints)
+- Planning phase creates executable tasks informed by both vision AND research
diff --git a/get-shit-done/workflows/discuss-milestone.md b/get-shit-done/workflows/discuss-milestone.md
index 85807c4c4..47a0e0f96 100644
--- a/get-shit-done/workflows/discuss-milestone.md
+++ b/get-shit-done/workflows/discuss-milestone.md
@@ -1,5 +1,7 @@
-Gather milestone context through adaptive questioning before creating a new milestone, using intake & decision gate pattern to build comprehensive understanding of goals, scope, lessons learned, and success criteria.
+Help the user figure out what they want to build in the next milestone through collaborative thinking.
+
+You're a thinking partner helping them crystallize their vision for what's next. Features first — everything else (scope, phases) derives from what they want to build.
@@ -91,17 +93,16 @@ Based on what you described:
**Theme suggestion:** v[X.Y] [Name]
```
-**Decision gate (MUST have all 3 options):**
+Use AskUserQuestion for decision gate:
-```
-Header: "Ready?"
-Options:
- 1. "Create milestone" - Proceed to /gsd:new-milestone
- 2. "Ask more questions" - Explore features or constraints further
- 3. "Let me add context" - I have more to share
-```
+- header: "Ready?"
+- question: "Ready to create the milestone, or explore more?"
+- options (ALL THREE REQUIRED):
+ - "Create milestone" - Proceed to /gsd:new-milestone
+ - "Ask more questions" - Help me think through this more
+ - "Let me add context" - I have more to share
-If "Ask more questions" → generate 2-3 contextual follow-ups → return to gate.
+If "Ask more questions" → dig into features they mentioned → return to gate.
If "Let me add context" → receive input, update synthesis → return to gate.
Loop until "Create milestone" selected.
diff --git a/get-shit-done/workflows/discuss-phase.md b/get-shit-done/workflows/discuss-phase.md
index cf97a33a5..6685114f4 100644
--- a/get-shit-done/workflows/discuss-phase.md
+++ b/get-shit-done/workflows/discuss-phase.md
@@ -1,7 +1,27 @@
-Gather phase context through adaptive questioning before planning, using intake & decision gate pattern to build comprehensive understanding of objectives, constraints, risks, success indicators, and codebase context.
+Gather phase context through collaborative thinking before planning. Help the user articulate their vision for how this phase should work, look, and feel.
+
+You are a thinking partner, not an interviewer. The user is the visionary — you are the builder. Your job is to understand their vision, not interrogate them about technical details you can figure out yourself.
+
+**User = founder/visionary. Claude = builder.**
+
+The user doesn't know (and shouldn't need to know):
+- Codebase patterns (you read the code)
+- Technical risks (you identify during research)
+- Implementation constraints (you figure those out)
+- Success metrics (you infer from the work)
+
+The user DOES know:
+- How they imagine it working
+- What it should look/feel like
+- What's essential vs nice-to-have
+- Any specific things they have in mind
+
+Ask about vision. Figure out implementation yourself.
+
+
@@ -22,7 +42,7 @@ fi
```
Error: Phase ${PHASE} not found in roadmap.
-Use /gsd:plan-phase to see available phases.
+Use /gsd:progress to see available phases.
```
Exit workflow.
@@ -43,7 +63,6 @@ Check if CONTEXT.md already exists for this phase:
```bash
ls .planning/phases/${PHASE}-*/CONTEXT.md 2>/dev/null
-# Also check for ${PHASE}-CONTEXT.md in phase directory
ls .planning/phases/${PHASE}-*/${PHASE}-CONTEXT.md 2>/dev/null
```
@@ -60,150 +79,83 @@ What's next?
Wait for user response.
-If "Update context": Load existing CONTEXT.md into intake flow (pre-populate known context)
+If "Update context": Load existing CONTEXT.md, continue to questioning
If "View existing": Read and display CONTEXT.md, then offer update/skip
If "Skip": Exit workflow
**If doesn't exist:**
-Continue to intake_gate.
+Continue to questioning.
-
-
-
+
Present initial context from roadmap:
```
Phase ${PHASE}: ${PHASE_NAME}
-Roadmap description: ${PHASE_DESCRIPTION}
+From the roadmap: ${PHASE_DESCRIPTION}
-I'll gather additional context through questions to ensure comprehensive planning.
+How do you imagine this working?
```
-Continue to context_analysis.
-
+Let them talk. Don't interrupt with clarifying questions yet.
-
-Analyze roadmap phase description and extract what's already provided:
+Then follow the conversation arc:
-**Objectives (what):** What this phase accomplishes
-**Constraints (how):** Technical/timeline limitations mentioned
-**Risks (concerns):** Potential issues mentioned
-**Success indicators (done when):** Completion criteria mentioned
-**Codebase context (dependencies):** Related systems mentioned
+**1. Follow the thread**
-Identify gaps where additional clarity would improve planning quality.
-
+Whatever they said — dig into it. What excites them? What matters most?
-
-Ask 2-4 questions based on actual gaps. Use AskUserQuestion with structured options.
+- "You mentioned [X] — what would that actually look like?"
+- "When you imagine using this, what happens?"
+- "Tell me more about [specific thing they mentioned]"
-CRITICAL: Questions must CLARIFY roadmap scope, not EXPAND it.
-- ASK: "How should X from the roadmap work?" (clarification)
-- ASK: "What constraints affect implementation?" (context)
-- ASK: "What existing code patterns should I follow?" (context)
-- NEVER ASK: "What else should we add?" (scope creep)
-- NEVER ASK: "Should we also include...?" (scope creep)
-- NEVER SUGGEST: Additional features beyond roadmap
+**2. Sharpen the core**
-**If objectives are vague:**
-header: "Phase Objectives"
-question: "The roadmap says [X]. How should this work specifically?"
-options:
+Help them distinguish essential from nice-to-have FOR THIS PHASE.
-- "Minimal implementation" - Core functionality only, simplest approach
-- "Standard approach" - Follow common patterns for this type of work
-- "Match existing patterns" - Do it the way similar things are done in codebase
-- "I'll clarify" - Let me explain what I have in mind
+- "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?"
-**If constraints are unclear:**
-header: "Constraints"
-question: "Are there constraints I should know about?"
-options:
+**3. Find boundaries**
-- "Technical limitations" - Library choices, platform requirements, compatibility
-- "Timeline pressure" - Specific deadline or urgency
-- "Dependencies" - Waiting on other phases or external factors
-- "Performance requirements" - Speed, scale, resource constraints
-- "No constraints" - Flexible approach
-- "Other" - Something else
+What is this phase NOT doing? Helps prevent scope creep during planning.
-**If risks are not mentioned:**
-header: "Risks"
-question: "What could go wrong in this phase?"
-options:
+- "What's explicitly out of scope for this phase?"
+- "Where does this phase end and the next begin?"
-- "Breaking changes" - Could affect existing functionality
-- "Integration complexity" - Coordinating multiple systems
-- "Unknown unknowns" - New territory, unclear best practices
-- "Performance impact" - Could slow things down
-- "Security concerns" - Authentication, data protection, vulnerabilities
-- "No major risks" - Straightforward implementation
-- "Other" - Something else
+**4. Capture specifics (only if they have them)**
-**If success indicators are unclear:**
-header: "Success Indicators"
-question: "How will we know this phase is complete?"
-options:
+If they have specific ideas about look/feel/behavior, capture them. Don't force this.
-- "Feature works" - Functional verification (tests pass, behavior correct)
-- "Deployed and live" - Actually running in production
-- "User-verified" - Visual/manual confirmation required
-- "Metrics hit target" - Performance, coverage, or quality thresholds
-- "Documentation complete" - Properly documented for future work
-- "Other" - Something else
+- "Any specific things you have in mind for how this should work?"
+- "Anything you've seen elsewhere that's close to what you want?"
-Skip questions where roadmap already provides clear answers.
-
+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)
-
-After initial questions, ask about codebase state:
+When you feel you understand their vision, use AskUserQuestion:
-header: "Codebase Context"
-question: "What should I know about the current codebase state?"
-options:
+- header: "Ready?"
+- question: "Ready to capture this context, or explore more?"
+- options (ALL THREE REQUIRED):
+ - "Create CONTEXT.md" - I've shared my vision
+ - "Ask more questions" - Help me think through this more
+ - "Let me add context" - I have more to share
-- "Fresh project" - Just starting, minimal existing code
-- "Established patterns" - Follow existing conventions and architecture
-- "Needs refactoring" - Current code has issues to address
-- "External dependencies" - Relies on specific libraries or services
-- "Legacy constraints" - Working with older code or technologies
-- "Not sure" - Help me figure this out
-- "Other" - Something else
-
-If "Established patterns" or "External dependencies" selected, ask follow-up:
-"Which files or systems should I examine for context?"
-
-If "Not sure" selected, offer to scan codebase:
-"I can scan the codebase to identify patterns and dependencies. Proceed?"
-
-
-
-**Decision gate (MUST have all 3 options):**
-
-```
-Header: "Context Gathering"
-Options:
- 1. "Create CONTEXT.md" - I have enough context, proceed
- 2. "Ask more questions" - I want to clarify how something should work
- 3. "Let me add context" - I have information that affects implementation
-```
-
-If "Ask more questions" → generate 2-3 CLARIFYING follow-ups (never suggest additions) → return to gate.
+If "Ask more questions" → dig into areas that seem unclear → return to gate.
If "Let me add context" → receive input → return to gate.
Loop until "Create CONTEXT.md" selected.
-
-SCOPE CREEP PREVENTION:
-- Follow-up questions must clarify roadmap items, not expand them
-- If user adds scope during "Let me add context", note it for ROADMAP update instead
-- CONTEXT.md documents HOW to implement roadmap scope, not WHAT additional things to add
-
-
-Create CONTEXT.md using accumulated context from intake flow.
+Create CONTEXT.md capturing the user's vision.
Use template from ~/.claude/get-shit-done/templates/context.md
@@ -214,41 +166,39 @@ Create it: `.planning/phases/${PHASE}-${SLUG}/`
Use roadmap phase name for slug (lowercase, hyphens).
-Populate template sections:
+Populate template sections with VISION context (not technical analysis):
-- ``: From "what" analysis and questions
-- ``: From "how" analysis and questions
-- ``: From "concerns" analysis and questions
-- ``: From "done when" analysis and questions
-- ``: From codebase questions and optional scanning
-- ``: From questions that revealed choices to make
-- ``: Any additional context gathered
+- ``: How the user imagines this working
+- ``: What must be nailed in this phase
+- ``: What's explicitly out of scope
+- ``: Any particular look/feel/behavior mentioned
+- ``: Any other context gathered
+
+Do NOT populate with your own technical analysis. That comes during research/planning.
Write file.
-Present CONTEXT.md to user:
+Present CONTEXT.md summary:
```
Created: .planning/phases/${PHASE}-${SLUG}/${PHASE}-CONTEXT.md
-## Phase Objectives
-[summary of objectives]
+## Vision
+[How they imagine it working]
-## Key Constraints
-[summary of constraints]
+## Essential
+[What must be nailed]
-## Risks to Watch
-[summary of risks]
-
-## Success Indicators
-[summary of success criteria]
+## Boundaries
+[What's out of scope]
What's next?
-1. Plan this phase (/gsd:plan-phase ${PHASE}) - CONTEXT.md will be loaded automatically
-2. Review/edit CONTEXT.md - Make adjustments before planning
-3. Done for now
+1. Research this phase (/gsd:research-phase ${PHASE}) - Investigate codebase, identify patterns and risks
+2. Plan this phase (/gsd:plan-phase ${PHASE}) - Skip research, go straight to planning
+3. Review/edit CONTEXT.md - Make adjustments
+4. Done for now
```
@@ -257,9 +207,9 @@ What's next?
-- Phase number validated against roadmap
-- Context gathered through adaptive questioning
-- All five core areas addressed: objectives, constraints, risks, success indicators, codebase context
-- CONTEXT.md created in phase directory using template
-- User knows next steps (typically: plan the phase)
-
+- Phase validated against roadmap
+- Vision gathered through collaborative thinking (not interrogation)
+- User's imagination captured: how it works, what's essential, what's out of scope
+- CONTEXT.md created in phase directory
+- User knows next steps (typically: research or plan the phase)
+