@sienklogic/plan-build-run 2.21.1 → 2.21.2

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

@@ -21,21 +21,33 @@ Then proceed to Step 1.
 
 ## Behavior
 
-1. **Parse arguments**: Extract `--port N` from the user's input. Default to `3000`.
+1. **Parse arguments**: Extract `--port N` from the user's input. Default to `3141`.
 
-2. **Check dependencies**: Check if `${CLAUDE_PLUGIN_ROOT}/dashboard/node_modules/` exists. If not, run:
-   ```
-   npm install --prefix ${CLAUDE_PLUGIN_ROOT}/dashboard
-   ```
+2. **Locate dashboard**: The dashboard lives at the **repository root** `dashboard/` directory (NOT under `${CLAUDE_PLUGIN_ROOT}`). Resolve the repo root from `<cwd>` — for PBR's own repo this is the project root; for installed plugins, use `git rev-parse --show-toplevel` or walk up from `${CLAUDE_PLUGIN_ROOT}` to find `dashboard/`.
+
+3. **Check dependencies**: Check if `<repo-root>/dashboard/server/node_modules/` exists. If not, run:
 
-3. **Launch dashboard**: Run in background via Bash:
+   ```bash
+   npm run dashboard:install --prefix <repo-root>
    ```
-   node ${CLAUDE_PLUGIN_ROOT}/dashboard/bin/cli.js --dir <cwd> --port <port> &
+
+4. **Launch dashboard**: Run in background via Bash:
+
+   ```bash
+   node <repo-root>/dashboard/bin/cli.cjs --dir <cwd> --port <port> &
    ```
+
    Use `&` to background the process so it doesn't block the session.
 
-4. **Output to user**:
+5. **Verify startup**: After launching, check the process is responding:
+
+   ```bash
+   curl -s -o /dev/null -w "%{http_code}" http://localhost:<port>/
    ```
+
+6. **Output to user**:
+
+   ```text
    Dashboard running at http://localhost:<port>
    Open this URL in your browser to view your project's planning state.
    ```
@@ -43,4 +55,4 @@ Then proceed to Step 1.
 ## Notes
 
 - If the port is already in use, the dashboard will fail to start — suggest the user try a different port with `--port`.
-- The dashboard watches `.planning/` for live updates via SSE.
+- The dashboard watches `.planning/` for live updates via WebSockets.

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)