/discuss-phase

name: discuss-phase
description: Gather phase context through adaptive questioning before planning.
argument-hint: "<phase> [--all] [--auto]"
allowed-tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
  - AskUserQuestion
  - Task

Objective

Extract implementation decisions that downstream agents need — the `phase-planner` and `phase-researcher` will consume CONTEXT.md to know what to investigate and what choices are locked.

**How it works:** 1. Load prior context (PROJECT.md, REQUIREMENTS.md, STATE.md, prior CONTEXT.md files) 2. Scout codebase for reusable assets and patterns 3. Analyze phase — skip gray areas already decided in prior phases 4. Present remaining gray areas — user selects which to discuss 5. Deep-dive each selected area until satisfied 6. Create CONTEXT.md with decisions that guide research and planning

**Output:** `{phase_num}-CONTEXT.md` — decisions clear enough that downstream agents can act without asking the user again

Context

Phase number: $ARGUMENTS (required)

Process

**Step 1 — Load Context**

Read the following if they exist:

• `.planning/PROJECT.md` — project vision and constraints
• `.planning/REQUIREMENTS.md` — numbered requirements
• `.planning/ROADMAP.md` — phase structure and goals
• `.planning/STATE.md` — current project state
• `.planning/phases/XX-name/{phase_num}-CONTEXT.md` — prior discussion for this phase

**Step 2 — Scout Codebase**

Scan the codebase for patterns relevant to this phase:

• Existing utilities and helpers that could be reused
• Established patterns (naming, error handling, folder structure)
• Prior phase artifacts that this phase builds on

**Step 3 — Identify Gray Areas**

For the target phase, identify implementation decisions that are:

• Not yet locked in prior discussions
• Not obviously determined by the project tech stack
• Non-trivial enough to warrant explicit user decision

Skip areas already decided in prior CONTEXT.md files.

**Step 4 — Present and Discuss**

If `--all` flag: present all gray areas. Otherwise: ask the user which areas they want to discuss. Present them as a numbered list.

For each selected area:

• Explain the decision and its implications
• Present 2-3 concrete options with trade-offs
• Ask for the user's preference
• Ask clarifying follow-ups until the decision is unambiguous

**Step 5 — Handle Scope Creep**

If the user introduces ideas beyond the current phase scope:

• Acknowledge the idea
• Note it as a deferred idea in the CONTEXT.md output
• Redirect to the current phase scope

**Step 6 — Write CONTEXT.md**

Create `.planning/phases/{padded_phase}-{slug}/{phase_num}-CONTEXT.md` (create directory if needed):

# Phase [X]: [Name] — Context

**Discussed:** [date]

## Decisions

- **D-01: [Decision area]** — [What was decided]. Rationale: [why]
- **D-02: [Decision area]** — [What was decided]. Rationale: [why]

## Claude's Discretion

Areas where Claude has freedom to choose the best approach:
- [Area]: [Guidance or constraints]

## Deferred Ideas

Ideas mentioned but out of scope for this phase:
- [Idea]: [Why deferred, which phase it belongs to]

**Step 7 — Confirm Next Steps**

Tell the user: > "Context captured. Run `/plan-phase {phase}` to create the implementation plan."

Success Criteria

• [ ] Prior context loaded (no re-asking already-decided questions)
• [ ] Gray areas identified through codebase and requirement analysis
• [ ] User chose which areas to discuss
• [ ] Each selected area explored until decision is unambiguous
• [ ] Scope creep redirected to deferred ideas
• [ ] CONTEXT.md captures decisions, not vague vision
• [ ] User knows next step (`/plan-phase`)