discuss

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:
3. Warn: "Phase {N} already has plans. Decisions from this discussion won't retroactively change them. Consider re-planning with /pbr:plan-phase {N} after."
4. 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

1. If Cancel: stop and display the existing PROJECT.md path.
2. 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:
3. Locked Decisions table: all decisions the user made (not "Let Claude decide")
4. User Constraints: budget, team, timeline, hosting from the conversation
5. Deferred Ideas: anything explicitly ruled out for this project
6. Claude's Discretion: decisions marked "Let Claude decide"
7. If Append mode: merge new decisions with existing PROJECT.md ## Context content

CRITICAL: Write the discussion results to PROJECT.md NOW.

1. Write to .planning/PROJECT.md under the ## Context section with subsections:
2. ### Locked Decisions
3. ### User Constraints
4. ### 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:
2. Phase name and description
3. Goal / objective
4. Requirements to satisfy
5. Success criteria
6. Dependencies on prior phases

1. Prior SUMMARY.md files — Scan .planning/phases/ for phases with lower numbers that have SUMMARY.md files. Read their frontmatter to understand:
2. What's already been built (provides field)
3. What technologies are in use (tech_stack field)
4. What patterns have been established (patterns field)
5. What decisions were already made (key_decisions field)

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

1. CONTEXT.md (if exists in the phase directory) — Check if a prior discussion already happened
2. If CONTEXT.md exists, inform the user and: