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 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
@@ -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.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
|
||||
@@ -1,7 +1,11 @@
|
||||
<purpose>
|
||||
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.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
@@ -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
|
||||
|
||||
<domain>
|
||||
## Task Boundary
|
||||
|
||||
${DESCRIPTION}
|
||||
|
||||
</domain>
|
||||
|
||||
<decisions>
|
||||
## 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}
|
||||
|
||||
</decisions>
|
||||
|
||||
<specifics>
|
||||
## Specific Ideas
|
||||
|
||||
${any_specific_references_or_examples_from_discussion}
|
||||
|
||||
[If none: "No specific requirements — open to standard approaches"]
|
||||
|
||||
</specifics>
|
||||
```
|
||||
|
||||
Note: Quick task CONTEXT.md omits `<code_context>` and `<deferred>` 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(
|
||||
<files_to_read>
|
||||
- .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)' : ''}
|
||||
</files_to_read>
|
||||
|
||||
**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)'}
|
||||
</check_dimensions>
|
||||
|
||||
<expected_output>
|
||||
@@ -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
|
||||
<success_criteria>
|
||||
- [ ] 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
|
||||
|
||||
Reference in New Issue
Block a user