From a7c08bfbdce261314fa5d71c07da51f03cbb982e Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Tue, 3 Mar 2026 11:55:10 -0600 Subject: [PATCH] feat: add --discuss flag to /gsd:quick for lightweight pre-planning discussion (#861) Surfaces gray areas and captures user decisions in CONTEXT.md before planning, reducing hallucination risk for ambiguous quick tasks. Composable with --full for discussion + plan-checking + verification. Co-Authored-By: Claude Opus 4.6 --- commands/gsd/quick.md | 8 +- get-shit-done/workflows/quick.md | 155 ++++++++++++++++++++++++++++++- 2 files changed, 157 insertions(+), 6 deletions(-) diff --git a/commands/gsd/quick.md b/commands/gsd/quick.md index a8f8a75cd..2432e4872 100644 --- a/commands/gsd/quick.md +++ b/commands/gsd/quick.md @@ -1,7 +1,7 @@ --- name: gsd:quick description: Execute a quick task with GSD guarantees (atomic commits, state tracking) but skip optional agents -argument-hint: "[--full]" +argument-hint: "[--full] [--discuss]" allowed-tools: - Read - Write @@ -20,9 +20,13 @@ Quick mode is the same system with a shorter path: - Quick tasks live in `.planning/quick/` separate from planned phases - Updates STATE.md "Quick Tasks Completed" table (NOT ROADMAP.md) -**Default:** Skips research, plan-checker, verifier. Use when you know exactly what to do. +**Default:** Skips research, discussion, plan-checker, verifier. Use when you know exactly what to do. + +**`--discuss` flag:** Lightweight discussion phase before planning. Surfaces assumptions, clarifies gray areas, captures decisions in CONTEXT.md. Use when the task has ambiguity worth resolving upfront. **`--full` flag:** Enables plan-checking (max 2 iterations) and post-execution verification. Use when you want quality guarantees without full milestone ceremony. + +Flags are composable: `--discuss --full` gives discussion + plan-checking + verification. diff --git a/get-shit-done/workflows/quick.md b/get-shit-done/workflows/quick.md index 3c9bcaa82..d8d52aa36 100644 --- a/get-shit-done/workflows/quick.md +++ b/get-shit-done/workflows/quick.md @@ -1,7 +1,11 @@ Execute small, ad-hoc tasks with GSD guarantees (atomic commits, STATE.md tracking). Quick mode spawns gsd-planner (quick mode) + gsd-executor(s), tracks tasks in `.planning/quick/`, and updates STATE.md's "Quick Tasks Completed" table. +With `--discuss` flag: lightweight discussion phase before planning. Surfaces assumptions, clarifies gray areas, captures decisions in CONTEXT.md so the planner treats them as locked. + With `--full` flag: enables plan-checking (max 2 iterations) and post-execution verification for quality guarantees without full milestone ceremony. + +Flags are composable: `--discuss --full` gives discussion + plan-checking + verification. @@ -13,6 +17,7 @@ Read all files referenced by the invoking prompt's execution_context before star Parse `$ARGUMENTS` for: - `--full` flag → store as `$FULL_MODE` (true/false) +- `--discuss` flag → store as `$DISCUSS_MODE` (true/false) - Remaining text → use as `$DESCRIPTION` if non-empty If `$DESCRIPTION` is empty after parsing, prompt user interactively: @@ -29,7 +34,27 @@ Store response as `$DESCRIPTION`. If still empty, re-prompt: "Please provide a task description." -If `$FULL_MODE`: +Display banner based on active flags: + +If `$DISCUSS_MODE` and `$FULL_MODE`: +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► QUICK TASK (DISCUSS + FULL) +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +◆ Discussion + plan checking + verification enabled +``` + +If `$DISCUSS_MODE` only: +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► QUICK TASK (DISCUSS) +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +◆ Discussion phase enabled — surfacing gray areas before planning +``` + +If `$FULL_MODE` only: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► QUICK TASK (FULL MODE) @@ -81,6 +106,124 @@ Store `$QUICK_DIR` for use in orchestration. --- +**Step 4.5: Discussion phase (only when `$DISCUSS_MODE`)** + +Skip this step entirely if NOT `$DISCUSS_MODE`. + +Display banner: +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► DISCUSSING QUICK TASK +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +◆ Surfacing gray areas for: ${DESCRIPTION} +``` + +**4.5a. Identify gray areas** + +Analyze `$DESCRIPTION` to identify 2-4 gray areas — implementation decisions that would change the outcome and that the user should weigh in on. + +Use the domain-aware heuristic to generate phase-specific (not generic) gray areas: +- 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 + +Each gray area should be a concrete decision point, not a vague category. Example: "Loading behavior" not "UX". + +**4.5b. Present gray areas** + +``` +AskUserQuestion( + header: "Gray Areas", + question: "Which areas need clarification before planning?", + options: [ + { label: "${area_1}", description: "${why_it_matters_1}" }, + { label: "${area_2}", description: "${why_it_matters_2}" }, + { label: "${area_3}", description: "${why_it_matters_3}" }, + { label: "All clear", description: "Skip discussion — I know what I want" } + ], + multiSelect: true +) +``` + +If user selects "All clear" → skip to Step 5 (no CONTEXT.md written). + +**4.5c. Discuss selected areas** + +For each selected area, ask 1-2 focused questions via AskUserQuestion: + +``` +AskUserQuestion( + header: "${area_name}", + question: "${specific_question_about_this_area}", + options: [ + { label: "${concrete_choice_1}", description: "${what_this_means}" }, + { label: "${concrete_choice_2}", description: "${what_this_means}" }, + { label: "${concrete_choice_3}", description: "${what_this_means}" }, + { label: "You decide", description: "Claude's discretion" } + ], + multiSelect: false +) +``` + +Rules: +- Options must be concrete choices, not abstract categories +- Highlight recommended choice where you have a clear opinion +- If user selects "Other" with freeform text, switch to plain text follow-up (per questioning.md freeform rule) +- If user selects "You decide", capture as Claude's Discretion in CONTEXT.md +- Max 2 questions per area — this is lightweight, not a deep dive + +Collect all decisions into `$DECISIONS`. + +**4.5d. Write CONTEXT.md** + +Write `${QUICK_DIR}/${next_num}-CONTEXT.md` using the standard context template structure: + +```markdown +# Quick Task ${next_num}: ${DESCRIPTION} - Context + +**Gathered:** ${date} +**Status:** Ready for planning + + +## Task Boundary + +${DESCRIPTION} + + + + +## Implementation Decisions + +### ${area_1_name} +- ${decision_from_discussion} + +### ${area_2_name} +- ${decision_from_discussion} + +### Claude's Discretion +${areas_where_user_said_you_decide_or_areas_not_discussed} + + + + +## Specific Ideas + +${any_specific_references_or_examples_from_discussion} + +[If none: "No specific requirements — open to standard approaches"] + + +``` + +Note: Quick task CONTEXT.md omits `` and `` sections (no codebase scouting, no phase scope to defer to). Keep it lean. + +Report: `Context captured: ${QUICK_DIR}/${next_num}-CONTEXT.md` + +--- + **Step 5: Spawn planner (quick mode)** **If `$FULL_MODE`:** Use `quick-full` mode with stricter constraints. @@ -99,6 +242,7 @@ Task( - .planning/STATE.md (Project State) - ./CLAUDE.md (if exists — follow project-specific guidelines) +${DISCUSS_MODE ? '- ' + QUICK_DIR + '/' + next_num + '-CONTEXT.md (User decisions — locked, do not revisit)' : ''} **Project skills:** Check .claude/skills/ or .agents/skills/ directory (if either exists) — read SKILL.md files, plans should account for project skill rules @@ -168,7 +312,8 @@ Checker prompt: - Scope sanity: Is this appropriately sized for a quick task (1-3 tasks)? - must_haves derivation: Are must_haves traceable to the task description? -Skip: context compliance (no CONTEXT.md), cross-plan deps (single plan), ROADMAP alignment +Skip: cross-plan deps (single plan), ROADMAP alignment +${DISCUSS_MODE ? '- Context compliance: Does the plan honor locked decisions from CONTEXT.md?' : '- Skip: context compliance (no CONTEXT.md)'} @@ -389,6 +534,7 @@ Build file list: - `${QUICK_DIR}/${next_num}-PLAN.md` - `${QUICK_DIR}/${next_num}-SUMMARY.md` - `.planning/STATE.md` +- If `$DISCUSS_MODE` and context file exists: `${QUICK_DIR}/${next_num}-CONTEXT.md` - If `$FULL_MODE` and verification file exists: `${QUICK_DIR}/${next_num}-VERIFICATION.md` ```bash @@ -440,11 +586,12 @@ Ready for next task: /gsd:quick - [ ] ROADMAP.md validation passes - [ ] User provides task description -- [ ] `--full` flag parsed from arguments when present +- [ ] `--full` and `--discuss` flags parsed from arguments when present - [ ] Slug generated (lowercase, hyphens, max 40 chars) - [ ] Next number calculated (001, 002, 003...) - [ ] Directory created at `.planning/quick/NNN-slug/` -- [ ] `${next_num}-PLAN.md` created by planner +- [ ] (--discuss) Gray areas identified and presented, decisions captured in `${next_num}-CONTEXT.md` +- [ ] `${next_num}-PLAN.md` created by planner (honors CONTEXT.md decisions when --discuss) - [ ] (--full) Plan checker validates plan, revision loop capped at 2 - [ ] `${next_num}-SUMMARY.md` created by executor - [ ] (--full) `${next_num}-VERIFICATION.md` created by verifier