@sienklogic/plan-build-run 2.11.0 → 2.12.1

package/plan-build-run/skills/discuss/SKILL.md

@@ -0,0 +1,489 @@
+---
+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, 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
+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:
+   - Phase name and description
+   - Goal / objective
+   - Requirements to satisfy
+   - Success criteria
+   - Dependencies on prior phases
+
+2. **Prior SUMMARY.md files** — Scan `.planning/phases/` for phases with lower numbers that have SUMMARY.md files. Read their frontmatter to understand:
+   - What's already been built (`provides` field)
+   - What technologies are in use (`tech_stack` field)
+   - 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. **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`:
+     question: "Phase {N} already has a CONTEXT.md from a prior discussion. How should we handle it?"
+
+   Handle responses:
+   - "Overwrite": Replace CONTEXT.md entirely with new decisions
+   - "Append": Add new decisions below existing ones, marked as "Amendment ({date})"
+   - "Cancel": Stop the discussion, keep existing CONTEXT.md
+
+### Step 2.5: Open Exploration Phase
+
+Before jumping into specific gray areas, give the user space to share their mental model unprompted.
+
+1. **Present the phase goal** (from ROADMAP.md) and ask an open question:
+   - "Before we get into specifics — what's your mental model of how this phase should work? What excites you about it? What concerns you?"
+
+2. **Follow the user's response with 2-3 domain-aware follow-ups** from `skills/shared/domain-probes.md`:
+   - Match what the user mentioned to the relevant domain tables
+   - Pick the 2-3 most insightful probes based on what they said, not a generic checklist
+   - Ask them conversationally, not as a numbered list
+
+3. **Surface implications** from what the user shared:
+   - "You mentioned X — that usually means we'd need Y. Is that part of your vision?"
+   - Connect their ideas to concrete technical or design consequences
+   - Flag anything that would affect scope, complexity, or dependencies
+
+4. **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.
+
+### Step 3: Identify Gray Areas
+
+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:**
+1. Look at the phase requirements — where are there multiple valid approaches?
+2. Look at prior phase decisions — where might this phase need to diverge?
+3. Look at the success criteria — what's ambiguous about how to satisfy them?
+4. Consider the user's likely pain points — what would they want a say in?
+
+**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.
+
+### 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):**
+
+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:**
+- Each option must be concrete and implementable
+- Include honest pros/cons (don't bias toward one option)
+- "Let Claude decide" should always be available as a choice
+- 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 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.
+
+**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.**
+1. **Scope boundary**: "Should {feature} also handle {edge case}?"
+   Use the **yes-no** pattern — this is a binary decision.
+
+**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:**
+- Ask all 4 questions for each area
+- Record exact answers (don't paraphrase)
+- If the user gives a short answer, capture it as-is
+- If the user says "you decide" on a follow-up, move that specific sub-decision to Claude's Discretion
+
+**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.
+
+### 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 `${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 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:
+```
+Phase {N} discussion: .planning/phases/{NN}-{slug}/CONTEXT.md ({count} locked, {count} deferred, {count} discretion)
+```
+
+This creates a pointer so `/pbr:resume-work` and `progress-tracker.js` know that phase-specific decisions exist and where to find them.
+
+### Step 8: Confirm and Route
+
+After writing CONTEXT.md, display branded output per `@references/ui-brand.md`:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  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-phase {N}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+**Also available:**
+- `/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
+
+### LOCKED Decisions
+
+These come from:
+- User selecting a specific option (not "Let Claude decide")
+- User answering follow-up questions with specific preferences
+- User volunteering a strong opinion during discussion
+
+**The planner MUST:**
+- Implement exactly as the user specified
+- Not modify, optimize, or "improve" the decision
+- Note in the plan if research suggests a different approach
+- Still follow the locked decision regardless
+
+### DEFERRED Ideas
+
+These come from:
+- User explicitly saying "not now" or "later"
+- Ideas that are out of scope per ROADMAP.md
+- User rejecting an option but saying it's a good idea for later
+
+**The planner MUST NOT:**
+- Include deferred ideas in the plan
+- Sneak deferred ideas in as "nice to have" tasks
+- Combine deferred ideas with in-scope work
+
+### CLAUDE'S DISCRETION
+
+These come from:
+- User selecting "Let Claude decide"
+- User saying "I don't care" or "whatever you think"
+- Follow-up questions answered with "you decide"
+
+**The planner MAY:**
+- Choose any reasonable approach
+- Use research results to inform the choice
+- Change their mind during planning if they learn something new
+- Must document their choice and rationale in the plan
+
+---
+
+## Edge Cases
+
+### Phase already has CONTEXT.md
+- 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
+
+### Phase already has plans
+- Handled by Step 1 — warn but do not block
+- See Step 1 "Check for existing plans" for the exact warning message
+
+### 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-phase {N+1}`."
+
+### User disagrees with all options
+- Ask: "What would you prefer instead?" — this is freeform text, do NOT use AskUserQuestion.
+- Accept any answer and lock it as a decision.
+- The options were suggestions, not constraints
+
+### User wants to skip follow-ups
+- If user says "that's enough" or "skip the details", respect that
+- Write what you have — partial follow-ups are fine
+- Mark missing follow-up areas as Claude's Discretion
+
+---
+
+## 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-phase` runs.
+
+---
+
+## Git Integration
+
+Reference: `skills/shared/commit-planning-docs.md` for the standard commit pattern.
+
+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
+
+1. **DO NOT** bias the user toward a particular option
+2. **DO NOT** skip the follow-up questions (unless the user asks to skip)
+3. **DO NOT** paraphrase the user's decisions — capture them verbatim
+4. **DO NOT** add your own opinions to LOCKED decisions
+5. **DO NOT** mark something as Claude's Discretion unless the user explicitly chose that
+6. **DO NOT** include implementation details in CONTEXT.md — it captures WHAT, not HOW
+7. **DO NOT** skip the deferred ideas section — this prevents scope creep later
+8. **DO NOT** present more than 4 options per gray area — decision fatigue is real

package/plan-build-run/skills/discuss/templates/CONTEXT.md.tmpl

@@ -0,0 +1,61 @@
+<!-- Source: discuss/SKILL.md | Purpose: Template for the CONTEXT.md file written after a phase discussion -->
+
+# Phase {N} Context
+
+**Created by:** /pbr:discuss-phase {N}
+**Date:** {ISO date}
+
+## Decision Summary
+
+<!-- Compact digest for agent prompt injection. ~300 tokens max. -->
+<!-- Agents: Read the full sections below only if you need scope/quality/integration details. -->
+
+**Locked:**
+- {Decision title}: {User's choice in one phrase}
+- {Decision title}: {User's choice in one phrase}
+
+**Deferred (excluded):** {Comma-separated list of deferred idea titles, or "None"}
+
+**Discretion:** {Comma-separated list of discretion area titles, or "None"}
+
+## Decisions (LOCKED -- must implement exactly as specified)
+
+These decisions are NON-NEGOTIABLE during planning. If research suggests a different approach,
+the planner must use the locked decision and note the discrepancy in the plan.
+
+- [ ] **{Decision title}** -- {User's exact choice and reasoning}
+  - Scope: {Any scope boundaries from follow-ups}
+  - Quality: {Quality level from follow-ups}
+  - Integration: {Integration notes from follow-ups}
+  - Notes: {Any additional context}
+
+- [ ] **{Decision title}** -- {User's exact choice and reasoning}
+  ...
+
+## Deferred Ideas (EXCLUDED -- do not plan these)
+
+These ideas were discussed but explicitly excluded from this phase.
+They may be addressed in future phases or milestones.
+
+- **{Idea}** -- {Why deferred}
+- **{Idea}** -- {Why deferred}
+
+## Claude's Discretion (OPEN -- Claude decides during planning)
+
+These areas were identified as gray areas but the user chose to let Claude decide.
+The planner has freedom here but should document their choices.
+
+- **{Area}** -- {What Claude can choose, any constraints mentioned}
+- **{Area}** -- {What Claude can choose, any constraints mentioned}
+
+## User's Vision Summary
+
+{2-3 sentences capturing how the user imagines this phase. This should reflect
+the user's mental model, not a technical specification. Write in the user's voice
+where possible, quoting key phrases they used.}
+
+## User's Concerns
+
+Things the user raised during discussion that should inform planning:
+
+- **{Concern}** -- {Context from the conversation}

package/plan-build-run/skills/discuss/templates/decision-categories.md

@@ -0,0 +1,9 @@
+<!-- Source: discuss/SKILL.md | Purpose: Reference table of gray area categories for phase discussions -->
+
+| Category | Example Gray Areas |
+|----------|-------------------|
+| **UI/UX choices** | Layout approach, component library, responsive strategy, accessibility level |
+| **Architecture decisions** | State management approach, API design style, database schema trade-offs |
+| **Edge case behavior** | What happens on failure, empty states, concurrent access, rate limiting |
+| **Technology selections** | Which library for X, build tool choice, testing framework preference |
+| **Feature scope boundaries** | MVP vs full feature, what to include vs defer, depth of implementation |

package/plan-build-run/skills/discuss/templates/project-CONTEXT.md.tmpl

@@ -0,0 +1,19 @@
+<!-- Source: begin/SKILL.md | Purpose: Template for PROJECT.md ## Context section -->
+
+## Context
+
+### Locked Decisions
+
+| Decision | Rationale | Source |
+|----------|-----------|--------|
+| {decision} | {rationale} | {questioning/research/user} |
+
+### User Constraints
+
+{user_constraints_list}
+
+### Deferred Ideas
+
+| Idea | Reason Deferred |
+|------|-----------------|
+| {idea} | {reason} |