From 7c60722b7196a7d18e20df85da3da3dd50965462 Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Fri, 16 Jan 2026 22:44:15 -0600 Subject: [PATCH] refactor(discuss-phase): domain-aware gray areas and deeper probing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- commands/gsd/discuss-phase.md | 39 +++--- get-shit-done/templates/context.md | 156 +++++++++++++++++++++-- get-shit-done/workflows/discuss-phase.md | 137 +++++++++++++------- 3 files changed, 260 insertions(+), 72 deletions(-) diff --git a/commands/gsd/discuss-phase.md b/commands/gsd/discuss-phase.md index 8beef2500..57706d461 100644 --- a/commands/gsd/discuss-phase.md +++ b/commands/gsd/discuss-phase.md @@ -35,10 +35,10 @@ Phase number: $ARGUMENTS (required) 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 diff --git a/get-shit-done/templates/context.md b/get-shit-done/templates/context.md index 2854f59b2..681eac564 100644 --- a/get-shit-done/templates/context.md +++ b/get-shit-done/templates/context.md @@ -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 ## 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 ``` + +**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 ## 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 @@ -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 @@ -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 + + +## Phase Boundary + +CLI command to backup database to local file or S3. Supports full and incremental backups. Restore command is a separate phase. + + + + +## 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 + + + + +## Specific Ideas + +- "I want it to feel like pg_dump — familiar to database people" +- Should work in CI pipelines (exit codes, no interactive prompts) + + + + +## Deferred Ideas + +- Scheduled backups — separate phase +- Backup rotation/retention — add to backlog + + + +--- + +*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 + + +## Phase Boundary + +Organize existing photo library into structured folders. Handle duplicates and apply consistent naming. Tagging and search are separate phases. + + + + +## 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 + + + + +## 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 + + + + +## Deferred Ideas + +- Face detection grouping — future phase +- Cloud sync — out of scope for now + + + +--- + +*Phase: 01-photo-organization* +*Context gathered: 2025-01-20* +``` + @@ -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. diff --git a/get-shit-done/workflows/discuss-phase.md b/get-shit-done/workflows/discuss-phase.md index 23eb60210..e24f985b8 100644 --- a/get-shit-done/workflows/discuss-phase.md +++ b/get-shit-done/workflows/discuss-phase.md @@ -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. - -Use these categories when analyzing a phase. Not all apply to every phase. + +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 - +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) + @@ -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. 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"