gsd-opencode 1.3.31

package/get-shit-done/workflows/discovery-phase.md

@@ -0,0 +1,293 @@
+<purpose>
+Execute discovery at the appropriate depth level.
+Produces DISCOVERY.md (for Level 2-3) that informs PLAN.md creation.
+
+Called from plan-phase.md's mandatory_discovery step with a depth parameter.
+
+NOTE: For comprehensive ecosystem research ("how do experts build this"), use /gsd:research-phase instead, which produces RESEARCH.md.
+</purpose>
+
+<depth_levels>
+**This workflow supports three depth levels:**
+
+| Level | Name         | Time      | Output                                       | When                                      |
+| ----- | ------------ | --------- | -------------------------------------------- | ----------------------------------------- |
+| 1     | Quick Verify | 2-5 min   | No file, proceed with verified knowledge     | Single library, confirming current syntax |
+| 2     | Standard     | 15-30 min | DISCOVERY.md                                 | Choosing between options, new integration |
+| 3     | Deep Dive    | 1+ hour   | Detailed DISCOVERY.md with validation gates  | Architectural decisions, novel problems   |
+
+**Depth is determined by plan-phase.md before routing here.**
+</depth_levels>
+
+<source_hierarchy>
+**MANDATORY: Context7 BEFORE WebSearch**
+
+Claude's training data is 6-18 months stale. Always verify.
+
+1. **Context7 MCP FIRST** - Current docs, no hallucination
+2. **Official docs** - When Context7 lacks coverage
+3. **WebSearch LAST** - For comparisons and trends only
+
+See ~/.config/opencode/get-shit-done/templates/discovery.md `<discovery_protocol>` for full protocol.
+</source_hierarchy>
+
+<process>
+
+<step name="determine_depth">
+Check the depth parameter passed from plan-phase.md:
+- `depth=verify` → Level 1 (Quick Verification)
+- `depth=standard` → Level 2 (Standard Discovery)
+- `depth=deep` → Level 3 (Deep Dive)
+
+Route to appropriate level workflow below.
+</step>
+
+<step name="level_1_quick_verify">
+**Level 1: Quick Verification (2-5 minutes)**
+
+For: Single known library, confirming syntax/version still correct.
+
+**Process:**
+
+1. Resolve library in Context7:
+
+   ```
+   mcp__context7__resolve-library-id with libraryName: "[library]"
+   ```
+
+2. Fetch relevant docs:
+
+   ```
+   mcp__context7__get-library-docs with:
+   - context7CompatibleLibraryID: [from step 1]
+   - topic: [specific concern]
+   ```
+
+3. Verify:
+
+   - Current version matches expectations
+   - API syntax unchanged
+   - No breaking changes in recent versions
+
+4. **If verified:** Return to plan-phase.md with confirmation. No DISCOVERY.md needed.
+
+5. **If concerns found:** Escalate to Level 2.
+
+**Output:** Verbal confirmation to proceed, or escalation to Level 2.
+</step>
+
+<step name="level_2_standard">
+**Level 2: Standard Discovery (15-30 minutes)**
+
+For: Choosing between options, new external integration.
+
+**Process:**
+
+1. **Identify what to discover:**
+
+   - What options exist?
+   - What are the key comparison criteria?
+   - What's our specific use case?
+
+2. **Context7 for each option:**
+
+   ```
+   For each library/framework:
+   - mcp__context7__resolve-library-id
+   - mcp__context7__get-library-docs (mode: "code" for API, "info" for concepts)
+   ```
+
+3. **Official docs** for anything Context7 lacks.
+
+4. **WebSearch** for comparisons:
+
+   - "[option A] vs [option B] {current_year}"
+   - "[option] known issues"
+   - "[option] with [our stack]"
+
+5. **Cross-verify:** Any WebSearch finding → confirm with Context7/official docs.
+
+6. **Quality check:** Before finalizing findings, consult ~/.config/opencode/get-shit-done/references/research-pitfalls.md to avoid common research gaps.
+
+7. **Create DISCOVERY.md** using ~/.config/opencode/get-shit-done/templates/discovery.md structure:
+
+   - Summary with recommendation
+   - Key findings per option
+   - Code examples from Context7
+   - Confidence level (should be MEDIUM-HIGH for Level 2)
+
+8. Return to plan-phase.md.
+
+**Output:** `.planning/phases/XX-name/DISCOVERY.md`
+</step>
+
+<step name="level_3_deep_dive">
+**Level 3: Deep Dive (1+ hour)**
+
+For: Architectural decisions, novel problems, high-risk choices.
+
+**Process:**
+
+1. **Scope the discovery** using ~/.config/opencode/get-shit-done/templates/discovery.md:
+
+   - Define clear scope
+   - Define include/exclude boundaries
+   - List specific questions to answer
+
+2. **Exhaustive Context7 research:**
+
+   - All relevant libraries
+   - Related patterns and concepts
+   - Multiple topics per library if needed
+
+3. **Official documentation deep read:**
+
+   - Architecture guides
+   - Best practices sections
+   - Migration/upgrade guides
+   - Known limitations
+
+4. **WebSearch for ecosystem context:**
+
+   - How others solved similar problems
+   - Production experiences
+   - Gotchas and anti-patterns
+   - Recent changes/announcements
+
+5. **Cross-verify ALL findings:**
+
+   - Every WebSearch claim → verify with authoritative source
+   - Mark what's verified vs assumed
+   - Flag contradictions
+
+6. **Quality check:** Before finalizing findings, consult ~/.config/opencode/get-shit-done/references/research-pitfalls.md to ensure comprehensive coverage and avoid common research gaps.
+
+7. **Create comprehensive DISCOVERY.md:**
+
+   - Full structure from ~/.config/opencode/get-shit-done/templates/discovery.md
+   - Quality report with source attribution
+   - Confidence by finding
+   - If LOW confidence on any critical finding → add validation checkpoints
+
+8. **Confidence gate:** If overall confidence is LOW, present options before proceeding.
+
+9. Return to plan-phase.md.
+
+**Output:** `.planning/phases/XX-name/DISCOVERY.md` (comprehensive)
+</step>
+
+<step name="identify_unknowns">
+**For Level 2-3:** Define what we need to learn.
+
+Ask: What do we need to learn before we can plan this phase?
+
+- Technology choices?
+- Best practices?
+- API patterns?
+- Architecture approach?
+  </step>
+
+<step name="create_discovery_scope">
+Use ~/.config/opencode/get-shit-done/templates/discovery.md.
+
+Include:
+
+- Clear discovery objective
+- Scoped include/exclude lists
+- Source preferences (official docs, Context7, current year)
+- Output structure for DISCOVERY.md
+  </step>
+
+<step name="execute_discovery">
+Run the discovery:
+- Use web search for current info
+- Use Context7 MCP for library docs
+- Prefer current year sources
+- Structure findings per template
+</step>
+
+<step name="create_discovery_output">
+Write `.planning/phases/XX-name/DISCOVERY.md`:
+- Summary with recommendation
+- Key findings with sources
+- Code examples if applicable
+- Metadata (confidence, dependencies, open questions, assumptions)
+</step>
+
+<step name="confidence_gate">
+After creating DISCOVERY.md, check confidence level.
+
+If confidence is LOW:
+Use AskUserQuestion:
+
+- header: "Low Confidence"
+- question: "Discovery confidence is LOW: [reason]. How would you like to proceed?"
+- options:
+  - "Dig deeper" - Do more research before planning
+  - "Proceed anyway" - Accept uncertainty, plan with caveats
+  - "Pause" - I need to think about this
+
+If confidence is MEDIUM:
+Inline: "Discovery complete (medium confidence). [brief reason]. Proceed to planning?"
+
+If confidence is HIGH:
+Proceed directly, just note: "Discovery complete (high confidence)."
+</step>
+
+<step name="open_questions_gate">
+If DISCOVERY.md has open_questions:
+
+Present them inline:
+"Open questions from discovery:
+
+- [Question 1]
+- [Question 2]
+
+These may affect implementation. Acknowledge and proceed? (yes / address first)"
+
+If "address first": Gather user input on questions, update discovery.
+</step>
+
+<step name="offer_next">
+```
+Discovery complete: .planning/phases/XX-name/DISCOVERY.md
+Recommendation: [one-liner]
+Confidence: [level]
+
+What's next?
+
+1. Discuss phase context (/gsd:discuss-phase [current-phase])
+2. Create phase plan (/gsd:plan-phase [current-phase])
+3. Refine discovery (dig deeper)
+4. Review discovery
+
+```
+
+NOTE: DISCOVERY.md is NOT committed separately. It will be committed with phase completion.
+</step>
+
+</process>
+
+<success_criteria>
+**Level 1 (Quick Verify):**
+- Context7 consulted for library/topic
+- Current state verified or concerns escalated
+- Verbal confirmation to proceed (no files)
+
+**Level 2 (Standard):**
+- Context7 consulted for all options
+- WebSearch findings cross-verified
+- DISCOVERY.md created with recommendation
+- Confidence level MEDIUM or higher
+- Ready to inform PLAN.md creation
+
+**Level 3 (Deep Dive):**
+- Discovery scope defined
+- Context7 exhaustively consulted
+- All WebSearch findings verified against authoritative sources
+- DISCOVERY.md created with comprehensive analysis
+- Quality report with source attribution
+- If LOW confidence findings → validation checkpoints defined
+- Confidence gate passed
+- Ready to inform PLAN.md creation
+</success_criteria>

package/get-shit-done/workflows/discuss-milestone.md

@@ -0,0 +1,236 @@
+<purpose>
+Help the user figure out what they want to build in the next milestone through collaborative thinking.
+
+You're a thinking partner helping them crystallize their vision for what's next. Features first — everything else (scope, phases) derives from what they want to build.
+</purpose>
+
+<process>
+
+<step name="check_state" priority="first">
+Load project state:
+
+```bash
+cat .planning/STATE.md
+cat .planning/ROADMAP.md
+```
+
+**If no active milestone (expected state after completing previous):**
+Continue to milestone_context.
+
+**If active milestone exists:**
+
+```
+Current milestone in progress: v[X.Y] [Name]
+Phases [N]-[M], [P]% complete
+
+Did you want to:
+1. Complete current milestone first (/gsd:complete-milestone)
+2. Add phases to current milestone (/gsd:add-phase)
+3. Continue anyway - discuss next milestone scope
+
+```
+
+Wait for user response. If "Continue anyway", proceed to milestone_context.
+</step>
+
+<step name="milestone_context">
+Present context from previous milestone:
+
+```
+Last completed: v[X.Y] [Name] (shipped [DATE])
+Key accomplishments:
+- [From MILESTONES.md or STATE.md]
+
+Total phases delivered: [N]
+Next phase number: [N+1]
+```
+
+Continue to intake_gate.
+</step>
+
+<step name="intake_gate">
+**CRITICAL: ALL questions use AskUserQuestion. Never ask inline text questions.**
+
+The primary question is: **What do you want to build/add/fix?**
+
+Everything else (scope, priority, constraints) is secondary and derived from features.
+
+Check for inputs:
+- Deferred issues from STATE.md (potential features)
+- Known gaps or pain points from usage
+- User's ideas for what's next
+
+**1. Open:**
+
+Use AskUserQuestion:
+- header: "Next"
+- question: "What do you want to add, improve, or fix in this milestone?"
+- options: [Deferred issues from STATE.md if any] + ["New features", "Improvements to existing", "Bug fixes", "Let me describe"]
+
+**2. Explore features:**
+
+Based on their response, use AskUserQuestion:
+
+If they named specific features:
+- header: "Feature Details"
+- question: "Tell me more about [feature] - what should it do?"
+- options: [Contextual options based on feature type + "Let me describe it"]
+
+If they described a general direction:
+- header: "Breaking It Down"
+- question: "That could involve [A], [B], [C] - which matter most?"
+- options: [Specific sub-features + "All of them" + "Something else"]
+
+If they're not sure:
+- header: "Starting Points"
+- question: "What's been frustrating or missing?"
+- options: [Deferred issues from STATE.md + pain point categories + "Let me think about it"]
+
+**3. Prioritize:**
+
+Use AskUserQuestion:
+- header: "Priority"
+- question: "Which of these matters most?"
+- options: [Features they mentioned + "All equally important" + "Let me prioritize"]
+
+After gathering features, synthesize:
+
+```
+Based on what you described:
+
+**Features:**
+- [Feature 1]: [brief description]
+- [Feature 2]: [brief description]
+- [Feature 3]: [brief description]
+
+**Estimated scope:** [N] phases
+**Theme suggestion:** v[X.Y] [Name]
+```
+
+**4. Decision gate:**
+
+Use AskUserQuestion:
+- header: "Ready?"
+- question: "Ready to create the milestone, or explore more?"
+- options (ALL THREE REQUIRED):
+  - "Create milestone" - Proceed to /gsd:new-milestone
+  - "Ask more questions" - Help me think through this more
+  - "Let me add context" - I have more to share
+
+If "Ask more questions" → return to step 2 with new probes.
+If "Let me add context" → receive input → return to step 2.
+Loop until "Create milestone" selected.
+</step>
+
+<step name="write_context">
+Write milestone context to file for handoff.
+
+**File:** `.planning/MILESTONE-CONTEXT.md`
+
+Use template from ~/.config/opencode/get-shit-done/templates/milestone-context.md
+
+Populate with:
+- Features identified during discussion
+- Suggested milestone name and theme
+- Estimated phase count
+- How features map to phases
+- Any constraints or scope boundaries mentioned
+
+```bash
+# Write the context file
+cat > .planning/MILESTONE-CONTEXT.md << 'EOF'
+# Milestone Context
+
+**Generated:** [today's date]
+**Status:** Ready for /gsd:new-milestone
+
+<features>
+## Features to Build
+
+- **[Feature 1]**: [description]
+- **[Feature 2]**: [description]
+- **[Feature 3]**: [description]
+
+</features>
+
+<scope>
+## Scope
+
+**Suggested name:** v[X.Y] [Theme Name]
+**Estimated phases:** [N]
+**Focus:** [One sentence theme/focus]
+
+</scope>
+
+<phase_mapping>
+## Phase Mapping
+
+- Phase [N]: [Feature/goal]
+- Phase [N+1]: [Feature/goal]
+- Phase [N+2]: [Feature/goal]
+
+</phase_mapping>
+
+<constraints>
+## Constraints
+
+- [Any constraints mentioned]
+
+</constraints>
+
+<notes>
+## Additional Context
+
+[Anything else from discussion]
+
+</notes>
+
+---
+
+*This file is temporary. It will be deleted after /gsd:new-milestone creates the milestone.*
+EOF
+```
+</step>
+
+<step name="handoff">
+Present summary and hand off to create-milestone:
+
+```
+Milestone scope defined:
+
+**Features:**
+- [Feature 1]: [description]
+- [Feature 2]: [description]
+- [Feature 3]: [description]
+
+**Suggested milestone:** v[X.Y] [Theme Name]
+**Estimated phases:** [N]
+
+Context saved to `.planning/MILESTONE-CONTEXT.md`
+
+---
+
+## ▶ Next Up
+
+**Create Milestone v[X.Y]** — [Theme Name]
+
+`/gsd:new-milestone`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+</step>
+
+</process>
+
+<success_criteria>
+
+- Project state loaded (STATE.md, ROADMAP.md)
+- Previous milestone context presented
+- **Features identified** - What to build/add/fix (the substance)
+- Features explored with clarifying questions
+- Scope synthesized from features (not asked abstractly)
+- **MILESTONE-CONTEXT.md created** with features, scope, and phase mapping
+- Context handed off to /gsd:new-milestone
+</success_criteria>