@lavralabs/lavra 0.7.0

package/plugins/lavra/gemini/commands/lavra-brainstorm.toml

@@ -0,0 +1,391 @@
+# Generated by lavra v0.6.0
+# DO NOT EDIT - changes will be overwritten on next install
+
+description = "Explore requirements and approaches through collaborative dialogue before planning"
+
+prompt = """
+
+<objective>
+Brainstorm a feature or improvement through collaborative dialogue. Brainstorming helps answer **WHAT** to build, surfaces gray areas that need decisions, and breaks the vision into implementation phases filed as child beads. It precedes `/lavra-design`, which answers **HOW** to build each phase.
+</objective>
+
+<execution_context>
+<raw_argument> #{{args}} </raw_argument>
+
+**First, determine if the argument is a bead ID or a feature description:**
+
+Check if the argument matches a bead ID pattern:
+- Pattern: lowercase alphanumeric segments separated by hyphens (e.g., `bikiniup-xhr`, `beads-123`, `explore-auth2`)
+- Regex: `^[a-z0-9]+-[a-z0-9]+(-[a-z0-9]+)*$`
+
+**If the argument matches a bead ID pattern:**
+
+1. Try to load the bead using the Bash tool:
+   ```bash
+   bd show "#$ARGUMENTS" --json
+   ```
+
+2. If the bead exists:
+   - Extract the `title` and `description` fields from the JSON array (first element)
+   - Example: `bd show "#{{args}}" --json | jq -r '.[0].title'` and `jq -r '.[0].description'`
+   - Use the bead's title and description as context for brainstorming
+   - Announce: "Brainstorming bead #{{args}}: {title}"
+   - Continue brainstorming to explore the idea more deeply
+
+3. If the bead doesn't exist (command fails):
+   - Report: "Bead ID '#{{args}}' not found. Please check the ID or provide a feature description instead."
+   - Stop execution
+
+**If the argument does NOT match a bead ID pattern:**
+- Treat it as a feature description: `<feature_description>#{{args}}</feature_description>`
+- Continue with the workflow
+
+**If the argument is empty:**
+- Ask: "What would you like to explore? Please provide either a bead ID (e.g., 'bikiniup-xhr') or describe the feature, problem, or improvement you're thinking about."
+
+Do not proceed until you have a clear feature description from the user.
+</execution_context>
+
+<context>
+**Note: The current year is 2026.** Use this when dating brainstorm documents.
+
+**Process knowledge:** Load the `brainstorming` skill for detailed question techniques, approach exploration patterns, and YAGNI principles.
+</context>
+
+<process>
+
+### Phase 0: Assess Requirements Clarity
+
+Evaluate whether brainstorming is needed based on the feature description.
+
+**Clear requirements indicators:**
+- Specific acceptance criteria provided
+- Referenced existing patterns to follow
+- Described exact expected behavior
+- Constrained, well-defined scope
+
+**If requirements are already clear:**
+Use **AskUserQuestion tool** to suggest: "Your requirements seem detailed enough to proceed directly to planning. Should I run `/lavra-plan` instead, or would you like to explore the idea further?"
+
+### Phase 1: Understand the Idea
+
+#### 1.1 Repository Research (Lightweight)
+
+Run a quick repo scan to understand existing patterns:
+
+- Task repo-research-analyst("Understand existing patterns related to: <feature_description>")
+
+Focus on: similar features, established patterns, CLAUDE.md or AGENTS.md guidance.
+
+#### 1.2 Check Existing Knowledge
+
+Search for relevant knowledge from past sessions:
+
+```bash
+.lavra/memory/recall.sh "{keywords from feature description}"
+```
+
+Present any relevant entries that might inform the brainstorm.
+
+#### 1.3 Collaborative Dialogue (Deep Questioning)
+
+Use the **AskUserQuestion tool** to ask questions **one at a time**. Keep asking until the picture is clear -- do not rush this phase.
+
+**Guidelines (see `brainstorming` skill for detailed techniques):**
+- Prefer multiple choice when natural options exist
+- Start broad, then narrow progressively
+
+**Questioning progression:**
+
+1. **Vision exploration** (start here):
+   - "What does success look like when this is done?"
+   - "Who is this for? What's their day-to-day context?"
+   - "What triggered this idea -- a pain point, an opportunity, or something else?"
+
+2. **Constraint discovery** (narrow down):
+   - Tech stack preferences or requirements
+   - Timeline pressure (is this urgent or exploratory?)
+   - Team size and skill distribution
+   - Existing patterns in the codebase to follow or avoid
+   - Dependencies on other systems or features
+
+3. **Scope sharpening** (lock boundaries):
+   - "What should this explicitly NOT do?"
+   - "What's the smallest version that would still be valuable?"
+   - Validate assumptions explicitly: "I'm assuming X. Is that correct?"
+
+4. **Success criteria** (close the loop):
+   - "How will you know this feature is working well?"
+   - "What's the happy path? What's the worst failure mode?"
+
+**Exit condition:** Continue until the picture is clear (vision, constraints, scope, and success criteria are all addressed) OR user says "proceed."
+
+### Phase 2: Gray Area Identification
+
+Scan the entire conversation so far for ambiguities where reasonable developers might choose differently.
+
+**2.1 Present gray areas:**
+
+Use **AskUserQuestion tool** to present a numbered list:
+
+"Before we explore approaches, I see these areas where we need a decision:
+
+1. {Gray area 1} -- e.g., should X be synchronous or async?
+2. {Gray area 2} -- e.g., do we handle Y at the API layer or the client?
+3. {Gray area 3} -- ...
+
+Which would you like to discuss? (Pick numbers, or 'all', or 'skip' if none matter yet)"
+
+**2.2 Explore selected gray areas:**
+
+For each selected gray area, ask 3-4 targeted questions using **AskUserQuestion tool** (one at a time) to drive toward a decision.
+
+**2.3 Capture decisions immediately:**
+
+After each gray area is resolved, log it right away -- do not wait for the capture phase:
+
+```bash
+bd comments add {BEAD_ID} "DECISION: {gray area} -- chose {option} because {rationale}. Alternatives considered: {list}"
+```
+
+If no bead exists yet, queue the decisions for Phase 5.
+
+### Phase 3: Explore Approaches
+
+Propose **2-3 concrete approaches** based on research, conversation, and resolved gray areas.
+
+For each approach, provide:
+- Brief description (2-3 sentences)
+- Pros and cons
+- When it's best suited
+
+Lead with your recommendation and explain why. Apply YAGNI -- prefer simpler solutions.
+
+Use **AskUserQuestion tool** to ask which approach the user prefers.
+
+### Phase 4: Phase Identification
+
+Based on requirements, decisions, and the chosen approach, identify logical implementation phases.
+
+**4.1 Present phases:**
+
+Use **AskUserQuestion tool** to present the proposed phases:
+
+"Based on our discussion, here are the implementation phases I'd suggest:
+
+Phase 1: {title} -- {one-line scope}
+Phase 2: {title} -- {one-line scope}
+Phase 3: {title} -- {one-line scope}
+
+Would you like to reorder, merge, split, or adjust any of these?"
+
+**4.2 File phases as child beads:**
+
+After confirmation, create the epic bead (if not already created) and file each phase:
+
+```bash
+# Create epic bead if it doesn't exist yet
+bd create --title="Brainstorm: {topic}" --type=epic --labels=brainstorm -d "{structured description -- see Phase 5}"
+
+# File each phase as a child bead
+bd create --title="Phase 1: {title}" --description="{scope + goals + locked decisions relevant to this phase}" --type=task --parent={EPIC_BEAD_ID}
+bd create --title="Phase 2: {title}" --description="{scope + goals + locked decisions relevant to this phase}" --type=task --parent={EPIC_BEAD_ID}
+bd create --title="Phase 3: {title}" --description="{scope + goals + locked decisions relevant to this phase}" --type=task --parent={EPIC_BEAD_ID}
+```
+
+Each phase bead description should include:
+- Scope: what's in and out for this phase
+- Goals: what's done when this phase is complete
+- Locked decisions: relevant decisions from Phase 2 that apply to this phase
+
+### Phase 5: Capture the Design
+
+Update the epic bead description with structured requirements. **Size budget: 80 lines max.** If the description exceeds 80 lines, it has too much scope -- split into more phases or move detail into child beads.
+
+```bash
+bd update {EPIC_BEAD_ID} -d "$(cat <<'EOF'
+## Vision
+{What success looks like -- 1-2 sentences}
+
+## Requirements
+1. {Must-have requirement}
+2. {Must-have requirement}
+3. ...
+
+## Non-Requirements
+- {Explicitly excluded scope}
+- {Things this does NOT do}
+
+## Locked Decisions
+{Decisions that MUST be honored during implementation. These are non-negotiable.}
+- {Decision from gray area exploration}
+- {Decision from gray area exploration}
+
+## Agent Discretion
+{Areas where the implementing agent can choose details. These are flexible.}
+- {Area where agent can decide approach}
+- {Area where agent can choose implementation details}
+
+## Deferred
+{Items raised during brainstorm but explicitly out of scope for now. Each becomes a backlog bead.}
+- {Deferred item -- rationale for deferral}
+- {Deferred item -- rationale for deferral}
+
+## Phases
+- {PHASE_1_BEAD_ID}: Phase 1 -- {title}
+- {PHASE_2_BEAD_ID}: Phase 2 -- {title}
+- {PHASE_3_BEAD_ID}: Phase 3 -- {title}
+EOF
+)"
+```
+
+Log remaining knowledge comments:
+
+```bash
+bd comments add {EPIC_BEAD_ID} "INVESTIGATION: {key findings from exploration}"
+bd comments add {EPIC_BEAD_ID} "FACT: {constraints discovered}"
+bd comments add {EPIC_BEAD_ID} "PATTERN: {patterns to follow}"
+```
+
+### Phase 6: Sharpen
+
+**6.0 Pre-Sharpen: Adversarial Audit**
+
+Before recommending a scope mode, run these checks (use Bash/Grep/Read/Glob as needed):
+
+**A. Premise Challenge**
+- Is this the right problem? Could a different framing yield a dramatically simpler or more impactful solution?
+- What is the actual user/business outcome? Is this the most direct path, or is it solving a proxy problem?
+- What happens if we do nothing? Real pain point or hypothetical one?
+
+**B. Existing Code Leverage**
+- For every sub-problem in the proposed phases, identify existing code that already partially or fully solves it.
+- Note any phase that rebuilds something already present — and whether the plan reuses or rebuilds it.
+
+**C. Dream State Mapping**
+
+Map the trajectory in one table:
+```
+CURRENT STATE       → THIS PLAN DELIVERS       → 12-MONTH IDEAL
+[describe briefly]    [describe delta]            [describe target]
+```
+Does this plan move toward the 12-month ideal or away from it?
+
+**D. Temporal Interrogation** (skip for SCOPE REDUCTION)
+
+Walk through implementation in your head and surface unresolved decisions now:
+- Hour 1 (foundations): What must the implementer know before writing a line?
+- Hours 2–3 (core logic): What ambiguities will they hit mid-build?
+- Hours 4–5 (integration): What will surprise them?
+- Hour 6+ (polish/tests): What will they wish they'd planned for?
+
+Log key findings:
+```bash
+bd comments add {EPIC_BEAD_ID} "INVESTIGATION: Pre-sharpen audit -- {key findings}"
+```
+
+Brainstorming expands possibilities. This phase forces contraction. Of everything discussed, what is the MVP that proves the thesis?
+
+**6.1 Evaluate scope and recommend a mode:**
+
+Review the full conversation -- the vision, requirements, phases, and locked decisions -- and recommend one of three modes:
+
+- **SCOPE EXPANSION**: "The 10-star version of this is..." -- recommend when the initial idea is too small, when there is an obvious larger opportunity the user has not considered, or when the phases feel like a fraction of what is needed.
+- **HOLD SCOPE**: "The scope is right. Here is how to make it bulletproof." -- recommend when the idea is well-sized, when the phases cover the problem space without excess, and when the locked decisions are sound.
+- **SCOPE REDUCTION**: "Strip to essentials. The 80/20 version is..." -- recommend when feature creep is happening, when phases have grown beyond what a first cut needs, or when nice-to-haves have crept into must-haves.
+
+**Mode-specific depth (run before presenting your recommendation):**
+
+- **SCOPE EXPANSION**: Articulate (a) the 10x version — what's 10x more ambitious for 2x effort? (b) the platonic ideal — what would the best engineer with perfect taste build, starting from user experience not architecture? (c) at least 3 delight opportunities — adjacent 30-min improvements that make users think "nice, they thought of that."
+- **HOLD SCOPE**: Check if the plan touches >8 files or introduces >2 new classes/services. If yes, challenge whether the goal can be achieved with fewer moving parts. Identify minimum change set.
+- **SCOPE REDUCTION**: Identify the absolute minimum that ships core value. Explicitly list what becomes a follow-up.
+
+Use **AskUserQuestion tool** to present your recommendation with a brief rationale (2-3 sentences) and let the user confirm or pick a different mode.
+
+**6.2 Force the hard questions:**
+
+Based on the chosen mode, ask these questions using **AskUserQuestion tool** (one at a time):
+
+1. "What is the smallest version that proves this works?"
+2. "What can we defer without losing the core value?"
+3. "Is this solving a real problem or an imagined one?"
+4. "If we could only ship 3 of these {N} items, which 3?"
+
+Skip questions that were already answered during earlier phases. The goal is pressure-testing, not repetition.
+
+**6.3 Apply the sharpening:**
+
+Based on the user's answers:
+
+- If **SCOPE EXPANSION**: add or revise phases to capture the larger vision. Update the epic description.
+- If **HOLD SCOPE**: validate that nothing needs trimming. Tighten phase descriptions if needed.
+- If **SCOPE REDUCTION**: remove or defer phases. Move deferred items to the `## Deferred` section in the epic description with rationale. Close any child beads that are no longer in scope.
+
+**6.4 Log scope decisions:**
+
+```bash
+bd comments add {EPIC_BEAD_ID} "DECISION: Scope mode: {EXPANSION|HOLD|REDUCTION} -- {rationale}. Deferred items: {list or 'none'}"
+```
+
+If individual items were cut or deferred, log each:
+
+```bash
+bd comments add {EPIC_BEAD_ID} "DECISION: Deferred {item} -- not needed for MVP. Can revisit after Phase {N} proves the thesis."
+```
+
+### Phase 7: Handoff
+
+Use **AskUserQuestion tool** to present next steps:
+
+**Question:** "Brainstorm captured as {EPIC_BEAD_ID} with {N} phases filed as child beads. What would you like to do next?"
+
+**Options:**
+1. **Proceed to design** -- Run `/lavra-design {EPIC_BEAD_ID}` to design all phases
+2. **Refine further** -- Continue exploring
+3. **Done for now** -- Return later
+
+</process>
+
+<success_criteria>
+- Feature description is clear and well-understood (vision, constraints, scope, success criteria)
+- Gray areas were identified and resolved with the user
+- 2-3 approaches were explored with pros/cons
+- An epic bead was created with structured description (vision, requirements, non-requirements, locked decisions, phases)
+- Implementation phases were identified, confirmed, and filed as child beads
+- Key decisions captured as DECISION comments immediately when resolved
+- Scope was sharpened: expansion/hold/reduction mode chosen, hard questions answered, phases adjusted if needed
+- Scope decisions logged as DECISION comments
+- Additional knowledge logged as INVESTIGATION/FACT/PATTERN comments
+- User was offered clear next steps (with `/lavra-design` as primary option)
+</success_criteria>
+
+<guardrails>
+- **Stay focused on WHAT, not HOW** - Implementation details belong in the plan
+- **Ask one question at a time** - Don't overwhelm
+- **Apply YAGNI** - Prefer simpler approaches
+- **Keep outputs concise** - 200-300 words per section max
+- NEVER CODE! Just explore and document decisions.
+</guardrails>
+
+<handoff>
+```
+Brainstorm complete!
+
+Epic: {EPIC_BEAD_ID} - Brainstorm: {topic}
+
+Phases:
+- {PHASE_1_BEAD_ID}: Phase 1 -- {title}
+- {PHASE_2_BEAD_ID}: Phase 2 -- {title}
+- {PHASE_3_BEAD_ID}: Phase 3 -- {title}
+
+Locked decisions:
+- [Decision 1]
+- [Decision 2]
+
+Knowledge captured: {count} entries logged to knowledge.jsonl
+
+Next: Run `/lavra-design {EPIC_BEAD_ID}` to design all phases.
+```
+</handoff>
+
+"""