Discovery Phase - Get Shit Done

<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-plan-phase --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.

Context7 MCP FIRST - Current docs, no hallucination
Official docs - When Context7 lacks coverage
WebSearch LAST - For comparisons and trends only

See ~/.claude/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:

Resolve library in Context7:

mcp__context7__resolve-library-id with libraryName: "[library]"

Fetch relevant docs:

mcp__context7__get-library-docs with:
- context7CompatibleLibraryID: [from step 1]
- topic: [specific concern]

Verify:
- Current version matches expectations
- API syntax unchanged
- No breaking changes in recent versions
If verified: Return to plan-phase.md with confirmation. No DISCOVERY.md needed.
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:

Identify what to discover:
- What options exist?
- What are the key comparison criteria?
- What's our specific use case?

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)

Official docs for anything Context7 lacks.
WebSearch for comparisons:
- "[option A] vs [option B] {current_year}"
- "[option] known issues"
- "[option] with [our stack]"
Cross-verify: Any WebSearch finding → confirm with Context7/official docs.
Create DISCOVERY.md using ~/.claude/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)
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:

Scope the discovery using ~/.claude/get-shit-done/templates/discovery.md:
- Define clear scope
- Define include/exclude boundaries
- List specific questions to answer
Exhaustive Context7 research:
- All relevant libraries
- Related patterns and concepts
- Multiple topics per library if needed
Official documentation deep read:
- Architecture guides
- Best practices sections
- Migration/upgrade guides
- Known limitations
WebSearch for ecosystem context:
- How others solved similar problems
- Production experiences
- Gotchas and anti-patterns
- Recent changes/announcements
Cross-verify ALL findings:
- Every WebSearch claim → verify with authoritative source
- Mark what's verified vs assumed
- Flag contradictions
Create comprehensive DISCOVERY.md:
- Full structure from ~/.claude/get-shit-done/templates/discovery.md
- Quality report with source attribution
- Confidence by finding
- If LOW confidence on any critical finding → add validation checkpoints
Confidence gate: If overall confidence is LOW, present options before proceeding.
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 ~/.claude/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:

Text mode (workflow.text_mode: true in config or --text flag): Set TEXT_MODE=true if --text is present in $ARGUMENTS OR text_mode from init JSON is true. When TEXT_MODE is active, replace every AskUserQuestion call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where AskUserQuestion is not available. Use AskUserQuestion:

header: "Low Conf."
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?

Discuss phase context (/gsd-discuss-phase [current-phase])
Create phase plan (/gsd-plan-phase [current-phase])
Refine discovery (dig deeper)
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>