@sienklogic/plan-build-run 2.11.0 → 2.12.1

package/plan-build-run/workflows/discuss-phase.md

@@ -0,0 +1,429 @@
+<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. **pbr-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. **pbr-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.
+</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)
+
+**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.
+</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>
+
+<process>
+
+<step name="initialize" priority="first">
+Phase number from argument (required).
+
+```bash
+INIT=$(node ~/.claude/plan-build-run/scripts/pbr-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 /pbr:progress to see available phases.
+```
+Exit workflow.
+
+**If `phase_found` is true:** Continue to check_existing.
+</step>
+
+<step name="check_existing">
+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: "Existing 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:** 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 posts 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 formatted as:
+  - "[Specific area]" (label) — concrete, not generic
+  - [1-2 questions this covers] (description)
+
+**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.
+</step>
+
+<step name="discuss_areas">
+For each selected area, conduct a focused discussion loop.
+
+**Philosophy: Ask questions, then check.**
+
+Check config for `workflow.max_discuss_questions` (default: 4). Ask that many 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 questions using AskUserQuestion (up to max_discuss_questions, default 4):**
+   - header: "[Area]"
+   - question: Specific decision for this area
+   - options: 2-3 concrete choices (AskUserQuestion adds "Other" automatically)
+   - Include "You decide" as an option when reasonable — captures Claude discretion
+
+3. **After reaching the question limit, check:**
+   - header: "[Area]"
+   - question: "More questions about [area], or move to next?"
+   - options: "More questions" / "Next area"
+
+   If "More questions" → ask another batch, then check again
+   If "Next area" → proceed to next selected area
+
+4. **After all areas complete:**
+
+   **If only one area was selected:** Skip this prompt — go directly to `write_context`.
+
+   **If multiple areas were selected:**
+   - header: "Done"
+   - question: "That covers [list areas]. Ready to create context?"
+   - options: "Create context" / "Revisit an area"
+
+**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:**
+
+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
+
+<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: XX-name*
+*Context gathered: [date]*
+```
+
+Write file.
+</step>
+
+<step name="confirm_creation">
+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]
+
+`/pbr:plan-phase ${PHASE}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/pbr:plan-phase ${PHASE} --skip-research` — plan without research
+- Review/edit CONTEXT.md before continuing
+
+---
+```
+</step>
+
+<step name="git_commit">
+Commit phase context (uses `commit_docs` from init internally):
+
+```bash
+node ~/.claude/plan-build-run/scripts/pbr-tools.cjs commit "docs(${padded_phase}): capture phase context" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
+```
+
+Confirm: "Committed: docs(${padded_phase}): capture phase context"
+</step>
+
+<step name="update_state">
+Update STATE.md to reflect context gathering completion:
+
+```bash
+node ~/.claude/plan-build-run/scripts/pbr-tools.cjs state record-session \
+  --stopped-at "Captured context for Phase ${padded_phase}-${phase_slug}" \
+  --resume-file "None"
+```
+
+Commit the state update:
+
+```bash
+node ~/.claude/plan-build-run/scripts/pbr-tools.cjs commit "docs(${padded_phase}): update state after context gathering" --files .planning/STATE.md
+```
+</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
+- STATE.md updated (session continuity recorded)
+- User knows next steps
+</success_criteria>