AGENTS/.pi/gsd/workflows/discuss-phase-assumptions.md

Context (pre-injected)

Phase:

Phase Data:

State:

Extract implementation decisions that downstream agents need - using codebase-first analysis and assumption surfacing instead of interview-style questioning.

You are a thinking partner, not an interviewer. Analyze the codebase deeply, surface what you believe based on evidence, and ask the user only to correct what's wrong.

<available_agent_types> Valid GSD subagent types (use exact names - do not fall back to 'general-purpose'):

• gsd-assumptions-analyzer - Analyzes codebase to surface implementation assumptions </available_agent_types>

<downstream_awareness> CONTEXT.md feeds into:

1. gsd-phase-researcher - Reads CONTEXT.md to know WHAT to research
2. gsd-planner - Reads CONTEXT.md to know WHAT decisions are locked

Your job: Capture decisions clearly enough that downstream agents can act on them without asking the user again. Output is identical to discuss mode - same CONTEXT.md format. </downstream_awareness>

**Assumptions mode philosophy:**

The user is a visionary, not a codebase archaeologist. They need enough context to evaluate whether your assumptions match their intent - not to answer questions you could figure out by reading the code.

• Read the codebase FIRST, form opinions SECOND, ask ONLY about what's genuinely unclear
• Every assumption must cite evidence (file paths, patterns found)
• Every assumption must state consequences if wrong
• Minimize user interactions: ~2-4 corrections vs ~15-20 questions

<scope_guardrail> CRITICAL: No scope creep.

The phase boundary comes from ROADMAP.md and is FIXED. Discussion clarifies HOW to implement what's scoped, never WHETHER to add new capabilities.

When user suggests scope creep: "[Feature X] would be a new capability - that's its own phase. Want me to note it for the roadmap backlog? For now, let's focus on [phase domain]."

Capture the idea in "Deferred Ideas". Don't lose it, don't act on it. </scope_guardrail>

<answer_validation> IMPORTANT: Answer validation - After every AskUserQuestion call, check if the response is empty or whitespace-only. If so:

1. Retry the question once with the same parameters
2. If still empty, present the options as a plain-text numbered list

Text mode (workflow.text_mode: true in config or --text flag): When text mode is active, do not use AskUserQuestion at all. Present every question as a plain-text numbered list and ask the user to type their choice number. </answer_validation>

Phase number from argument (required).

Parse JSON for: commit_docs, phase_found, phase_dir, phase_number, phase_name, phase_slug, padded_phase, has_research, has_context, has_plans, has_verification, plan_count, roadmap_exists, planning_exists.

If phase_found is false:

Phase [X] not found in roadmap.

Use /gsd-progress to see available phases.

Exit workflow.

If phase_found is true: Continue to check_existing.

Auto mode - If --auto is present in ARGUMENTS:

• In check_existing: auto-select "Update it" (if context exists) or continue without prompting
• In present_assumptions: skip confirmation gate, proceed directly to write CONTEXT.md
• In correct_assumptions: auto-select recommended option for each correction
• Log each auto-selected choice inline
• After completion, auto-advance to plan-phase

Check if CONTEXT.md already exists using `has_context` from init.

ls ${phase_dir}/*-CONTEXT.md 2>/dev/null || true

If exists:

If --auto: Auto-select "Update it". Log: [auto] Context exists - updating with assumption-based analysis.

Otherwise: Use AskUserQuestion:

• header: "Context"
• question: "Phase [X] already has context. What do you want to do?"
• options:
  • "Update it" - Re-analyze codebase and refresh assumptions
  • "View it" - Show me what's there
  • "Skip" - Use existing context as-is

If "Update": Load existing, continue to load_prior_context If "View": Display CONTEXT.md, then offer update/skip If "Skip": Exit workflow

If doesn't exist:

Check has_plans and plan_count from init. If has_plans is true:

If --auto: Auto-select "Continue and replan after". Log: [auto] Plans exist - continuing with assumption analysis, will replan after.

Otherwise: Use AskUserQuestion:

• header: "Plans exist"
• question: "Phase [X] already has {plan_count} plan(s) created without user context. Your decisions here won't affect existing plans unless you replan."
• options:
  • "Continue and replan after"
  • "View existing plans"
  • "Cancel"

If "Continue and replan after": Continue to load_prior_context. If "View existing plans": Display plan files, then offer "Continue" / "Cancel". If "Cancel": Exit workflow.

If has_plans is false: Continue to load_prior_context.

Read project-level and prior phase context to avoid re-asking decided questions.

Step 1: Read project-level files

cat .planning/PROJECT.md 2>/dev/null || true
cat .planning/REQUIREMENTS.md 2>/dev/null || true
cat .planning/STATE.md 2>/dev/null || true

Extract from these:

• PROJECT.md - Vision, principles, non-negotiables, user preferences
• REQUIREMENTS.md - Acceptance criteria, constraints
• STATE.md - Current progress, any flags

Step 2: Read all prior CONTEXT.md files

(find .planning/phases -name "*-CONTEXT.md" 2>/dev/null || true) | sort

For each CONTEXT.md where phase number < current phase:

• Read the <decisions> section - these are locked preferences
• Read <specifics> - particular references or "I want it like X" moments
• Note patterns (e.g., "user consistently prefers minimal UI")

Step 3: Build internal <prior_decisions> context

Structure the extracted information for use in assumption generation.

If no prior context exists: Continue without - expected for early phases.

Check if any pending todos are relevant to this phase's scope.

TODO_MATCHES=$(pi-gsd-tools todo match-phase "${PHASE_NUMBER}")

Parse JSON for: todo_count, matches[].

If todo_count is 0: Skip silently.

If matches found: Present matched todos, use AskUserQuestion (multiSelect) to fold relevant ones into scope.

For selected (folded) todos: Store as <folded_todos> for CONTEXT.md <decisions> section. For unselected: Store as <reviewed_todos> for CONTEXT.md <deferred> section.

Auto mode (--auto): Fold all todos with score >= 0.4 automatically. Log the selection.

Lightweight scan of existing code to inform assumption generation.

Step 1: Check for existing codebase maps

ls .planning/codebase/*.md 2>/dev/null || true

If codebase maps exist: Read relevant ones (CONVENTIONS.md, STRUCTURE.md, STACK.md). Extract reusable components, patterns, integration points. Skip to Step 3.

Step 2: If no codebase maps, do targeted grep

Extract key terms from phase goal, search for related files.

grep -rl "{term1}\|{term2}" src/ app/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -10

Read the 3-5 most relevant files.

Step 3: Build internal <codebase_context>

Identify reusable assets, established patterns, integration points, and creative options. Store internally for use in deep_codebase_analysis.

Spawn a `gsd-assumptions-analyzer` agent to deeply analyze the codebase for this phase. This keeps raw file contents out of the main context window, protecting token budget.

Resolve calibration tier (if USER-PROFILE.md exists):

PROFILE_PATH=".pi/gsd/USER-PROFILE.md"

If file exists at PROFILE_PATH:

• Priority 1: Read config.json > preferences.vendor_philosophy (project-level override)
• Priority 2: Read USER-PROFILE.md Vendor Choices/Philosophy rating (global)
• Priority 3: Default to "standard"

Map to calibration tier:

• conservative OR thorough-evaluator → full_maturity (more alternatives, detailed evidence)
• opinionated → minimal_decisive (fewer alternatives, decisive recommendations)
• pragmatic-fast OR any other value → standard

If no USER-PROFILE.md: calibration_tier = "standard"

Spawn Explore subagent:

Task(subagent_type="gsd-assumptions-analyzer", prompt="""
Analyze the codebase for Phase {PHASE}: {phase_name}.

Phase goal: {roadmap_description}
Prior decisions: {prior_decisions_summary}
Codebase scout hints: {codebase_context_summary}
Calibration: {calibration_tier}

Your job:
1. Read ROADMAP.md phase {PHASE} description
2. Read any prior CONTEXT.md files from earlier phases
3. Glob/Grep for files related to: {phase_relevant_terms}
4. Read 5-15 most relevant source files
5. Return structured assumptions

## Output Format

Return EXACTLY this structure:

## Assumptions

### [Area Name] (e.g., "Technical Approach")
- **Assumption:** [Decision statement]
  - **Why this way:** [Evidence from codebase - cite file paths]
  - **If wrong:** [Concrete consequence of this being wrong]
  - **Confidence:** Confident | Likely | Unclear

(3-5 areas, calibrated by tier:
- full_maturity: 3-5 areas, 2-3 alternatives per Likely/Unclear item
- standard: 3-4 areas, 2 alternatives per Likely/Unclear item
- minimal_decisive: 2-3 areas, decisive single recommendation per item)

## Needs External Research
[Topics where codebase alone is insufficient - library version compatibility,
ecosystem best practices, etc. Leave empty if codebase provides enough evidence.]

${AGENT_SKILLS_ANALYZER}
""")

Parse the subagent's response. Extract:

• assumptions[] - each with area, statement, evidence, consequence, confidence
• needs_research[] - topics requiring external research (may be empty)

Initialize canonical refs accumulator:

• Source 1: Copy Canonical refs: from ROADMAP.md for this phase, expand to full paths
• Source 2: Check REQUIREMENTS.md and PROJECT.md for specs/ADRs referenced
• Source 3: Add any docs referenced in codebase scout results

**Skip if:** `needs_research` from deep_codebase_analysis is empty.

If research topics were flagged, spawn a general-purpose research agent:

Task(subagent_type="general-purpose", prompt="""
Research the following topics for Phase {PHASE}: {phase_name}.

Topics needing research:
{needs_research_content}

For each topic, return:
- **Finding:** [What you learned]
- **Source:** [URL or library docs reference]
- **Confidence impact:** [Which assumption this resolves and to what confidence level]

Use Context7 (resolve-library-id then query-docs) for library-specific questions.
Use WebSearch for ecosystem/best-practice questions.
""")

Merge findings back into assumptions:

• Update confidence levels where research resolves ambiguity
• Add source attribution to affected assumptions
• Store research findings for DISCUSSION-LOG.md

If no gaps flagged: Skip entirely. Most phases will skip this step.

Display all assumptions grouped by area with confidence badges.

Format for display:

## Phase {PHASE}: {phase_name} - Assumptions

Based on codebase analysis, here's what I'd go with:

### {Area Name}
{Confidence badge} **{Assumption statement}**
↳ Evidence: {file paths cited}
↳ If wrong: {consequence}

### {Area Name 2}
...

[If external research was done:]
### External Research Applied
- {Topic}: {Finding} (Source: {URL})

If --auto:

• If all assumptions are Confident or Likely: log assumptions, skip to write_context. Log: [auto] All assumptions Confident/Likely - proceeding to context capture.
• If any assumptions are Unclear: log a warning, auto-select recommended alternative for each Unclear item. Log: [auto] {N} Unclear assumptions auto-resolved with recommended defaults. Proceed to write_context.

Otherwise: Use AskUserQuestion:

• header: "Assumptions"
• question: "These all look right?"
• options:
  • "Yes, proceed" - Write CONTEXT.md with these assumptions as decisions
  • "Let me correct some" - Select which assumptions to change

If "Yes, proceed": Skip to write_context. If "Let me correct some": Continue to correct_assumptions.

The assumptions are already displayed above from present_assumptions.

Present a multiSelect where each option's label is the assumption statement and description is the "If wrong" consequence:

Use AskUserQuestion (multiSelect):

• header: "Corrections"
• question: "Which assumptions need correcting?"
• options: [one per assumption, label = assumption statement, description = "If wrong: {consequence}"]

For each selected correction, ask ONE focused question:

Use AskUserQuestion:

• header: "{Area Name}"
• question: "What should we do instead for: {assumption statement}?"
• options: [2-3 concrete alternatives describing user-visible outcomes, recommended option first]

Record each correction:

• Original assumption
• User's chosen alternative
• Reason (if provided via "Other" free text)

After all corrections processed, continue to write_context with updated assumptions.

Auto mode: Should not reach this step (--auto skips from present_assumptions).

Create phase directory if needed. Write CONTEXT.md using the standard 6-section format.

File: ${phase_dir}/${padded_phase}-CONTEXT.md

Map assumptions to CONTEXT.md sections:

• Assumptions → <decisions> (each assumption becomes a locked decision: D-01, D-02, etc.)
• Corrections → override the original assumption in <decisions>
• Areas where all assumptions were Confident → marked as locked decisions
• Areas with corrections → include user's chosen alternative as the decision
• Folded todos → included in <decisions> under "### Folded Todos"

# Phase {PHASE}: {phase_name} - Context

**Gathered:** {date} (assumptions mode)
**Status:** Ready for planning

<domain>
## Phase Boundary

{Domain boundary from ROADMAP.md - clear statement of scope anchor}
</domain>

<decisions>
## Implementation Decisions

### {Area Name 1}
- **D-01:** {Decision - from assumption or correction}
- **D-02:** {Decision}

### {Area Name 2}
- **D-03:** {Decision}

### the agent's Discretion
{Any assumptions where the user confirmed "you decide" or left as-is with Likely confidence}

### Folded Todos
{If any todos were folded into scope}
</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

{Accumulated canonical refs from analyze step - full relative paths}

[If no external specs: "No external specs - requirements fully captured in decisions above"]
</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
{From codebase scout + Explore subagent findings}

### Established Patterns
{Patterns that constrain/enable this phase}

### Integration Points
{Where new code connects to existing system}
</code_context>

<specifics>
## Specific Ideas

{Any particular references from corrections or user input}

[If none: "No specific requirements - open to standard approaches"]
</specifics>

<deferred>
## Deferred Ideas

{Ideas mentioned during corrections that are out of scope}

### Reviewed Todos (not folded)
{Todos reviewed but not folded - with reason}

[If none: "None - analysis stayed within phase scope"]
</deferred>

Write file.

Write audit trail of assumptions and corrections.

File: ${phase_dir}/${padded_phase}-DISCUSSION-LOG.md

# Phase {PHASE}: {phase_name} - Discussion Log (Assumptions Mode)

> **Audit trail only.** Do not use as input to planning, research, or execution agents.
> Decisions captured in CONTEXT.md - this log preserves the analysis.

**Date:** {ISO date}
**Phase:** {padded_phase}-{phase_name}
**Mode:** assumptions
**Areas analyzed:** {comma-separated area names}

## Assumptions Presented

### {Area Name}
| Assumption  | Confidence                 | Evidence     |
| ----------- | -------------------------- | ------------ |
| {Statement} | {Confident/Likely/Unclear} | {file paths} |

{Repeat for each area}

## Corrections Made

{If corrections were made:}

### {Area Name}
- **Original assumption:** {what the agent assumed}
- **User correction:** {what the user chose instead}
- **Reason:** {user's rationale, if provided}

{If no corrections: "No corrections - all assumptions confirmed."}

## Auto-Resolved

{If --auto and Unclear items existed:}
- {Assumption}: auto-selected {recommended option}

{If not applicable: omit this section}

## External Research

{If research was performed:}
- {Topic}: {Finding} (Source: {URL})

{If no research: omit this section}

Write file.

Commit phase context and discussion log:

pi-gsd-tools commit "docs(${padded_phase}): capture phase context (assumptions mode)" --files "${phase_dir}/${padded_phase}-CONTEXT.md" "${phase_dir}/${padded_phase}-DISCUSSION-LOG.md"

Confirm: "Committed: docs(${padded_phase}): capture phase context (assumptions mode)"

Update STATE.md with session info:

pi-gsd-tools state record-session \
  --stopped-at "Phase ${PHASE} context gathered (assumptions mode)" \
  --resume-file "${phase_dir}/${padded_phase}-CONTEXT.md"

Commit STATE.md:

pi-gsd-tools commit "docs(state): record phase ${PHASE} context session" --files .planning/STATE.md

Present summary and next steps:

Created: .planning/phases/${PADDED_PHASE}-${SLUG}/${PADDED_PHASE}-CONTEXT.md

## Decisions Captured (Assumptions Mode)

### {Area Name}
- {Key decision} (from assumption / corrected)

{Repeat per area}

[If corrections were made:]
## Corrections Applied
- {Area}: {original} → {corrected}

[If deferred ideas exist:]
## Noted for Later
- {Deferred idea} - future phase

---

## ▶ Next Up

**Phase ${PHASE}: {phase_name}** - {Goal from ROADMAP.md}

`/gsd-plan-phase ${PHASE}`

<sub>`/new` first → fresh context window</sub>

---

**Also available:**
- `/gsd-plan-phase ${PHASE} --skip-research` - plan without research
- `/gsd-ui-phase ${PHASE}` - generate UI design contract (if frontend work)
- Review/edit CONTEXT.md before continuing

---

Check for auto-advance trigger:

1. Parse --auto flag from $ARGUMENTS
2. Sync chain flag:

   if [[ ! "$ARGUMENTS" =~ --auto ]]; then
     pi-gsd-tools config-set workflow._auto_chain_active false 2>/dev/null
   fi
   

3. Read chain flag and user preference:

   AUTO_CHAIN=$(pi-gsd-tools config-get workflow._auto_chain_active 2>/dev/null || echo "false")
   AUTO_CFG=$(pi-gsd-tools config-get workflow.auto_advance 2>/dev/null || echo "false")
   

If --auto flag present AND AUTO_CHAIN is not true:

pi-gsd-tools config-set workflow._auto_chain_active true

If --auto flag present OR AUTO_CHAIN is true OR AUTO_CFG is true:

Display banner:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GSD ► AUTO-ADVANCING TO PLAN
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Context captured (assumptions mode). Launching plan-phase...

Launch: Skill(skill="gsd-plan-phase", args="${PHASE} --auto")

Handle return: PHASE COMPLETE / PLANNING COMPLETE / INCONCLUSIVE / GAPS FOUND (identical handling to discuss-phase.md auto_advance step)

If neither --auto nor config enabled: Route to confirm_creation step.

<success_criteria>

• Phase validated against roadmap
• Prior context loaded (no re-asking decided questions)
• Codebase deeply analyzed via Explore subagent (5-15 files read)
• Assumptions surfaced with evidence and confidence levels
• User confirmed or corrected assumptions (~2-4 interactions max)
• Scope creep redirected to deferred ideas
• CONTEXT.md captures actual decisions (identical format to discuss mode)
• CONTEXT.md includes canonical_refs with full file paths (MANDATORY)
• CONTEXT.md includes code_context from codebase analysis
• DISCUSSION-LOG.md records assumptions and corrections as audit trail
• STATE.md updated with session info
• User knows next steps </success_criteria>