Discusses planning phases to identify ambiguities, capture decisions in CONTEXT.md, and lock them before plan generation. Supports phase numbers or --project mode.
From pbrnpx claudepluginhub sienklogic/plan-build-run --plugin pbrThis skill is limited to using the following tools:
templates/CONTEXT.md.tmpltemplates/decision-categories.mdSearches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Ingests video/audio from files, URLs, RTSP, desktop; indexes/searches moments with timestamps/clips; transcodes/edits timelines (subtitles/overlays/dubbing); generates assets and live alerts.
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.
Before ANY tool calls, display this banner:
╔══════════════════════════════════════════════════════════════╗
║ PLAN-BUILD-RUN ► DISCUSSION ║
╚══════════════════════════════════════════════════════════════╝
Then proceed to Step 1.
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).
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.
Parse $ARGUMENTS:
--project: enter PROJECT mode (see Step 1-project below). Skip Steps 2-8.Validation (PHASE mode):
3.1)/pbr:status to see available phases."Phase directory resolution:
.planning/phases/{NN}-* where NN matches the phase number╔══════════════════════════════════════════════════════════════╗
║ ERROR ║
╚══════════════════════════════════════════════════════════════╝
Phase {N} not found.
**To fix:** Run `/pbr:status` to see available phases.
Check for existing plans (after resolving the phase directory):
PLAN.md or PLAN-*.md files in the phase directory/pbr:plan {N} after."When invoked with --project, discuss project-level cross-cutting decisions.
This mode writes to .planning/CONTEXT.md (project-level), NOT a phase directory.
Check for existing project CONTEXT.md:
.planning/CONTEXT.md exists.skills/shared/gate-prompts.md):
question: "Project CONTEXT.md already exists. How should we handle it?"
options: Overwrite | Append | CancelLoad project context:
.planning/PROJECT.md (if exists) — project vision and scope.planning/REQUIREMENTS.md (if exists) — requirements for constraint awareness.planning/CONTEXT.md (if exists) — current locked decisions (for Append mode)Run gray areas for project-level decisions (Steps 2.5-5 pattern):
Write project CONTEXT.md:
${CLAUDE_SKILL_DIR}/templates/project-CONTEXT.md.tmpl.planning/CONTEXT.mdUpdate STATE.md pointer: Add under Accumulated Context:
Project context: .planning/CONTEXT.md ({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.md written — locked decisions will auto-sync to CLAUDE.md
Skip to Cleanup step. Do NOT run Steps 2-8 of the phase flow.
Read the following files to understand what this phase needs to accomplish:
ROADMAP.md — Find the phase entry. Extract:
Prior SUMMARY.md files — Scan .planning/phases/ for phases with lower numbers that have SUMMARY.md files. Read their frontmatter to understand:
provides field)tech_stack field)patterns field)key_decisions field)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.
CONTEXT.md (if exists in the phase directory) — Check if a prior discussion already happened
skills/shared/gate-prompts.md:
question: "Phase {N} already has a CONTEXT.md from a prior discussion. How should we handle it?"Handle responses:
Before jumping into specific gray areas, give the user space to share their mental model unprompted.
Present the phase goal (from ROADMAP.md) and ask an open question:
Follow the user's response with 2-3 domain-aware follow-ups from skills/shared/domain-probes.md:
Surface implications from what the user shared:
Let the conversation reveal gray areas naturally. The user's responses here often surface the real gray areas better than top-down analysis. Carry any themes, concerns, or preferences forward into Step 3.
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 ${CLAUDE_SKILL_DIR}/templates/decision-categories.md for the category reference table.
How to identify gray areas:
Important: Do NOT identify gray areas that are purely implementation details (e.g., variable naming, file organization). Focus on areas that affect user experience, system behavior, or long-term maintainability.
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: question: "Gray Area {N}: {Title} — {Why this matters}" header: "Decision" options: (generate 2-4 concrete options from analysis, each with pros/cons in the description) - label: "{Option A}" description: "{Pros: ..., Cons: ...}" - label: "{Option B}" description: "{Pros: ..., Cons: ...}" - ...up to 4 options total, with "Let Claude decide" always as the last option - label: "Let Claude decide" description: "Mark as Claude's Discretion" multiSelect: false
If more than 3 concrete options exist for a gray area, present only the top 3 plus "Let Claude decide" (max 4 total). Mention the omitted option(s) in the question text.
Rules for presenting options:
For each gray area where the user made a decision (not "Let Claude decide"), ask 4 follow-up questions to fully capture their intent.
CRITICAL — STOP: Do NOT skip ANY of the 4 follow-up areas below. All 4 MUST be asked for each gray area where the user made a decision.
Follow-up question types:
CRITICAL — STOP: Do NOT skip this follow-up area.
CRITICAL — STOP: Do NOT skip this follow-up area. 2. Quality level: "How polished should this be?" Do NOT use AskUserQuestion — this is freeform. Let the user describe their quality expectations in their own words.
CRITICAL — STOP: Do NOT skip this follow-up area. 3. Integration: "How should this interact with {existing component}?" Do NOT use AskUserQuestion — this is freeform. The answer depends on the specific component and context.
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?" Use the yes-no pattern: question: "Design {feature} to support {future need}, or keep it simple for now?" options: - label: "Future-proof" description: "Add extensibility for {future need}" - label: "Keep simple" description: "Build only what's needed now"
Rules for follow-ups:
Completion check: After all follow-up questions for all gray areas, verify that all 4 follow-up areas produced output for each decided gray area. If any area was missed, go back and ask it before proceeding to Step 6.
During the conversation, the user may mention ideas they want but not in this phase. Track these separately:
Write the CONTEXT.md file to the phase directory:
Path: .planning/phases/{NN}-{phase-name}/CONTEXT.md
Content:
Read ${CLAUDE_SKILL_DIR}/templates/CONTEXT.md.tmpl for the template structure.
Placeholders to fill:
{N} -- the phase number{ISO date} -- today's date in ISO format{Decision title} / {User's exact choice and reasoning} -- from Step 4-5 decisions{Idea} / {Why deferred} -- from Step 6 deferred ideas{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 discussionDecision 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.
Update .planning/STATE.md's ## Accumulated Context section to add a reference to the new CONTEXT.md:
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.
After writing CONTEXT.md, display branded output:
╔══════════════════════════════════════════════════════════════╗
║ PLAN-BUILD-RUN ► DISCUSSION CAPTURED ✓ ║
╚══════════════════════════════════════════════════════════════╝
**Phase {N}: {name}**
Decisions: {count} locked, {count} deferred, {count} discretion
╔══════════════════════════════════════════════════════════════╗
║ ▶ NEXT UP ║
╚══════════════════════════════════════════════════════════════╝
**Plan this phase** — your decisions will be honored
`/pbr:plan {N}`
<sub>`/clear` first → fresh context window</sub>
**Also available:**
- `/pbr:status` — see project status
- `/pbr:explore` — explore ideas further
These come from:
The planner MUST:
These come from:
The planner MUST NOT:
These come from:
The planner MAY:
skills/shared/gate-prompts.md (same as Step 2)/pbr:discuss {N+1}."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.
Reference: skills/shared/commit-planning-docs.md for the standard commit pattern.
If planning.commit_docs: true in config.json:
docs(planning): capture phase {N} discussion decisions