/discuss

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

Step 0 — Immediate Output

**Before ANY tool calls**, display this banner:

╔══════════════════════════════════════════════════════════════╗
║  PLAN-BUILD-RUN ► DISCUSSION                                 ║
╚══════════════════════════════════════════════════════════════╝

Then proceed to Step 1.

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

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.

---

Flow

Step 1: Parse Phase Number and Check for Existing Plans

**CRITICAL (hook-enforced): Write .active-skill NOW.** Write the text "discuss" to `.planning/.active-skill` using the Write tool.

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:progress` to see available phases."

**Phase directory resolution:** 1. List directories in `.planning/phases/` 2. Find directory matching pattern `{NN}-*` where NN matches the phase number 3. If not found, check ROADMAP.md for the phase name 4. If still not found, display:

╔══════════════════════════════════════════════════════════════╗
║  ERROR                                                       ║
╚══════════════════════════════════════════════════════════════╝

Phase {N} not found.

**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-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")
• Use