opencode-goopspec 0.1.2 → 0.1.4

package/commands/goop-discuss.md

@@ -1,138 +1,434 @@
 ---
 name: goop-discuss
-description: Capture user vision before planning - the discovery conversation
+description: Capture user vision through discovery interview before planning
+phase: discuss
+next-step: "When discovery is complete, create the blueprint"
+next-command: /goop-plan
+alternatives:
+  - command: /goop-research
+    when: "If there are unknowns to investigate first"
+  - command: /goop-quick
+    when: "For small, single-file tasks that don't need planning"
 ---
 
-# GoopSpec Discuss
+# /goop-discuss
 
-Capture user vision and gather requirements through structured conversation before formal planning.
+**Start the Discovery Interview.** Capture vision, requirements, constraints, and risks before planning begins.
 
 ## Usage
 
+```bash
+/goop-discuss [brief description of what you want to build]
 ```
-/goop-discuss [brief description]
+
+## Core Purpose
+
+The Discovery Interview is a **mandatory gate** before planning. It ensures requirements are "nailed down" before any work begins.
+
+```
++================================================================+
+|  NO PLANNING WITHOUT DISCOVERY.                                 |
+|  The interview ensures we build the RIGHT thing.                |
+|  Skipping discovery leads to scope creep and rework.            |
++================================================================+
 ```
 
-## Workflow Position
+## Orchestrator Role
+
+**YOU conduct the interview directly.** Do NOT spawn agents for conversation.
+
+Why: The interview builds shared understanding. That understanding stays in YOUR context and informs how you delegate. Spawning for conversation fragments knowledge.
+
+## The Six Questions
+
+Every discovery interview MUST answer these questions:
+
+### 1. Vision (The What)
+- What are you trying to build?
+- What problem does this solve?
+- Who is this for?
+
+### 2. Must-Haves (The Contract)
+- What are the non-negotiable requirements?
+- What MUST be delivered for this to be complete?
+- What are the acceptance criteria?
+
+### 3. Constraints (The Boundaries)
+- What stack/frameworks are we using?
+- What are the performance requirements?
+- What existing code must we integrate with?
+
+### 4. Out of Scope (The Guardrails)
+- What are we explicitly NOT building?
+- What features are deferred to later?
+
+### 5. Assumptions (The Baseline)
+- What existing functionality are we relying on?
+- What decisions have already been made?
+
+### 6. Risks (The Unknowns)
+- What could go wrong?
+- What are we uncertain about?
+- What dependencies could block us?
+
+## Tools Used
 
+| Tool | Purpose in This Command |
+|------|------------------------|
+| `goop_status` | Check current phase and project state |
+| `memory_search` | Find prior context about the project |
+| `memory_save` | Persist discovery interview results |
+| `goop_reference` | Load discovery-interview protocol |
+
+**Hook Support:** `system.transform` injects relevant memories before execution.
+
+---
+
+## Process
+
+### Phase 1: Setup
+
+**Execute these checks BEFORE any user interaction:**
+
+**1.1 Check current state:**
 ```
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│   DISCUSS   │ ──▶ │    PLAN     │ ──▶ │  RESEARCH   │
-│  (Vision)   │     │  (Intent)   │     │  (Explore)  │
-└─────────────┘     └─────────────┘     └─────────────┘
-      ↑
-(You are here)
+goop_status()
+goop_state({ action: "get" })        # NEVER read state.json directly
+Read(".goopspec/REQUIREMENTS.md")    # If exists, interview was done
 ```
 
-The Discuss phase answers: **What does the user really want?**
+**CRITICAL: Never read or edit .goopspec/state.json directly. Always use `goop_state` tool.**
 
-## What Happens
+**1.2 If REQUIREMENTS.md exists:**
 
-1. **Vision Capture** - Understand the high-level goal
-2. **Requirements Gathering** - Ask clarifying questions to understand:
-   - Functional requirements (what it should do)
-   - Non-functional requirements (performance, security, accessibility)
-   - Constraints (time, technology, compatibility)
-   - Success criteria (how to know it's done)
-3. **Scope Definition** - Identify boundaries
-4. **Priority Clarification** - Understand what matters most
-5. **Memory Search** - Check for relevant past context
+Use `question` tool:
+- header: "Existing Discovery"
+- question: "I found an existing discovery interview. How would you like to proceed?"
+- options:
+  - "Start fresh (Recommended)" — Clear previous discovery, start new interview
+  - "Review and update" — Load previous answers, modify as needed
+  - "Use existing" — Skip interview, go straight to /goop-plan
 
-## Discussion Techniques
+**1.3 Initialize if needed:**
+```bash
+mkdir -p .goopspec
+```
 
-**Ask Open-Ended Questions:**
+**1.4 Search memory for context:**
 ```
-"Can you walk me through how a user would interact with this?"
-"What happens if [edge case]?"
-"Are there any existing patterns in the codebase we should follow?"
+memory_search({ query: "project preferences architecture [user's topic]", limit: 5 })
 ```
 
-**Validate Understanding:**
+Store relevant findings - use them to skip questions you already know answers to.
+
+### Phase 2: Discovery Interview
+
+**Display stage banner:**
 ```
-"Let me make sure I understand correctly:
-- The feature should [summary]
-- It needs to handle [edge cases]
-- Success looks like [acceptance criteria]
+## 🔮 GoopSpec · Discovery Interview
+
+Let's nail down the requirements before planning.
+I'll ask six key questions to understand your needs.
 
-Is that accurate?"
+---
 ```
 
-**Challenge Assumptions:**
+**2.1 Open the conversation:**
+
+If `$ARGUMENTS` provided:
+> "You want to **[argument]**. Let me understand this better."
+
+Otherwise:
+> "What do you want to build?"
+
+**2.2 Work through the six questions:**
+
+Ask naturally, not as a checklist. Weave questions based on their responses.
+
+**Memory-first protocol:**
+Before asking ANYTHING:
+1. Check memory: `memory_search({ query: "[topic] preference" })`
+2. If found: "I recall you prefer X for this. Still true? [Y/n]"
+3. If not found: Ask, then SAVE the answer with `memory_note`
+
+**2.3 Probe for specifics:**
+
+| Vague Answer | Follow-up |
+|--------------|-----------|
+| "It should be fast" | "What's the target? Sub-100ms? Sub-1s?" |
+| "Standard auth" | "JWT? Sessions? OAuth? What's the token TTL?" |
+| "Good UX" | "What does that mean for this feature? Animations? Accessibility level?" |
+
+**2.4 Checklist tracker (internal):**
+
+Track progress through the six questions:
+- [ ] Vision defined (goal, problem, users)
+- [ ] Must-haves listed (at least 1)
+- [ ] Constraints documented (stack, performance)
+- [ ] Out of scope defined (at least 1 item)
+- [ ] Assumptions listed
+- [ ] Risks identified (at least 1 with mitigation)
+
+**2.5 Completion check:**
+
+When all six questions are answered, confirm:
+
+Use `question` tool:
+- header: "Discovery Check"
+- question: "I think I have what I need. Let me summarize..."
+- options:
+  - "Looks good, proceed" — Generate REQUIREMENTS.md
+  - "I want to add more" — Continue discussion
+  - "Start over" — Clear and restart interview
+
+### Phase 3: Generate REQUIREMENTS.md
+
+**Display stage banner:**
 ```
-"I notice you mentioned X. Have you considered Y as an alternative? 
-It might be simpler because [reason]."
+## 🔮 GoopSpec · Saving Discovery
+
+⏳ Generating REQUIREMENTS.md...
+
+---
 ```
 
-## What to Gather
+**3.1 Create REQUIREMENTS.md:**
+
+Write directly (orchestrator can write planning docs):
+
+```markdown
+# REQUIREMENTS: [Feature Name]
+
+**Generated:** [timestamp]
+**Interview Status:** Complete
+**Ready for Planning:** Yes
+
+---
+
+## Vision
 
-### Functional Requirements
-- What should the feature DO?
-- What are the inputs and outputs?
-- What are the edge cases?
-- What happens on errors?
+[Vision statement from interview]
 
-### Non-Functional Requirements
-- Performance expectations?
-- Security considerations?
-- Accessibility needs?
-- Compatibility requirements?
+**Problem Solved:** [From interview]
 
-### Context & Constraints
-- Why is this needed? What problem does it solve?
-- What existing code/patterns should be followed?
-- Any technical constraints or limitations?
-- Timeline or priority considerations?
+**Why Now:** [From interview]
 
-### Acceptance Criteria
-- How will we know it's "done"?
-- What tests should pass?
-- What should the user experience be?
+---
+
+## Must-Haves (The Contract)
 
-## Artifacts Created
+- [ ] **MH1**: [Title]
+  - [Description]
+  - **Acceptance:** [Criteria]
 
-- Understanding of requirements (informal)
-- Identified edge cases
-- Agreement on acceptance criteria
-- Technical research notes (if needed)
+- [ ] **MH2**: [Title]
+  - [Description]
+  - **Acceptance:** [Criteria]
+
+---
 
-## Example
+## Out of Scope
+
+- **[Item]** — [Reason]
+- **[Item]** — [Reason]
+
+---
 
+## Constraints
+
+### Technical Constraints
+- [Stack, frameworks, versions]
+
+### Practical Constraints
+- [Timeline, resources]
+
+---
+
+## Assumptions
+
+- **[Assumption]** — If false: [Impact]
+
+---
+
+## Risks & Mitigations
+
+| Risk | Impact | Likelihood | Mitigation |
+|------|--------|------------|------------|
+| [Risk] | [H/M/L] | [H/M/L] | [Plan] |
+
+---
+
+*Discovery interview completed. Ready for /goop-plan.*
+```
+
+**3.2 Mark interview complete (using goop_state tool):**
+
+```
+goop_state({ action: "complete-interview" })
+```
+
+This atomically updates the workflow state. **NEVER edit state.json directly.**
+
+**3.3 Save to memory:**
+
+```
+memory_save({
+  type: "note",
+  title: "Discovery: [Feature Name]",
+  content: "[Summary of key requirements and constraints]",
+  concepts: ["discovery", "requirements", "[domain]"],
+  importance: 0.7
+})
+```
+
+### Phase 4: Completion
+
+**Display completion banner:**
+
+```
+## 🔮 GoopSpec · Discovery Complete
+
+✨ Requirements captured successfully
+
+**Feature:** [Name]
+
+| Question | Status |
+|----------|--------|
+| Vision | ✓ Defined |
+| Must-Haves | ✓ [N] items |
+| Constraints | ✓ Documented |
+| Out of Scope | ✓ [M] items |
+| Assumptions | ✓ Listed |
+| Risks | ✓ [P] identified |
+
+### Next Step
+
+**Create the blueprint** — Transform requirements into an execution plan
+
+→ `/goop-plan`
+
+---
+
+**Also available:**
+- `cat .goopspec/REQUIREMENTS.md` — Review discovery output
+- `/goop-research [topic]` — Investigate unknowns first
 ```
-/goop-discuss Add user authentication
+
+## Output
+
+| File | Purpose |
+|------|---------|
+| `.goopspec/REQUIREMENTS.md` | Discovery interview output |
+| State (via goop_state) | Updated with `interviewComplete: true` |
+
+## Transitions
+
+| Outcome | Next Step |
+|---------|-----------|
+| Discovery complete | `/goop-plan` to create blueprint |
+| Unknowns found | `/goop-research` to investigate |
+| Small task | `/goop-quick` to skip planning |
+
+## Bypass Conditions
+
+Discovery MAY be skipped only for:
+- `/goop-quick` small tasks (single file, < 30 min work)
+- Bug fixes with clear reproduction steps
+- Documentation-only changes
+
+## Examples
+
+**Simple Feature:**
 ```
+User: /goop-discuss add dark mode toggle
+
+Orchestrator: "Dark mode toggle. Let me understand what you need.
+
+**Vision:** What's the goal here?
+- Toggle in settings that switches the app theme
+- Persist preference across sessions
+- Respect system preference as default
+
+**Must-haves:** What MUST work?
+- Toggle UI in settings
+- Theme actually changes
+- Persists to localStorage
+
+**Out of scope?**
+- Per-component theme overrides
+- Multiple theme options beyond light/dark
+
+**Constraints?**
+- Using existing Tailwind dark: classes
+- No new dependencies
 
-Agent asks:
-- "What authentication methods? Email/password? OAuth?"
-- "Should sessions persist across browser closes?"
-- "Any specific security requirements?"
-- "How should errors be displayed?"
+**Assumptions?**
+- CSS already has dark variants (will verify)
 
-After discussion, agent summarizes understanding and asks for confirmation.
+**Risks?**
+- Some components may not have dark styles → will audit first
 
-## Transition to Plan
+Great, I have what I need. Creating REQUIREMENTS.md..."
+```
 
-When requirements are clear:
+**Complex Feature:**
 ```
-"I have a clear picture of what we need:
-[Summary of requirements]
+User: /goop-discuss rebuild the payment system
+
+Orchestrator: "Payment system rebuild - that's significant. 
+Let me understand the scope.
+
+**Vision:** What's driving this?
+- Current system uses deprecated Stripe API
+- Need to add PayPal as alternative
+- Improve error handling and retry logic
+
+**Must-haves:**
+- Migrate to Stripe v2 API
+- Add PayPal integration
+- Unified payment interface
+- Retry with exponential backoff
+- Webhook handling for async payments
 
-Ready to move to planning? I'll capture the formal intent 
-and requirements in the Plan phase."
+**Out of scope:**
+- Cryptocurrency payments (future)
+- Subscription management (separate project)
+
+**Risks:**
+- Stripe migration may have breaking changes → research first
+- PayPal integration complexity unknown → estimate 2x buffer
+
+I'd recommend running `/goop-research stripe v2 migration` before 
+planning. Want to do that first?"
 ```
 
-## Next Steps
+## Success Criteria
+
+- [ ] All six questions answered with specifics
+- [ ] At least 1 must-have defined
+- [ ] At least 1 out-of-scope item defined
+- [ ] At least 1 risk with mitigation
+- [ ] REQUIREMENTS.md created
+- [ ] State updated via `goop_state({ action: "complete-interview" })`
+- [ ] User knows next step is `/goop-plan`
 
-After discussion:
-- `/goop-plan [description]` - Capture formal intent and requirements
+## Anti-Patterns
 
-## Tips
+**DON'T:**
+- Accept vague answers ("it should be good")
+- Skip the risks question ("nothing could go wrong")
+- Rush through to get to coding
+- Spawn agents to conduct the interview
+- Create SPEC.md directly (that's /goop-plan's job)
 
-- Don't rush to planning - thorough discussion prevents rework
-- Ask about edge cases early
-- Validate understanding frequently
-- Challenge assumptions respectfully
-- Search memory for relevant past context
+**DO:**
+- Probe vague answers for specifics
+- Challenge "no risks" with scenarios
+- Take time - discovery is highest leverage
+- Conduct interview yourself (keeps context)
+- Save answers to memory for future reference
 
 ---
 
-**GoopSpec**: Understand deeply, build correctly.
+*Discovery Interview Protocol v0.1.4*
+*"Nail the spec before you write the code."*