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

refactor(discuss-phase): domain-aware gray areas and deeper probing

Browse Source 
- Remove useless "None — you decide" skip option
- Generate phase-specific gray areas based on domain analysis
  (UI features, CLI tools, APIs, organization tasks, etc.)
- Increase probing depth: 4 questions per area before check
- Make context.md categories flexible (emerge from discussion)
- Add CLI and organization examples to context template

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
2026-01-16 22:44:15 -06:00
parent 567bdd2e2c
commit 7c60722b71
3 changed files with 260 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -35,10 +35,10 @@ Phase number: $ARGUMENTS (required)
<process>
1. Validate phase number (error if missing or not in roadmap)
2. Check if CONTEXT.md exists (offer update/view/skip if yes)
3. **Analyze phase** — Identify domain boundary and gray areas by category
4. **Present gray areas** — Multi-select AskUserQuestion: which to discuss?
5. **Deep-dive each area** — Loop per area until user says "move on"
6. **Write CONTEXT.md** — Structured by decisions made
3. **Analyze phase** — Identify domain and generate phase-specific gray areas
4. **Present gray areas** — Multi-select: which to discuss? (NO skip option)
5. **Deep-dive each area** — 4 questions per area, then offer more/next
6. **Write CONTEXT.md** — Sections match areas discussed
7. Offer next steps (research or plan)
**CRITICAL: Scope guardrail**
@@ -47,18 +47,27 @@ Phase number: $ARGUMENTS (required)
- If user suggests new capabilities: "That's its own phase. I'll note it for later."
- Capture deferred ideas — don't lose them, don't act on them
**Gray area categories (use what's relevant):**
- **UI** — Layout, visual presentation, information density
- **UX** — Interactions, flows, feedback
- **Behavior** — Runtime behavior, state changes
- **Empty/Edge States** — What shows in unusual situations
- **Content** — What information is shown/hidden
**Domain-aware gray areas:**
Gray areas depend on what's being built. Analyze the phase goal:
- Something users SEE → layout, density, interactions, states
- Something users CALL → responses, errors, auth, versioning
- Something users RUN → output format, flags, modes, error handling
- Something users READ → structure, tone, depth, flow
- Something being ORGANIZED → criteria, grouping, naming, exceptions
**Do NOT ask about (downstream agents handle these):**
- Technical implementation (researcher investigates)
- Architecture choices (planner decides)
- Performance concerns (researcher/planner handle)
- Scope expansion (roadmap defines scope)
Generate 3-4 **phase-specific** gray areas, not generic categories.
**Probing depth:**
- Ask 4 questions per area before checking
- "More questions about [area], or move to next?"
- If more → ask 4 more, check again
- After all areas → "Ready to create context?"
**Do NOT ask about (Claude handles these):**
- Technical implementation
- Architecture choices
- Performance concerns
- Scope expansion
</process>
<success_criteria>

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

@@ -4,6 +4,8 @@ Template for `.planning/phases/XX-name/{phase}-CONTEXT.md` - captures implementa
**Purpose:** Document decisions that downstream agents need. Researcher uses this to know WHAT to investigate. Planner uses this to know WHAT choices are locked vs flexible.
**Key principle:** Categories are NOT predefined. They emerge from what was actually discussed for THIS phase. A CLI phase has CLI-relevant sections, a UI phase has UI-relevant sections.
**Downstream consumers:**
- `gsd-phase-researcher` — Reads decisions to focus research (e.g., "card layout" → research card component patterns)
- `gsd-planner` — Reads decisions to create specific tasks (e.g., "infinite scroll" → task includes virtualization)
@@ -28,11 +30,14 @@ Template for `.planning/phases/XX-name/{phase}-CONTEXT.md` - captures implementa
<decisions>
## Implementation Decisions
### [Category discussed, e.g., UI]
### [Area 1 that was discussed]
- [Specific decision made]
- [Another decision if applicable]
### [Category discussed, e.g., Behavior]
### [Area 2 that was discussed]
- [Specific decision made]
### [Area 3 that was discussed]
- [Specific decision made]
### Claude's Discretion
@@ -65,6 +70,9 @@ Template for `.planning/phases/XX-name/{phase}-CONTEXT.md` - captures implementa
```
<good_examples>
**Example 1: Visual feature (Post Feed)**
```markdown
# Phase 3: Post Feed - Context
@@ -81,18 +89,17 @@ Display posts from followed users in a scrollable feed. Users can view posts and
<decisions>
## Implementation Decisions
### UI
### Layout style
- Card-based layout, not timeline or list
- Each card shows: author avatar, name, timestamp, full post content, reaction counts
- Cards have subtle shadows, rounded corners — modern feel
- Show 10 posts initially, load more on scroll
### Behavior
### Loading behavior
- Infinite scroll, not pagination
- Pull-to-refresh on mobile
- New posts indicator at top ("3 new posts") rather than auto-inserting
### Empty State
### Empty state
- Friendly illustration + "Follow people to see posts here"
- Suggest 3-5 accounts to follow based on interests
@@ -108,7 +115,6 @@ Display posts from followed users in a scrollable feed. Users can view posts and
- "I like how Twitter shows the new posts indicator without disrupting your scroll position"
- Cards should feel like Linear's issue cards — clean, not cluttered
- No infinite scroll fatigue — maybe show "You're all caught up" after ~50 posts
</specifics>
@@ -116,7 +122,6 @@ Display posts from followed users in a scrollable feed. Users can view posts and
## Deferred Ideas
- Commenting on posts — Phase 5
- Reaction picker (not just counts) — Phase 5
- Bookmarking posts — add to backlog
</deferred>
@@ -126,6 +131,131 @@ Display posts from followed users in a scrollable feed. Users can view posts and
*Phase: 03-post-feed*
*Context gathered: 2025-01-20*
```
**Example 2: CLI tool (Database backup)**
```markdown
# Phase 2: Backup Command - Context
**Gathered:** 2025-01-20
**Status:** Ready for planning
<domain>
## Phase Boundary
CLI command to backup database to local file or S3. Supports full and incremental backups. Restore command is a separate phase.
</domain>
<decisions>
## Implementation Decisions
### Output format
- JSON for programmatic use, table format for humans
- Default to table, --json flag for JSON
- Verbose mode (-v) shows progress, silent by default
### Flag design
- Short flags for common options: -o (output), -v (verbose), -f (force)
- Long flags for clarity: --incremental, --compress, --encrypt
- Required: database connection string (positional or --db)
### Error recovery
- Retry 3 times on network failure, then fail with clear message
- --no-retry flag to fail fast
- Partial backups are deleted on failure (no corrupt files)
### Claude's Discretion
- Exact progress bar implementation
- Compression algorithm choice
- Temp file handling
</decisions>
<specifics>
## Specific Ideas
- "I want it to feel like pg_dump — familiar to database people"
- Should work in CI pipelines (exit codes, no interactive prompts)
</specifics>
<deferred>
## Deferred Ideas
- Scheduled backups — separate phase
- Backup rotation/retention — add to backlog
</deferred>
---
*Phase: 02-backup-command*
*Context gathered: 2025-01-20*
```
**Example 3: Organization task (Photo library)**
```markdown
# Phase 1: Photo Organization - Context
**Gathered:** 2025-01-20
**Status:** Ready for planning
<domain>
## Phase Boundary
Organize existing photo library into structured folders. Handle duplicates and apply consistent naming. Tagging and search are separate phases.
</domain>
<decisions>
## Implementation Decisions
### Grouping criteria
- Primary grouping by year, then by month
- Events detected by time clustering (photos within 2 hours = same event)
- Event folders named by date + location if available
### Duplicate handling
- Keep highest resolution version
- Move duplicates to _duplicates folder (don't delete)
- Log all duplicate decisions for review
### Naming convention
- Format: YYYY-MM-DD_HH-MM-SS_originalname.ext
- Preserve original filename as suffix for searchability
- Handle name collisions with incrementing suffix
### Claude's Discretion
- Exact clustering algorithm
- How to handle photos with no EXIF data
- Folder emoji usage
</decisions>
<specifics>
## Specific Ideas
- "I want to be able to find photos by roughly when they were taken"
- Don't delete anything — worst case, move to a review folder
</specifics>
<deferred>
## Deferred Ideas
- Face detection grouping — future phase
- Cloud sync — out of scope for now
</deferred>
---
*Phase: 01-photo-organization*
*Context gathered: 2025-01-20*
```
</good_examples>
<guidelines>
@@ -133,11 +263,11 @@ Display posts from followed users in a scrollable feed. Users can view posts and
The output should answer: "What does the researcher need to investigate? What choices are locked for the planner?"
**Good content:**
**Good content (concrete decisions):**
- "Card-based layout, not timeline"
- "Infinite scroll with pull-to-refresh"
- "Show 10 posts initially"
- "New posts indicator rather than auto-insert"
- "Retry 3 times on network failure, then fail"
- "Group by year, then by month"
- "JSON for programmatic use, table for humans"
**Bad content (too vague):**
- "Should feel modern and clean"
@@ -148,7 +278,7 @@ The output should answer: "What does the researcher need to investigate? What ch
**Sections explained:**
- **Domain** — The scope anchor. Copied/derived from ROADMAP.md. Fixed boundary.
- **Decisions** — Organized by category (UI, UX, Behavior, etc.). Actual choices made.
- **Decisions** — Organized by areas discussed (NOT predefined categories). Section headers come from the actual discussion — "Layout style", "Flag design", "Grouping criteria", etc.
- **Claude's Discretion** — Explicit acknowledgment of what Claude can decide during implementation.
- **Specifics** — Product references, examples, "like X but..." statements.
- **Deferred** — Ideas captured but explicitly out of scope. Prevents scope creep while preserving good ideas.

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

@@ -66,23 +66,44 @@ For now, let's focus on [phase domain]."
Capture the idea in a "Deferred Ideas" section. Don't lose it, don't act on it.
</scope_guardrail>
<gray_area_categories>
Use these categories when analyzing a phase. Not all apply to every phase.
<gray_area_identification>
Gray areas are **implementation decisions the user cares about** — things that could go multiple ways and would change the result.
| Category | What it clarifies | Example questions |
|----------|-------------------|-------------------|
| **UI** | Visual presentation, layout, information density | "Card-based or list view?" "What info shows on each item?" |
| **UX** | Interactions, flows, feedback | "How does loading work?" "What happens when you tap X?" |
| **Behavior** | Runtime behavior, state changes | "Auto-refresh or manual?" "How does pagination work?" |
| **Empty/Edge States** | What shows in unusual situations | "What appears with no data?" "How do errors display?" |
| **Content** | What information is shown/hidden | "Show timestamps?" "How much preview text?" |
**How to identify gray areas:**
**Categories to AVOID:**
- **Scope** — The roadmap defines scope, not discussion
- **Technical** — You figure out implementation
- **Architecture** — You decide patterns
- **Performance** — You handle optimization
</gray_area_categories>
1. **Read the phase goal** from ROADMAP.md
2. **Understand the domain** — What kind of thing is being built?
- Something users SEE → visual presentation, interactions, states matter
- Something users CALL → interface contracts, responses, errors matter
- Something users RUN → invocation, output, behavior modes matter
- Something users READ → structure, tone, depth, flow matter
- Something being ORGANIZED → criteria, grouping, handling exceptions matter
3. **Generate phase-specific gray areas** — Not generic categories, but concrete decisions for THIS phase
**Don't use generic category labels** (UI, UX, Behavior). Generate specific gray areas:
```
Phase: "User authentication"
→ Session handling, Error responses, Multi-device policy, Recovery flow
Phase: "Organize photo library"
→ Grouping criteria, Duplicate handling, Naming convention, Folder structure
Phase: "CLI for database backups"
→ Output format, Flag design, Progress reporting, Error recovery
Phase: "API documentation"
→ Structure/navigation, Code examples depth, Versioning approach, Interactive elements
```
**The key question:** What decisions would change the outcome that the user should weigh in on?
**Claude handles these (don't ask):**
- Technical implementation details
- Architecture patterns
- Performance optimization
- Scope (roadmap defines this)
</gray_area_identification>
<process>
@@ -169,47 +190,79 @@ We'll clarify HOW to implement this.
**Then use AskUserQuestion (multiSelect: true):**
- header: "Discuss"
- question: "Which areas do you want to discuss?"
- options: Generate 2-4 based on your analysis, each formatted as:
- "[Category] — [Specific gray area question]"
- Last option always: "None — you decide, proceed to planning"
- question: "Which areas do you want to discuss for [phase name]?"
- options: Generate 3-4 phase-specific gray areas, each formatted as:
- "[Specific area]" (label) — concrete, not generic
- [1-2 questions this covers] (description)
**Example options:**
**Do NOT include a "skip" or "you decide" option.** User ran this command to discuss — give them real choices.
**Examples by domain:**
For "Post Feed" (visual feature):
```
☐ UI — Card layout or timeline? How much of each post shows?
☐ Behavior — Infinite scroll or pagination? Pull to refresh?
☐ Empty state — What appears when there are no posts?
☐ None — You decide, proceed to planning
☐ Layout style — Cards vs list vs timeline? Information density?
☐ Loading behavior — Infinite scroll or pagination? Pull to refresh?
☐ Content ordering — Chronological, algorithmic, or user choice?
☐ Post metadata — What info per post? Timestamps, reactions, author?
```
If user selects "None": Skip to write_context with minimal context.
Otherwise: Continue to discuss_areas with selected areas.
For "Database backup CLI" (command-line tool):
```
☐ Output format — JSON, table, or plain text? Verbosity levels?
☐ Flag design — Short flags, long flags, or both? Required vs optional?
☐ Progress reporting — Silent, progress bar, or verbose logging?
☐ Error recovery — Fail fast, retry, or prompt for action?
```
For "Organize photo library" (organization task):
```
☐ Grouping criteria — By date, location, faces, or events?
☐ Duplicate handling — Keep best, keep all, or prompt each time?
☐ Naming convention — Original names, dates, or descriptive?
☐ Folder structure — Flat, nested by year, or by category?
```
Continue to discuss_areas with selected areas.
</step>
<step name="discuss_areas">
For each selected area, conduct a focused discussion loop.
**Philosophy: 4 questions, then check.**
Ask 4 questions per area before offering to continue or move on. Each answer often reveals the next question.
**For each area:**
1. **Announce the area:**
```
Let's talk about [Category].
Let's talk about [Area].
```
2. **Ask focused questions using AskUserQuestion:**
- header: "[Category]"
- question: Specific question about that gray area
- options: 2-3 concrete choices + "Let me describe" + "You decide"
2. **Ask 4 questions using AskUserQuestion:**
- header: "[Area]"
- question: Specific decision for this area
- options: 2-3 concrete choices (AskUserQuestion adds "Other" automatically)
- Include "You decide" as an option when reasonable — captures Claude discretion
3. **Follow up based on response:**
- If they chose an option: Capture it, ask if there's more about this area
- If "Let me describe": Receive their input, reflect it back, confirm understanding
- If "You decide": Note that Claude has discretion here
3. **After 4 questions, check:**
- header: "[Area]"
- question: "More questions about [area], or move to next?"
- options: "More questions" / "Next area"
4. **Loop control — Always offer:**
- "Ask more about [Category]" — Continue probing this area
- "Move to next area" — Done with this category
- "That's enough, create context" — Done with all discussion
If "More questions" → ask 4 more, then check again
If "Next area" → proceed to next selected area
4. **After all areas complete:**
- header: "Done"
- question: "That covers [list areas]. Ready to create context?"
- options: "Create context" / "Revisit an area"
**Question design:**
- Options should be concrete, not abstract ("Cards" not "Option A")
- Each answer should inform the next question
- If user picks "Other", receive their input, reflect it back, confirm
**Scope creep handling:**
If user mentions something outside the phase domain:
@@ -217,14 +270,10 @@ If user mentions something outside the phase domain:
"[Feature] sounds like a new capability — that belongs in its own phase.
I'll note it as a deferred idea.
Back to [current domain]: [return to current question]"
Back to [current area]: [return to current question]"
```
Track deferred ideas internally.
**Continue until:**
- User says "Move to next area" and all selected areas are done, OR
- User says "That's enough, create context"
</step>
<step name="write_context">