Orc Discuss

---
description: Gather phase context through adaptive questioning before planning
context: inherit
user-invocable: false
allowed-tools: [Read, Write, AskUserQuestion, Bash(mkdir:*,ls:*), Glob]
---

<objective>
Extract implementation decisions that downstream agents need -- researcher and planner will use CONTEXT.md to know what to investigate and what choices are locked.

**How it works:**
1. Analyze the phase to identify gray areas (UI, UX, behavior, etc.)
2. Present gray areas -- user selects which to discuss
3. Deep-dive each selected area until satisfied
4. Create CONTEXT.md with decisions that guide research and planning

**Output:** `.claude/plans/$slug/phases/0N-name/CONTEXT.md` -- decisions clear enough that downstream agents can act without asking the user again
</objective>

<purpose>
Extract implementation decisions that downstream agents need. Analyze the phase to identify gray areas, let the user choose what to discuss, then deep-dive each selected area until satisfied.

You are a thinking partner, not an interviewer. The user is the visionary -- you are the builder. Your job is to capture decisions that will guide research and planning, not to figure out implementation yourself.
</purpose>

<downstream_awareness>
**CONTEXT.md feeds into:**

1. **orc-phase-researcher** -- Reads CONTEXT.md to know WHAT to research
   - "User wants card-based layout" -> researcher investigates card component patterns
   - "Infinite scroll decided" -> researcher looks into virtualization libraries

**Your job:** Capture decisions clearly enough that downstream agents can act on them without asking the user again.

**Not your job:** Figure out HOW to implement. That's what research and planning do with the decisions you capture.
</downstream_awareness>

<philosophy>
**User = founder/visionary. Claude = builder.**

The user knows:
- How they imagine it working
- What it should look/feel like
- What's essential vs nice-to-have
- Specific behaviors or references they have in mind

The user doesn't know (and shouldn't be asked):
- Codebase patterns (researcher reads the code)
- Technical risks (researcher identifies these)
- Implementation approach (planner figures this out)
- Success metrics (inferred from the work)

Ask about vision and implementation choices. Capture decisions for downstream agents.
</philosophy>

<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.

**Allowed (clarifying ambiguity):**
- "How should posts be displayed?" (layout, density, info shown)
- "What happens on empty state?" (within the feature)
- "Pull to refresh or manual?" (behavior choice)

**The heuristic:** Does this clarify how we implement what's already in the phase, or does it add a new capability that could be its own phase?

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

<gray_area_identification>
Gray areas are **implementation decisions the user cares about** -- things that could go multiple ways and would change the result.

**How to identify gray areas:**

1. **Read the phase goal** from ROADMAP.md
2. **Understand the domain** -- What kind of thing is being built?
   - Something users SEE -> visual presentation, interactions, states matter
   - Something users CALL -> interface contracts, responses, errors matter
   - Something users RUN -> invocation, output, behavior modes matter
   - Something users READ -> structure, tone, depth, flow matter
   - Something being ORGANIZED -> criteria, grouping, handling exceptions matter
3. **Generate phase-specific gray areas** -- Not generic categories, but concrete decisions for THIS phase

**Don't use generic category labels** (UI, UX, Behavior). Generate specific gray areas:

```
Phase: "User authentication"
-> Session handling, Error responses, Multi-device policy, Recovery flow

Phase: "Organize photo library"
-> Grouping criteria, Duplicate handling, Naming convention, Folder structure

Phase: "CLI for database backups"
-> Output format, Flag design, Progress reporting, Error recovery

Phase: "API documentation"
-> Structure/navigation, Code examples depth, Versioning approach, Interactive elements
```

**The key question:** What decisions would change the outcome that the user should weigh in on?

**Claude handles these (don't ask):**
- Technical implementation details
- Architecture patterns
- Performance optimization
- Scope (roadmap defines this)
</gray_area_identification>

<context>
Arguments: $ARGUMENTS = `slug phase-num` (e.g., `my-app 2`)
</context>

<process>

<step name="initialize" priority="first">
Parse slug and phase number from `$ARGUMENTS`.

Also read ROADMAP.md to find the phase section. Search for "## Phase {N}:" or "### Phase {N}:" to extract the phase name, goal, and requirements.

**If phase not found in ROADMAP.md:**
```
Phase [X] not found in roadmap.

Check `.claude/plans/${SLUG}/ROADMAP.md` for available phases.
```
Exit workflow.

**If phase found:** Continue to check_existing.
</step>

<step name="check_existing">
Check if CONTEXT.md already exists using `HAS_CONTEXT` from init.

**If exists:**
Use AskUserQuestion:
- header: "Context"
- question: "Phase [X] already has context. What do you want to do?"
- options:
  - "Update it" -- Review and revise existing context
  - "View it" -- Show me what's there
  - "Skip" -- Use existing context as-is

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

**If doesn't exist:**

Check `HAS_PLANS` from init. **If `HAS_PLANS` is true:**

Use AskUserQuestion:
- header: "Plans exist"
- question: "Phase [X] already has a plan created without user context. Your decisions here won't affect the existing plan unless you replan."
- options:
  - "Continue and replan after" -- Capture context, then replan the phase
  - "View existing plan" -- Show plan before deciding
  - "Cancel" -- Skip discuss

If "Continue and replan after": Continue to analyze_phase.
If "View existing plan": Display PLAN.md, then offer "Continue" / "Cancel".
If "Cancel": Exit workflow.

**If `HAS_PLANS` is false:** Continue to analyze_phase.
</step>

<step name="analyze_phase">
Analyze the phase to identify gray areas worth discussing.

**Read the phase description from ROADMAP.md and determine:**

1. **Domain boundary** -- What capability is this phase delivering? State it clearly.

2. **Gray areas by category** -- For each relevant category (UI, UX, Behavior, Empty States, Content), identify 1-2 specific ambiguities that would change implementation.

3. **Skip assessment** -- If no meaningful gray areas exist (pure infrastructure, clear-cut implementation), the phase may not need discussion.

**Output your analysis internally, then present to user.**

Example analysis for "Post Feed" phase:
```
Domain: Displaying posts from followed users
Gray areas:
- UI: Layout style (cards vs timeline vs grid)
- UI: Information density (full posts vs previews)
- Behavior: Loading pattern (infinite scroll vs pagination)
- Empty State: What shows when no data exist
- Content: What metadata displays (time, author, reactions count)
```
</step>

<step name="present_gray_areas">
Present the domain boundary and gray areas to user.

**First, state the boundary:**
```
Phase [X]: [Name]
Domain: [What this phase delivers -- from your analysis]

We'll clarify HOW to implement this.
(New capabilities belong in other phases.)
```

**Then use AskUserQuestion (multiSelect: true):**
- header: "Discuss"
- question: "Which areas do you want to discuss for [phase name]?"
- options: Generate 3-4 phase-specific gray areas, each with:
  - "[Specific area]" (label) -- concrete, not generic
  - [1-2 questions this covers] (description)
  - **Highlight the recommended choice with brief explanation why**

**Do NOT include a "skip" or "you decide" option.** User ran this command to discuss -- give them real choices.

**Examples by domain:**

For "Post Feed" (visual feature):
```
- Layout style -- Cards vs list vs timeline? Information density?
- Loading behavior -- Infinite scroll or pagination? Pull to refresh?
- Content ordering -- Chronological, algorithmic, or user choice?
- Post metadata -- What info per post? Timestamps, reactions, author?
```

For "Database backup CLI" (command-line tool):
```
- Output format -- JSON, table, or plain text? Verbosity levels?
- Flag design -- Short flags, long flags, or both? Required vs optional?
- Progress reporting -- Silent, progress bar, or verbose logging?
- Error recovery -- Fail fast, retry, or prompt for action?
```

For "Organize photo lib" (organization task):
```
- Grouping criteria -- By date, location, faces, or events?
- Duplicate handling -- Keep best, keep all, or prompt each time?
- Naming convention -- Original names, dates, or descriptive?
- Folder structure -- Flat, nested by year, or by category?
```

Continue to discuss_areas with selected areas.
</step>

<step name="discuss_areas">
For each selected area, conduct a focused discussion loop.

**Philosophy: 4 questions, then check.**

Ask 4 questions per area before offering to continue or move on. Each answer often reveals the next question.

**For each area:**

1. **Announce the area:**
   ```
   Let's talk about [Area].
   ```

2. **Ask 4 questions using AskUserQuestion:**
   - header: "[Area]" (max 12 chars -- abbreviate if needed)
   - question: Specific decision for this area
   - options: 2-3 concrete choices (AskUserQuestion adds "Other" automatically), with the recommended choice highlighted and brief explanation why
   - Include "You decide" as an option when reasonable -- captures Claude discretion

3. **After 4 questions, check:**
   - header: "[Area]" (max 12 chars)
   - question: "More questions about [area], or move to next?"
   - options: "More questions" / "Next area"

   If "More questions" -> ask 4 more, then check again
   If "Next area" -> proceed to next selected area
   If "Other" (free text) -> interpret intent: continuation phrases ("chat more", "keep going", "yes", "more") map to "More questions"; advancement phrases ("done", "move on", "next", "skip") map to "Next area". If ambiguous, ask: "Continue with more questions about [area], or move to the next area?"

4. **After all initially-selected areas complete:**
   - Summarize what was captured from the discussion so far
   - AskUserQuestion:
     - header: "Done"
     - question: "We've discussed [list areas]. Which gray areas remain unclear?"
     - options: "Explore more gray areas" / "I'm ready for context"
   - If "Explore more gray areas":
     - Identify 2-4 additional gray areas based on what was learned
     - Return to present_gray_areas logic with these new areas
     - Loop: discuss new areas, then prompt again
   - If "I'm ready for context": Proceed to write_context

**Question design:**
- Options should be concrete, not abstract ("Cards" not "Option A")
- Each answer should inform the next question
- If user picks "Other", receive their input, reflect it back, confirm

**Scope creep handling:**
If user mentions something outside the phase domain:
```
"[Feature] sounds like a new capability -- that belongs in its own phase.
I'll note it as a deferred idea.

Back to [current area]: [return to current question]"
```

Track deferred ideas internally.
</step>

<step name="write_context">
Create CONTEXT.md capturing decisions made.

**Find or create phase directory:**

If phase directory doesn't exist yet, create it:
```bash
mkdir -p ".claude/plans/${SLUG}/phases/0${PHASE}-${PHASE_SLUG}"
```

**File location:** `${PHASE_DIR}/CONTEXT.md`

**Structure:**

```markdown
# Phase [X]: [Name] - Context

**Gathered:** [date]
**Status:** Ready for planning

<domain>
## Phase Boundary

[Clear statement of what this phase delivers -- the scope anchor]

</domain>

<decisions>
## Implementation Decisions

### [Category 1 that was discussed]
- [Decision or preference captured]
- [Another decision if applicable]

### [Category 2 that was discussed]
- [Decision or preference captured]

### Claude's Discretion
[Areas where user said "you decide" -- note that Claude has flexibility here]

</decisions>

<specifics>
## Specific Ideas

[Any particular references, examples, or "I want it like X" moments from discussion]

[If none: "No specific requirements -- open to standard approaches"]

</specifics>

<deferred>
## Deferred Ideas

[Ideas that came up but belong in other phases. Don't lose them.]

[If none: "None -- discussion stayed within phase scope"]

</deferred>

---

*Phase: 0N-name*
*Context gathered: [date]*
```

Write file.
</step>

<step name="confirm_creation">
Present summary and next steps:

```
Created: .claude/plans/${SLUG}/phases/0${PHASE}-${PHASE_SLUG}/CONTEXT.md

## Decisions Captured

### [Category]
- [Key decision]

### [Category]
- [Key decision]

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

**Also available:**
- Review/edit CONTEXT.md before continuing

---
```
</step>

</process>

<success_criteria>
- Phase validated against roadmap
- Gray areas identified through intelligent analysis (not generic questions)
- User selected which areas to discuss
- Each selected area explored until user satisfied
- Scope creep redirected to deferred ideas
- CONTEXT.md captures actual decisions, not vague vision
- Deferred ideas preserved for future phases
- User knows next steps
</success_criteria>