golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

fix: present new-project completion inline instead of as question

Browse Source 
Show slash commands inline so users can copy them to fresh context,
matching pattern used by other GSD commands.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
2025-12-16 07:38:42 -06:00
parent ba2704ed87
commit 3e8e5d537d
5 changed files with 206 additions and 472 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
commands/gsd/discuss-phase.md
View File

@@ -4,10 +4,11 @@ argument-hint: "[phase]"
---
<objective>
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
</objective>
<execution_context>
@@ -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
</process>
<success_criteria>
- 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)
</success_criteria>
- 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)
</success_criteria>

10
commands/gsd/new-project.md
View File

@@ -102,8 +102,9 @@ EOF
</step>
<step name="done">
```
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`
</step>
</process>

384
get-shit-done/templates/context.md
View File

@@ -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]
<phase_objectives>
## What This Phase Accomplishes
<vision>
## 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]
</vision>
**Clarifications:**
[Any clarified details about HOW the primary goal works - not additional features]
<essential>
## What Must Be Nailed
**Out of scope:**
[What this phase explicitly does NOT include - prevents scope creep]
</phase_objectives>
[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>
## Constraints
- [Essential thing 1]
- [Essential thing 2]
- [Essential thing 3 if applicable]
**Technical:**
[Library choices, platform requirements, compatibility needs, existing architecture patterns to follow]
</essential>
**Timeline:**
[Deadlines, urgency, sequencing dependencies]
<boundaries>
## 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]
</boundaries>
[If no constraints: "None - flexible approach"]
</constraints>
<specifics>
## Specific Ideas
<risks>
## 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"]
</risks>
<success_indicators>
## 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]
</success_indicators>
<codebase_context>
## 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]
</codebase_context>
<decisions_needed>
## 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"]
</decisions_needed>
</specifics>
<notes>
## 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"]
</notes>
---
*Phase: XX-name*
*Context gathered: [date]*
*Ready for planning: [yes/no]*
```
<good_examples>
```markdown
# Phase 3: Authentication - Context
# Phase 3: User Dashboard - Context
**Gathered:** 2025-01-20
**Status:** For planning
**Status:** Ready for research
<phase_objectives>
## What This Phase Accomplishes
<vision>
## 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
</vision>
**Out of scope:**
- OAuth providers (Google, GitHub) - deferred to Phase 4
- 2FA - deferred to Phase 5
- Role-based access control - deferred to Phase 6
</phase_objectives>
<essential>
## What Must Be Nailed
<constraints>
## 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)
</essential>
**Timeline:**
- Target completion: End of week 3
- Blocking Phase 4 (user profiles) and Phase 5 (product catalog)
<boundaries>
## 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)
</boundaries>
**Other:**
None
</constraints>
<specifics>
## Specific Ideas
<risks>
## 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.
</risks>
<success_indicators>
## 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
</success_indicators>
<codebase_context>
## 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)
</codebase_context>
<decisions_needed>
## 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)
</decisions_needed>
</specifics>
<notes>
## 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
</notes>
---
*Phase: 03-authentication*
*Phase: 03-user-dashboard*
*Context gathered: 2025-01-20*
*Ready for planning: yes*
```
</good_examples>
<guidelines>
**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
</guidelines>

21
get-shit-done/workflows/discuss-milestone.md
View File

@@ -1,5 +1,7 @@
<purpose>
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.
</purpose>
<process>
@@ -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.
</step>

226
get-shit-done/workflows/discuss-phase.md
View File

@@ -1,7 +1,27 @@
<purpose>
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.
</purpose>
<philosophy>
**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.
</philosophy>
<process>
<step name="validate_phase" priority="first">
@@ -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.
</step>
<step name="intake_gate">
<no_context_handler>
<step name="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.
</no_context_handler>
Let them talk. Don't interrupt with clarifying questions yet.
<context_analysis>
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.
</context_analysis>
Whatever they said — dig into it. What excites them? What matters most?
<initial_questions>
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.
</initial_questions>
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)
<gather_codebase_context>
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?"
</gather_codebase_context>
<decision_gate>
**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
</decision_gate>
</step>
<step name="write_context">
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):
- `<phase_objectives>`: From "what" analysis and questions
- `<constraints>`: From "how" analysis and questions
- `<risks>`: From "concerns" analysis and questions
- `<success_indicators>`: From "done when" analysis and questions
- `<codebase_context>`: From codebase questions and optional scanning
- `<decisions_needed>`: From questions that revealed choices to make
- `<notes>`: Any additional context gathered
- `<vision>`: How the user imagines this working
- `<essential>`: What must be nailed in this phase
- `<boundaries>`: What's explicitly out of scope
- `<specifics>`: Any particular look/feel/behavior mentioned
- `<notes>`: Any other context gathered
Do NOT populate with your own technical analysis. That comes during research/planning.
Write file.
</step>
<step name="confirm_creation">
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
```
</step>
@@ -257,9 +207,9 @@ What's next?
<success_criteria>
- 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)
</success_criteria>
- 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)
</success_criteria>