---
name: forge:discuss
description: Capture project context and identify gray areas for a phase.
argument-hint: <phase-name>
allowed-tools:
  - Read
  - Write
  - Glob
  - Grep
  - Bash
  - AskUserQuestion
---

Extract implementation decisions for phase $ARGUMENTS that downstream agents (researcher, planner) need. The user is the visionary — you are the builder asking clarifying questions.

**Read first:** ROADMAP.md, REQUIREMENTS.md, state/STATE.json

**Steps:**

1. **Initialize** — Read ROADMAP.md, REQUIREMENTS.md, STATE.json. Validate the phase exists in the roadmap. Extract the phase goal and scope statement.

2. **Check existing** — If `.planning/phases/{phase}/CONTEXT.md` exists, use AskUserQuestion:
   - "Update existing context" — re-run discussion, merge new answers
   - "View current context" — display CONTEXT.md and stop
   - "Skip (use existing)" — proceed to offering next command

3. **Analyze phase for gray areas** — Based on the phase goal from ROADMAP.md, identify 3-4 **concrete** gray areas specific to THIS phase. Do NOT use generic categories (UI, UX, Behavior). Instead, identify real decisions:
   - For a visual feature → presentation choices, interaction patterns, layout decisions
   - For a CLI tool → flag design, output format, error messaging style
   - For an API → contract shape, auth strategy, error handling patterns
   - For infrastructure → deployment strategy, monitoring approach, scaling model
   - Each gray area should be a specific decision point, e.g. "Layout style", "Loading behavior", "Error recovery strategy"

4. **Present gray areas** — Use AskUserQuestion (multiSelect: true) with the 3-4 phase-specific gray areas. User picks which ones to discuss.

5. **Discuss selected areas** — For each selected area:
   - Ask up to 4 questions via AskUserQuestion with concrete options (not abstract)
   - Always include a "You decide (Claude's discretion)" option where reasonable — this captures areas where the planner has flexibility
   - After 4 questions, ask: "More questions about [area], or move to next?"
   - If user introduces scope creep (new capability beyond this phase), redirect: "That sounds like a new capability — I'll note it under Deferred Ideas for a future phase."

6. **Write CONTEXT.md** — Create `.planning/phases/{phase}/CONTEXT.md` with this structure:

   ```markdown
   # Phase [X]: [Name] - Context
   **Gathered:** [date]
   **Status:** Ready for planning

   ## Phase Boundary
   [Clear scope statement from ROADMAP.md — fixed, not negotiable]

   ## Implementation Decisions
   ### [Area 1 discussed]
   - [Specific decision made]
   - [Another decision]
   ### [Area 2 discussed]
   - [Specific decision made]

   ## Claude's Discretion
   [Areas where user said "you decide" — flexibility for planner/researcher]
   - [Area]: [What Claude can choose freely]

   ## Specific Ideas
   [Any references, inspirations, or "I want it like X" moments from discussion]

   ## Deferred Ideas
   [Scope creep captured here — explicitly out of scope for this phase]
   - [Idea]: [Why it was deferred]
   ```

7. **Commit and offer next step** — Offer `/forge:plan {phase}` to proceed.

**Downstream contract — who reads CONTEXT.md and how:**
- **Researcher** reads CONTEXT.md to know WHAT to research:
  - Locked decisions → research deeply, don't explore alternatives
  - Claude's discretion → research options and recommend best approach
  - Deferred ideas → ignore completely
- **Planner** reads CONTEXT.md to know WHAT choices are locked (implement exactly), flexible (can choose), and out of scope (must not include)