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. **context.md feeds into:** 1. **pan-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 2. **pan-planner** — Reads context.md to know WHAT decisions are locked - "Pull-to-refresh on mobile" → planner includes that in task specs - "Claude's Discretion: loading skeleton" → planner can decide approach **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. **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. **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) **Not allowed (scope creep):** - "Should we also add comments?" (new capability) - "What about search/filtering?" (new capability) - "Maybe include bookmarking?" (new capability) **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? **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 a "Deferred Ideas" section. Don't lose it, don't act on it. 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) **Express path available:** If you already have a PRD or acceptance criteria document, use `/pan:plan-phase {phase} --prd path/to/prd.md` to skip this discussion and go straight to planning. Phase number from argument (required). ```bash INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init phase-op "${PHASE}") ``` 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 /pan:progress to see available phases. ``` Exit workflow. **If `phase_found` is true:** Continue to auto_mode_bypass. **P-1803 fix (v3.7.8):** When `--auto` is set or `workflow.auto_advance: true`, **skip the entire question-driven discussion** and synthesize a minimal `context.md` directly from upstream artifacts. The 6 unguarded `AskUserQuestion` calls in this workflow (lines ~140, 156, 208, 261, 264, 278) all stall headless `claude -p` sessions immediately. Surfaced by the wookie autonomous build (v3.7.7): retry attempts via `/pan:discuss-phase 3 --auto` exited in 75s with $0.42 cost and zero commits before plan-phase auto-mode was patched to bypass discuss-phase entirely. This step makes discuss-phase itself auto-mode-safe, so it can be re-introduced into the auto pipeline cleanly. Detect auto mode: ```bash HAS_AUTO_FLAG=$(echo "$ARGUMENTS" | grep -c -- '--auto' || true) AUTO_CFG=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-get workflow.auto_advance 2>/dev/null || echo "false") ``` **If `HAS_AUTO_FLAG` > 0 OR `AUTO_CFG` is `true`:** Skip the interactive flow. Generate `context.md` from the roadmap goal + idea.md (if present) + project.md + requirements.md, then jump to `write_context` with the synthesized content. Specifically: 1. Display banner: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ PAN ► AUTO-MODE: synthesizing context from upstream artifacts ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` 2. Read inputs: ```bash ROADMAP_GOAL=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "${PHASE}" --raw | sed -n '/^Goal:/,/^$/p') IDEA_PATH=".planning/idea.md" PROJECT_PATH=".planning/project.md" REQ_PATH=".planning/requirements.md" ``` 3. Build a synthesized context.md (skip `analyze_phase`, `present_gray_areas`, `discuss_areas`, `summarize_decisions`, and the Plans-exist branch — go directly to a minimal but valid context.md): ```markdown # Phase ${PHASE}: ${PHASE_NAME} - Context **Gathered:** [today] **Status:** Ready for planning **Source:** Auto-mode synthesis (P-1803, v3.7.8) — derived from idea.md + project.md + requirements.md without user dialogue ## Phase Boundary [Goal extracted verbatim from roadmap.md] ## Implementation Decisions ### From idea.md [For each item in idea.md "Constraints" / "Scope" / "Notes for the planner" sections that mentions Phase ${PHASE} or its domain keywords (e.g., "image pipeline" for Phase 3) — extract as a locked decision, prefixed with the domain name] ### From requirements.md [For each requirement marked Active that maps to Phase ${PHASE} via `requirements.md`'s phase column — list as a locked decision] ### Claude's Discretion - Implementation patterns within the constraints above (the planner decides specific libraries / file layouts / function shapes) - Test names, fixture data, mock strategy - Internal variable / function naming - Comment density and inline doc style ## Specific References [Any concrete examples, library names, or file paths mentioned in idea.md "Reference material" or "Notes" sections that apply to this phase] ## Deferred Ideas None — auto-mode synthesis honors the original idea.md scope. --- *Phase: ${PADDED_PHASE}-${PHASE_SLUG}* *Context auto-synthesized: [today] via discuss-phase P-1803 bypass — no user dialogue* ``` Write the file: ```bash mkdir -p "${phase_dir}" # Use Write tool (NOT heredoc) to create ${phase_dir}/${PADDED_PHASE}-context.md ``` 4. Commit if `commit_docs` is true: ```bash node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs(${PADDED_PHASE}): auto-synthesize phase context (P-1803)" --files "${phase_dir}/${PADDED_PHASE}-context.md" ``` 5. Log a trace event: ```bash node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace log \ --type decision --category context-auto-synthesized \ --description "Phase ${PHASE} P-1803 bypass: context.md auto-synthesized in auto-mode without user dialogue" \ --agent orchestrator --impact minor 2>/dev/null || true ``` 6. **Skip ahead to `auto_advance` step** (existing step that spawns plan-phase via Task). Do NOT pass through `check_existing`, `analyze_phase`, `present_gray_areas`, `discuss_areas`, `summarize_decisions` — those all contain unguarded AskUserQuestion calls. **If neither `HAS_AUTO_FLAG` > 0 nor `AUTO_CFG` is true:** Continue to `check_existing` (interactive flow with full question-driven discussion). Check if context.md already exists using `has_context` from init. ```bash ls ${phase_dir}/*-context.md 2>/dev/null ``` **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` and `plan_count` from init. **If `has_plans` is true:** 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" — Capture context, then run /pan:plan-phase {X} to replan - "View existing plans" — Show plans before deciding - "Cancel" — Skip discuss-phase If "Continue and replan after": Continue to analyze_phase. If "View existing plans": Display plan files, then offer "Continue" / "Cancel". If "Cancel": Exit workflow. **If `has_plans` is false:** Continue to 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 posts exist - Content: What metadata displays (time, author, reactions count) ``` 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 library" (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. 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. Create context.md capturing decisions made. **Find or create phase directory:** Use values from init: `phase_dir`, `phase_slug`, `padded_phase`. If `phase_dir` is null (phase exists in roadmap but no directory): ```bash mkdir -p ".planning/phases/${padded_phase}-${phase_slug}" ``` **File location:** `${phase_dir}/${padded_phase}-context.md` **Structure the content by what was discussed:** ```markdown # Phase [X]: [Name] - Context **Gathered:** [date] **Status:** Ready for planning ## Phase Boundary [Clear statement of what this phase delivers — the scope anchor] ## 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] ## Specific Ideas [Any particular references, examples, or "I want it like X" moments from discussion] [If none: "No specific requirements — open to standard approaches"] ## Deferred Ideas [Ideas that came up but belong in other phases. Don't lose them.] [If none: "None — discussion stayed within phase scope"] --- *Phase: XX-name* *Context gathered: [date]* ``` Write file. Present summary and next steps: ``` Created: .planning/phases/${PADDED_PHASE}-${SLUG}/${PADDED_PHASE}-context.md ## Decisions Captured ### [Category] - [Key decision] ### [Category] - [Key decision] [If deferred ideas exist:] ## Noted for Later - [Deferred idea] — future phase --- ## ▶ Next Up **Phase ${PHASE}: [Name]** — [Goal from roadmap.md] `/pan:plan-phase ${PHASE}` <sub>`/clear` first → fresh context window</sub> --- **Also available:** - `/pan:plan-phase ${PHASE} --skip-research` — plan without research - Review/edit context.md before continuing --- ``` Commit phase context (uses `commit_docs` from init internally): ```bash node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs(${padded_phase}): capture phase context" --files "${phase_dir}/${padded_phase}-context.md" ``` Confirm: "Committed: docs(${padded_phase}): capture phase context" Update state.md with session info: ```bash node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state record-session \ --stopped-at "Phase ${PHASE} context gathered" \ --resume-file "${phase_dir}/${padded_phase}-context.md" ``` Commit state.md: ```bash node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs(state): record phase ${PHASE} context session" --files .planning/state.md ``` Check for auto-advance trigger: 1. Parse `--auto` flag from $ARGUMENTS 2. Read `workflow.auto_advance` from config: ```bash AUTO_CFG=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-get workflow.auto_advance 2>/dev/null || echo "false") ``` **If `--auto` flag present AND `AUTO_CFG` is not true:** Persist auto-advance to config (handles direct `--auto` usage without new-project): ```bash node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.auto_advance true ``` **If `--auto` flag present OR `AUTO_CFG` is true:** Display banner: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ PAN ► AUTO-ADVANCING TO PLAN ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Context captured. Spawning plan-phase... ``` Spawn plan-phase as Task with direct workflow file reference (do NOT use Skill tool — Skills don't resolve inside Task subagents): ``` Task( prompt=" You are the plan-phase orchestrator. Create executable plans for Phase ${PHASE}: ${PHASE_NAME}, then auto-advance to execution. @~/.claude/pan-wizard-core/workflows/plan-phase.md @~/.claude/pan-wizard-core/references/ui-brand.md @~/.claude/pan-wizard-core/references/model-profile-resolution.md PHASE=${PHASE} ARGUMENTS='${PHASE} --auto' 1. Read plan-phase.md from execution_context for your complete workflow 2. Follow ALL steps: initialize, validate, load context, research, plan, verify, auto-advance 3. When spawning agents (pan-phase-researcher, pan-planner, pan-plan-checker), use Task with specified subagent_type and model 4. For step 14 (auto-advance to execute): spawn execute-phase as a Task with DIRECT file reference — tell it to read exec-phase.md. Include @file refs to exec-phase.md, checkpoints.md, tdd.md, model-profile-resolution.md. Pass --no-transition flag so execute-phase returns results instead of chaining further. 5. Do NOT use the Skill tool or /pan: commands. Read workflow .md files directly. 6. Return: PHASE COMPLETE (full pipeline success), PLANNING COMPLETE (planning done but execute failed/skipped), PLANNING INCONCLUSIVE, or GAPS FOUND ", subagent_type="general-purpose", description="Plan Phase ${PHASE}" ) ``` **Handle plan-phase return:** - **PHASE COMPLETE** → Full chain succeeded. Display: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ PAN ► PHASE ${PHASE} COMPLETE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Auto-advance pipeline finished: discuss → plan → execute Next: /pan:discuss-phase ${NEXT_PHASE} --auto <sub>/clear first → fresh context window</sub> ``` - **PLANNING COMPLETE** → Planning done, execution didn't complete: ``` Auto-advance partial: Planning complete, execution did not finish. Continue: /pan:exec-phase ${PHASE} ``` - **PLANNING INCONCLUSIVE / CHECKPOINT** → Stop chain: ``` Auto-advance stopped: Planning needs input. Continue: /pan:plan-phase ${PHASE} ``` - **GAPS FOUND** → Stop chain: ``` Auto-advance stopped: Gaps found during execution. Continue: /pan:plan-phase ${PHASE} --gaps ``` **If neither `--auto` nor config enabled:** Route to `confirm_creation` step (existing behavior — show manual next steps). - 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 - state.md updated with session info - User knows next steps