@sienklogic/plan-build-run 2.18.1 → 2.19.1

package/plugins/pbr/skills/debug/SKILL.md

@@ -27,9 +27,17 @@ This skill **spawns Task(subagent_type: "pbr:debugger")** for investigation work
 
 ---
 
+## References
+
+- `references/questioning.md` — Investigation questioning patterns: progressive depth, exploratory questions, concrete options (not open-ended)
+- `references/ui-brand.md` — Status symbols, banners, error boxes for issue reporting
+
+---
+
 ## Context Budget
 
 Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
+Reference: `skills/shared/agent-type-resolution.md` for agent type fallback when spawning Task() subagents.
 
 Additionally for this skill:
 - **Never** perform investigation work yourself — delegate ALL analysis to the debugger subagent
@@ -48,6 +56,8 @@ Additionally for this skill:
 
 ### Step 1: Ensure Debug Directory Exists
 
+**CRITICAL (no hook) -- DO NOT SKIP: Create debug directory before any file writes.**
+
 Before any file operations, ensure both directories exist by running:
 
 ```bash
@@ -76,6 +86,7 @@ Read each file's frontmatter to check status:
 
 **If active sessions found:**
 
+**CRITICAL -- DO NOT SKIP**: Present the following choice to the user via AskUserQuestion before proceeding:
 Use the **debug-session-select** pattern from `skills/shared/gate-prompts.md`:
   question: "Found active debug sessions. Which would you like?"
 
@@ -92,6 +103,31 @@ Handle responses:
 **If no active sessions found:**
 - Go to **New Session Flow** (Step 3a)
 
+### Step 2b: UAT Gap Intake (conditional)
+
+**Trigger:** If `$ARGUMENTS` contains `--from-uat`, OR if no arguments provided and UAT.md gaps exist for the current phase.
+
+When triggered:
+
+1. Read the current phase's VERIFICATION.md (or UAT.md if it exists):
+   - Look for `status: gaps_found` in frontmatter
+   - Parse the gaps section for individual gap entries
+2. For each gap entry, extract:
+   - Gap description (symptom)
+   - Expected vs. actual behavior
+   - Affected files/components
+3. Pre-fill the debug session with UAT context:
+   - **Issue title**: derived from the first/primary gap description
+   - **Symptoms**: populated from gap details (expected, actual, scope)
+   - **Category**: set to the gap's category if available (e.g., "test", "integration")
+   - **Context**: include the phase context and related plan information
+4. Skip the symptom-gathering questions in Step 3a (symptoms are already populated from UAT gaps)
+5. Proceed directly to **Generate Session ID** and **Create Debug File** with the pre-filled data
+
+**If `--from-uat` is specified but no gaps exist:**
+- Display: "No UAT/verification gaps found for the current phase. Starting a standard debug session."
+- Fall through to normal Step 3a flow
+
 ### Step 3a: New Session Flow
 
 #### Gather Symptoms
@@ -121,10 +157,16 @@ If `$ARGUMENTS` is empty or minimal:
 1. Scan `.planning/debug/` for existing files
 2. Extract NNN prefixes
 3. Next number = highest + 1 (start at 001)
-4. Generate slug from issue title (same rules as quick task slugs)
+4. Generate slug from issue title via CLI:
+   ```bash
+   node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js slug-generate "{issue title}"
+   ```
+   Parse the JSON output to get the `slug` field.
 
 #### Create Debug File
 
+**CRITICAL (no hook) -- DO NOT SKIP: Write debug session file to disk.**
+
 Create `.planning/debug/{NNN}-{slug}.md`:
 
 ```markdown
@@ -181,11 +223,11 @@ category: "{runtime|build|test|config|integration|unknown}"
 
 #### Spawn Debugger
 
-Display to the user: `◐ Spawning debugger...`
+Display to the user: `◆ Spawning debugger...`
 
 Spawn `Task(subagent_type: "pbr:debugger")` with the prompt template.
 
-Read `skills/debug/templates/initial-investigation-prompt.md.tmpl` for the spawn prompt. Fill in the `{NNN}`, `{slug}`, and symptom placeholders with values from the debug file created above.
+Read `${CLAUDE_SKILL_DIR}/templates/initial-investigation-prompt.md.tmpl` for the spawn prompt. Fill in the `{NNN}`, `{slug}`, and symptom placeholders with values from the debug file created above.
 
 ### Step 3b: Resume Flow
 
@@ -205,15 +247,28 @@ Last state:
 Continuing investigation...
 ```
 
-4. **Increment the round counter** (resuming counts as a new round). Display to the user: `◐ Spawning debugger (resuming session #{NNN}, round {N})...`
+4. **Increment the round counter** (resuming counts as a new round). Display to the user: `◆ Spawning debugger (resuming session #{NNN}, round {N})...`
 
    Spawn `Task(subagent_type: "pbr:debugger")` with the continuation prompt template.
 
-   Read `skills/debug/templates/continuation-prompt.md.tmpl` for the spawn prompt. Fill in the `{NNN}`, `{slug}`, and `{paste investigation log...}` placeholders with data from the debug file.
+   Read `${CLAUDE_SKILL_DIR}/templates/continuation-prompt.md.tmpl` for the spawn prompt. Fill in the `{NNN}`, `{slug}`, and `{paste investigation log...}` placeholders with data from the debug file.
 
 ### Step 4: Handle Debugger Results
 
-When the debugger agent completes, display: `✓ Debug session complete — {N} hypotheses tested` (read the hypothesis count from the debug file's Hypotheses table).
+When the debugger agent completes, first check for completion markers in the Task() output before routing:
+
+| Marker in Task() Output | Route To |
+|--------------------------|----------|
+| `## DEBUG COMPLETE` | ROOT CAUSE FOUND + FIX path |
+| `## ROOT CAUSE FOUND` | ROOT CAUSE FOUND (no fix) path |
+| `## DEBUG SESSION PAUSED` | CHECKPOINT path |
+| No marker found | INCONCLUSIVE path |
+
+**Spot-check:** Before routing, verify `.planning/debug/{NNN}-{slug}.md` exists and was recently updated (modified timestamp is newer than the Task() spawn time). If the debug file was not updated, warn: `⚠ Debug file not updated by agent — results may be incomplete.`
+
+**Memory capture:** Reference `skills/shared/memory-capture.md` — check debugger output for `<memory_suggestion>` blocks and save any reusable knowledge discovered during debugging.
+
+Display: `✓ Debug session complete — {N} hypotheses tested` (read the hypothesis count from the debug file's Hypotheses table).
 
 The debugger returns one of four outcomes:
 
@@ -252,7 +307,7 @@ Actions:
 
 **Continue your workflow** — the bug is fixed
 
-`/pbr:status`
+`/pbr:progress`
 
 <sub>`/clear` first → fresh context window</sub>
 
@@ -260,7 +315,7 @@ Actions:
 
 **Also available:**
 - `/pbr:continue` — execute next logical step
-- `/pbr:review {N}` — verify the current phase
+- `/pbr:verify-work {N}` — verify the current phase
 
 
 ```
@@ -297,8 +352,8 @@ Actions:
 
 
 **Also available:**
-- `/pbr:plan` — for complex fixes that need planning
-- `/pbr:status` — see project status
+- `/pbr:plan-phase` — for complex fixes that need planning
+- `/pbr:progress` — see project status
 
 
 ```
@@ -317,11 +372,12 @@ Investigation progress:
 Actions:
 1. Update debug file with findings so far
 2. Present checkpoint to user
-3. Use the **debug-checkpoint** pattern from `skills/shared/gate-prompts.md`:
+3. **CRITICAL -- DO NOT SKIP**: Present the following choice to the user via AskUserQuestion before proceeding:
+   Use the **debug-checkpoint** pattern from `skills/shared/gate-prompts.md`:
    question: "Investigation has reached a checkpoint. How should we proceed?"
 
 Handle responses:
-- "Continue": **Increment the round counter** (e.g., round 1 becomes round 2). Then display `◐ Spawning debugger (continuing investigation, round {N})...` and spawn another `Task(subagent_type: "pbr:debugger")` with updated context from the debug file
+- "Continue": **Increment the round counter** (e.g., round 1 becomes round 2). Then display `◆ Spawning debugger (continuing investigation, round {N})...` and spawn another `Task(subagent_type: "pbr:debugger")` with updated context from the debug file
 - "More info": **Increment the round counter.** Ask the user freeform what additional context they have, then update the debug file and spawn another debugger
 - "New approach": **Increment the round counter.** Ask the user freeform what alternative angle to try, then update hypotheses and spawn another debugger
 
@@ -463,6 +519,8 @@ If `planning.commit_docs: true` in config.json:
 
 ---
 
+Reference: `skills/shared/error-reporting.md` for branded error output patterns.
+
 ## Edge Cases
 
 ### User provides a stack trace or error in arguments

package/plugins/pbr/skills/debug/templates/continuation-prompt.md.tmpl

@@ -1,6 +1,13 @@
 <!-- Source: skills/debug/SKILL.md | Purpose: Spawn prompt for continuation debugger investigation -->
 You are debugger. Continue investigating the following issue.
 
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/debug/{NNN}-{slug}.md — the debug session file with all prior findings
+2. .planning/CONTEXT.md — locked decisions and constraints (if exists)
+3. .planning/STATE.md — current project state (if exists)
+</files_to_read>
+
 Debug file: .planning/debug/{NNN}-{slug}.md
 Mode: continuation
 
@@ -13,4 +20,8 @@ Instructions:
 3. Formulate NEW hypotheses based on prior findings
 4. Continue systematic investigation
 5. Update the debug file
-6. Return: ROOT_CAUSE_FOUND, CHECKPOINT, or INCONCLUSIVE
+6. Return one of these markers as a heading in your response:
+   - `## DEBUG COMPLETE` — root cause found + fix applied
+   - `## ROOT CAUSE FOUND` — root cause identified, no fix applied
+   - `## DEBUG SESSION PAUSED` — checkpoint, need user input
+   - If no root cause found after exhausting hypotheses, return without a marker (treated as INCONCLUSIVE)

package/plugins/pbr/skills/debug/templates/initial-investigation-prompt.md.tmpl

@@ -1,6 +1,13 @@
 <!-- Source: skills/debug/SKILL.md | Purpose: Spawn prompt for initial debugger investigation -->
 You are debugger. Investigate the following issue systematically.
 
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/debug/{NNN}-{slug}.md — the debug session file with symptoms and context
+2. .planning/CONTEXT.md — locked decisions and constraints (if exists)
+3. .planning/STATE.md — current project state (if exists)
+</files_to_read>
+
 Debug file: .planning/debug/{NNN}-{slug}.md
 Mode: initial_investigation
 
@@ -20,8 +27,8 @@ Instructions:
    c. Execute the test
    d. Record the result (confirmed, rejected, inconclusive)
 4. Update the debug file with findings
-5. Return one of:
-   - ROOT_CAUSE_FOUND: {cause} + FIX: {what to change}
-   - ROOT_CAUSE_FOUND: {cause} (if find_root_cause_only mode)
-   - CHECKPOINT: {what was found, what to investigate next}
-   - INCONCLUSIVE: {findings so far, suggested next approaches}
+5. Return one of these markers as a heading in your response:
+   - `## DEBUG COMPLETE` — root cause found + fix applied: {cause} + {what was changed}
+   - `## ROOT CAUSE FOUND` — root cause identified, no fix applied (if find_root_cause_only mode): {cause}
+   - `## DEBUG SESSION PAUSED` — checkpoint, need user input: {what was found, what to investigate next}
+   - If no root cause found after exhausting hypotheses, return without a marker (treated as INCONCLUSIVE)

package/plugins/pbr/skills/discuss/SKILL.md

@@ -2,7 +2,7 @@
 name: discuss
 description: "Talk through a phase before planning. Identifies gray areas and captures your decisions."
 allowed-tools: Read, Write, Glob, Grep, AskUserQuestion
-argument-hint: "<phase-number>"
+argument-hint: "<phase-number> [--auto] | --project"
 ---
 
 **STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes ~7,600 tokens. Begin executing Step 1 immediately.**
@@ -19,7 +19,12 @@ argument-hint: "<phase-number>"
 
 Then proceed to Step 1.
 
-# /pbr:discuss — Pre-Planning Discussion
+# /pbr:discuss-phase — Pre-Planning Discussion
+
+**References:** `@references/questioning.md`, `@references/ui-brand.md`
+
+Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
+Reference: `skills/shared/context-loader-task.md` for efficient context loading patterns.
 
 You are running the **discuss** skill. Your job is to help the user think through a phase BEFORE planning begins. You identify gray areas where the user's preference matters, ask structured questions, and capture every decision in a CONTEXT.md file that the planner must honor.
 
@@ -27,6 +32,22 @@ This skill runs **inline** (no Task delegation).
 
 ---
 
+## Multi-Session Sync
+
+Before any phase-modifying operations (writing CONTEXT.md, updating STATE.md), acquire a claim:
+
+```
+acquireClaim(phaseDir, sessionId)
+```
+
+If the claim fails (another session owns this phase), display: "Another session owns this phase. Use `/pbr:progress` to see active claims."
+
+On completion or error (including all exit paths), release the claim:
+
+```
+releaseClaim(phaseDir, sessionId)
+```
+
 ## Core Principle
 
 **Decisions made here are LOCKED.** The planner cannot override them, even if research suggests a different approach. The planner must implement the locked decision and may note the discrepancy, but must follow the user's choice exactly.
@@ -37,12 +58,24 @@ This skill runs **inline** (no Task delegation).
 
 ### Step 1: Parse Phase Number and Check for Existing Plans
 
-Parse `$ARGUMENTS` to get the phase number.
+**CRITICAL (hook-enforced): Write .active-skill NOW.** Write the text "discuss" to `.planning/.active-skill` using the Write tool.
 
-**Validation:**
+Parse `$ARGUMENTS`:
+- If argument is `--project`: enter PROJECT mode (see Step 1-project below). Skip Steps 2-8.
+- If argument is a phase number: enter PHASE mode (existing flow — continue with Step 1 as-is).
+- If no argument: existing logic applies (read STATE.md for current phase).
+- If `--auto` is present in `$ARGUMENTS`: set `auto_mode = true`. Log: "Auto mode enabled — batching gray area questions"
+
+| Argument | Meaning |
+|----------|---------|
+| `3` | Discuss phase 3 |
+| `3 --auto` | Discuss phase 3 with auto mode — batch all gray areas into a single presentation |
+| `--project` | Discuss project-level cross-cutting decisions |
+
+**Validation (PHASE mode):**
 - Must be a valid phase number (integer or decimal like `3.1`)
 - If no argument provided, read STATE.md to get the current phase
-- If no current phase and no argument: "Which phase do you want to discuss? Run `/pbr:status` to see available phases."
+- If no current phase and no argument: "Which phase do you want to discuss? Run `/pbr:progress` to see available phases."
 
 **Phase directory resolution:**
 1. List directories in `.planning/phases/`
@@ -56,17 +89,74 @@ Parse `$ARGUMENTS` to get the phase number.
 
 Phase {N} not found.
 
-**To fix:** Run `/pbr:status` to see available phases.
+**To fix:** Run `/pbr:progress` to see available phases.
 ```
 
 **Check for existing plans** (after resolving the phase directory):
 1. Check for `PLAN.md` or `PLAN-*.md` files in the phase directory
 2. If plan files exist:
-   - Warn: "Phase {N} already has plans. Decisions from this discussion won't retroactively change them. Consider re-planning with `/pbr:plan {N}` after."
+   - Warn: "Phase {N} already has plans. Decisions from this discussion won't retroactively change them. Consider re-planning with `/pbr:plan-phase {N}` after."
    - This is a **warning only** — do not block the discussion
 
+### Step 1-project: Project Discussion Mode (--project)
+
+When invoked with `--project`, discuss project-level cross-cutting decisions.
+This mode writes to `.planning/PROJECT.md` ## Context section (project-level), NOT a phase directory.
+
+**Check for existing project context:**
+1. Read `.planning/PROJECT.md` and check if it has a `## Context` section.
+2. If it has a ## Context section:
+   **CRITICAL -- DO NOT SKIP**: Present the following choice to the user via AskUserQuestion before proceeding:
+   Ask the user (using the context-handling pattern from
+   `skills/shared/gate-prompts.md`):
+   question: "PROJECT.md already has a ## Context section. How should we handle it?"
+   options: Overwrite | Append | Cancel
+3. If Cancel: stop and display the existing PROJECT.md path.
+4. **Backwards compat:** If `.planning/CONTEXT.md` exists (legacy), read it as the existing context source for Append mode, then write merged result to PROJECT.md ## Context.
+
+**Load project context:**
+- Read `.planning/PROJECT.md` (if exists) — project vision, scope, and context (## Context section)
+- Read `.planning/REQUIREMENTS.md` (if exists) — requirements for constraint awareness
+- **Backwards compat:** If PROJECT.md has no ## Context but `.planning/CONTEXT.md` exists, read from the legacy file
+
+**Run gray areas for project-level decisions (Steps 2.5-5 pattern):**
+- Identify 3-4 cross-cutting architectural decisions across ALL phases
+- Focus on: technology stack choices, infrastructure, security posture,
+  observability approach, deployment strategy, data storage decisions
+- Follow the same Steps 3-5 pattern (gray areas → options → follow-ups)
+
+**Write project context to PROJECT.md:**
+1. Read `${CLAUDE_SKILL_DIR}/templates/project-CONTEXT.md.tmpl`
+2. Fill in from discussion decisions:
+   - Locked Decisions table: all decisions the user made (not "Let Claude decide")
+   - User Constraints: budget, team, timeline, hosting from the conversation
+   - Deferred Ideas: anything explicitly ruled out for this project
+   - Claude's Discretion: decisions marked "Let Claude decide"
+3. If Append mode: merge new decisions with existing PROJECT.md ## Context content
+**CRITICAL: Write the discussion results to PROJECT.md NOW.**
+
+4. Write to `.planning/PROJECT.md` under the `## Context` section with subsections:
+   - `### Locked Decisions`
+   - `### User Constraints`
+   - `### Deferred Ideas`
+
+**Update STATE.md pointer:**
+Add under Accumulated Context:
+```
+Project context: .planning/PROJECT.md ## Context ({N} locked decisions, {N} deferred, {N} discretion)
+```
+
+**After writing:** Auto-sync to CLAUDE.md is handled by the post-write-dispatch hook.
+Display: `✓ Project context written to PROJECT.md — locked decisions will auto-sync to CLAUDE.md`
+
+Skip to Cleanup step. Do NOT run Steps 2-8 of the phase flow.
+
+---
+
 ### Step 2: Load Phase Context
 
+Reference: `skills/shared/context-loader-task.md` for efficient context loading patterns.
+
 Read the following files to understand what this phase needs to accomplish:
 
 1. **ROADMAP.md** — Find the phase entry. Extract:
@@ -82,10 +172,12 @@ Read the following files to understand what this phase needs to accomplish:
    - What patterns have been established (`patterns` field)
    - What decisions were already made (`key_decisions` field)
 
-3. **REQUIREMENTS.md** (if exists) — Read project requirements relevant to this phase
+3. **REQUIREMENTS.md** (if exists) — Read project requirements relevant to this phase. **CRITICAL**: After reading, display to the user which specific requirements map to this phase. Flag any requirements that could constrain decisions. If the user's discussion decisions later contradict a stated requirement, surface the contradiction immediately — don't wait until planning.
 
 4. **CONTEXT.md** (if exists in the phase directory) — Check if a prior discussion already happened
-   - If CONTEXT.md exists, inform the user and use the **context-handling** pattern from `skills/shared/gate-prompts.md`:
+   - If CONTEXT.md exists, inform the user and:
+     **CRITICAL -- DO NOT SKIP**: Present the following choice to the user via AskUserQuestion before proceeding:
+     Use the **context-handling** pattern from `skills/shared/gate-prompts.md`:
      question: "Phase {N} already has a CONTEXT.md from a prior discussion. How should we handle it?"
 
    Handle responses:
@@ -116,7 +208,7 @@ Before jumping into specific gray areas, give the user space to share their ment
 
 Analyze the phase goal, requirements, and what's already built. Identify **3-4 gray areas** where the user's preference matters. Gray areas fall into these categories:
 
-Read `skills/discuss/templates/decision-categories.md` for the category reference table.
+Read `${CLAUDE_SKILL_DIR}/templates/decision-categories.md` for the category reference table.
 
 **How to identify gray areas:**
 1. Look at the phase requirements — where are there multiple valid approaches?
@@ -128,6 +220,11 @@ Read `skills/discuss/templates/decision-categories.md` for the category referenc
 
 ### Step 4: Present Gray Areas
 
+**Smart batching (auto_mode):** When `auto_mode` is true, collect ALL gray areas and present them in a single batch rather than one at a time. Present all gray areas together with their options so the user can respond to everything at once. This reduces interaction rounds while still capturing user decisions. After the user responds, proceed to Step 5 with all decisions.
+
+**Standard mode (auto_mode is false or absent):**
+
+**CRITICAL -- DO NOT SKIP**: Present the following choice to the user via AskUserQuestion before proceeding:
 Present each gray area to the user using the **gray-area-option** pattern from `skills/shared/gate-prompts.md`. For each gray area:
 
 Use AskUserQuestion:
@@ -149,6 +246,28 @@ If more than 3 concrete options exist for a gray area, present only the top 3 pl
 - If the user gives a preference not in the options, accept it
 - If the user says "I don't care", mark it as Claude's Discretion
 
+### Step 4b: Advisor Research (optional, for technology decisions)
+
+If any gray area involves a **technology choice** (library selection, framework decision, architecture pattern) and the user expresses uncertainty or asks "which is better?", spawn a focused research agent:
+
+```
+Task({
+  subagent_type: "pbr:advisor-researcher",
+  prompt: "<files_to_read>
+    1. .planning/PROJECT.md — project context and constraints
+    2. .planning/CONTEXT.md — existing locked decisions (if exists)
+  </files_to_read>
+  Decision area: {gray area title}
+  Context: {project constraints, existing stack}
+  Options to compare: {options from Step 4}
+  Return a structured comparison table with recommendation."
+})
+```
+
+After the advisor returns, present the comparison table to the user and let them make the final decision. The user's choice becomes the locked decision — the advisor's recommendation is advisory only.
+
+**Skip this step if:** No gray areas involve technology choices, or the user already made confident decisions in Step 4.
+
 ### Step 5: Deep-Dive Each Selected Area
 
 For each gray area where the user made a decision (not "Let Claude decide"), ask **4 follow-up questions** to fully capture their intent.
@@ -159,6 +278,7 @@ For each gray area where the user made a decision (not "Let Claude decide"), ask
 
 **CRITICAL — STOP: Do NOT skip this follow-up area.**
 1. **Scope boundary**: "Should {feature} also handle {edge case}?"
+   **CRITICAL -- DO NOT SKIP**: Present the following choice to the user via AskUserQuestion before proceeding:
    Use the **yes-no** pattern — this is a binary decision.
 
 **CRITICAL — STOP: Do NOT skip this follow-up area.**
@@ -171,6 +291,7 @@ For each gray area where the user made a decision (not "Let Claude decide"), ask
 
 **CRITICAL — STOP: Do NOT skip this follow-up area.**
 4. **Future-proofing**: "Should we design this to support {potential future need}, or keep it simple?"
+   **CRITICAL -- DO NOT SKIP**: Present the following choice to the user via AskUserQuestion before proceeding:
    Use the **yes-no** pattern:
      question: "Design {feature} to support {future need}, or keep it simple for now?"
      options:
@@ -187,20 +308,41 @@ For each gray area where the user made a decision (not "Let Claude decide"), ask
 
 ### Step 6: Capture Deferred Ideas
 
+Reference: The deferred section prevents scope creep in downstream planning. See CONTEXT.md template.
+
 During the conversation, the user may mention ideas they want but not in this phase. Track these separately:
+
 - Ideas explicitly deferred by the user ("let's do that later")
 - Ideas that are out of scope for this phase based on ROADMAP.md
 - Ideas the user considered but rejected
 
+### Step 6.5: Decision Gate (inline)
+
+Before creating the CONTEXT.md artifact, confirm readiness with the user per `@references/questioning.md` decision gate pattern:
+
+```
+AskUserQuestion:
+  question: "I think I have a clear picture of your decisions for this phase. Ready to capture them in CONTEXT.md?"
+  header: "Ready?"
+  options:
+    - label: "Yes, proceed"    description: "Write CONTEXT.md with captured decisions"
+    - label: "Keep exploring"  description: "I want to share more or discuss further"
+```
+
+If "Keep exploring" -- ask what they want to add or identify gaps and probe naturally. Loop until "Yes, proceed" is selected.
+
+**Freeform rule:** If the user selects "Keep exploring" and responds with freeform text (not selecting an option), switch to plain text conversation per `@references/questioning.md` freeform rule. Do NOT present another AskUserQuestion until you have processed their freeform response.
+
 ### Step 7: Write CONTEXT.md
 
+**CRITICAL — DO NOT SKIP: Write CONTEXT.md NOW. This file is the sole output of the discuss skill. Skipping it means all decisions are lost.**
 Write the CONTEXT.md file to the phase directory:
 
 **Path:** `.planning/phases/{NN}-{phase-name}/CONTEXT.md`
 
 **Content:**
 
-Read `skills/discuss/templates/CONTEXT.md.tmpl` for the template structure.
+Read `${CLAUDE_SKILL_DIR}/templates/CONTEXT.md.tmpl` for the template structure.
 
 **Placeholders to fill:**
 - `{N}` -- the phase number
@@ -210,11 +352,22 @@ Read `skills/discuss/templates/CONTEXT.md.tmpl` for the template structure.
 - `{Area}` / `{What Claude can choose}` -- items marked "Let Claude decide"
 - `{2-3 sentences}` -- user's vision summary from the conversation
 - `{Concern}` / `{Context}` -- concerns raised during discussion
+- `<specifics>` -- concrete technical details, patterns, or conventions from the conversation
+- `<code_context>` -- relevant files and modules referenced during discussion
 
 **Decision Summary generation:** The `## Decision Summary` section at the top of CONTEXT.md is a compact digest (~300 tokens) of all decisions. For each locked decision, write only the title and the user's choice in one phrase (no scope/quality/integration details). List deferred and discretion items as comma-separated titles only. This summary is injected into agent prompts by the plan skill -- keep it concise.
 
+**Downstream awareness:** The CONTEXT.md written here is consumed by:
+
+- `/pbr:plan-phase` -- planner reads locked decisions as constraints
+- `/pbr:execute-phase` -- executor receives decisions via planner's plan
+- `/pbr:verify-work` -- verifier checks deliverables against phase intent
+
+Ensure all locked decisions are written clearly enough for mechanical consumption.
+
 ### Step 7.5: Update STATE.md Pointer
 
+**CRITICAL — DO NOT SKIP: Update STATE.md pointer to new CONTEXT.md NOW.**
 Update `.planning/STATE.md`'s `## Accumulated Context` section to add a reference to the new CONTEXT.md:
 
 Add under the `### Decisions` subsection:
@@ -222,11 +375,28 @@ Add under the `### Decisions` subsection:
 Phase {N} discussion: .planning/phases/{NN}-{slug}/CONTEXT.md ({count} locked, {count} deferred, {count} discretion)
 ```
 
-This creates a pointer so `/pbr:resume` and `progress-tracker.js` know that phase-specific decisions exist and where to find them.
+This creates a pointer so `/pbr:resume-work` and `progress-tracker.js` know that phase-specific decisions exist and where to find them.
+
+### Step 7.7: Write Discussion Log (audit trail)
+
+Write `.planning/phases/{NN}-{slug}/DISCUSSION-LOG.md` as an audit trail of the discussion. This file is NOT consumed by agents — it's for human audit only.
+
+Read `${CLAUDE_PLUGIN_ROOT}/templates/DISCUSSION-LOG.md.tmpl` for the format.
+
+For each decision area discussed:
+- Record all options that were presented
+- Mark which option was selected
+- Include the user's verbatim choice and any notes/rationale
+- Record items delegated to Claude's discretion
+- Record deferred ideas
+
+This log is separate from CONTEXT.md (which is the implementation artifact for agents). The discussion log preserves the alternatives considered, not just the final decisions.
+
+If `planning.commit_docs` is true, include in the next commit.
 
 ### Step 8: Confirm and Route
 
-After writing CONTEXT.md, display branded output:
+After writing CONTEXT.md, display branded output per `@references/ui-brand.md`:
 
 ```
 ╔══════════════════════════════════════════════════════════════╗
@@ -235,9 +405,7 @@ After writing CONTEXT.md, display branded output:
 
 **Phase {N}: {name}**
 
-Decisions: {count} locked, {count} deferred, {count} discretion
-
-
+✓ Decisions: {count} locked, {count} deferred, {count} discretion
 
 ╔══════════════════════════════════════════════════════════════╗
 ║  ▶ NEXT UP                                                   ║
@@ -245,19 +413,17 @@ Decisions: {count} locked, {count} deferred, {count} discretion
 
 **Plan this phase** — your decisions will be honored
 
-`/pbr:plan {N}`
+`/pbr:plan-phase {N}`
 
 <sub>`/clear` first → fresh context window</sub>
 
-
-
 **Also available:**
-- `/pbr:status` — see project status
+- `/pbr:progress` — see project status
 - `/pbr:explore` — explore ideas further
-
-
 ```
 
+**Cleanup:** Delete `.planning/.active-skill` before finishing. This must happen on all paths (success, cancel, and error).
+
 ---
 
 ## Decision Categories Reference
@@ -305,7 +471,8 @@ These come from:
 ## Edge Cases
 
 ### Phase already has CONTEXT.md
-- Use the **context-handling** pattern from `skills/shared/gate-prompts.md` (same as Step 2)
+- **CRITICAL -- DO NOT SKIP**: Present the following choice to the user via AskUserQuestion before proceeding:
+  Use the **context-handling** pattern from `skills/shared/gate-prompts.md` (same as Step 2)
 - If "Overwrite": replace entirely
 - If "Append": add new decisions below existing ones, marking them as "Amendment"
 - If "Cancel": stop the discussion, keep existing CONTEXT.md
@@ -316,7 +483,7 @@ These come from:
 
 ### User wants to discuss multiple phases
 - Handle one at a time
-- After completing one, suggest: "Want to discuss Phase {N+1} too? Run `/pbr:discuss {N+1}`."
+- After completing one, suggest: "Want to discuss Phase {N+1} too? Run `/pbr:discuss-phase {N+1}`."
 
 ### User disagrees with all options
 - Ask: "What would you prefer instead?" — this is freeform text, do NOT use AskUserQuestion.
@@ -330,9 +497,21 @@ These come from:
 
 ---
 
+## Error Handling
+
+Reference: `skills/shared/error-reporting.md` for error output patterns.
+
+If any step fails (file read error, directory not found, write failure):
+
+1. Display branded error using the pattern from `error-reporting.md`
+2. Clear `.planning/.active-skill` before exiting
+3. Do NOT leave partial CONTEXT.md files -- write atomically or not at all
+
+---
+
 ## State Integration
 
-This skill updates STATE.md's Accumulated Context section with a pointer to the phase CONTEXT.md file. It does NOT change the project position (current phase/plan). STATE.md position is updated when `/pbr:plan` runs.
+This skill updates STATE.md's Accumulated Context section with a pointer to the phase CONTEXT.md file. It does NOT change the project position (current phase/plan). STATE.md position is updated when `/pbr:plan-phase` runs.
 
 ---
 
@@ -343,6 +522,8 @@ Reference: `skills/shared/commit-planning-docs.md` for the standard commit patte
 If `planning.commit_docs: true` in config.json:
 - Commit CONTEXT.md: `docs(planning): capture phase {N} discussion decisions`
 
+**Memory capture:** Reference `skills/shared/memory-capture.md` — check researcher output for `<memory_suggestion>` blocks and save any reusable knowledge discovered during research.
+
 ---
 
 ## Anti-Patterns