discovery-phase

Called from plan-phase.md's mandatory_discovery step with a depth parameter.

NOTE: For comprehensive ecosystem research ("how do experts build this"), use /research-phase.md instead, which produces RESEARCH.md. </purpose>

<depth_levels> This workflow supports three depth levels:

Depth is determined by plan-phase.md before routing here. </depth_levels>

<source_hierarchy> MANDATORY: Context7 BEFORE Web Search

KiloCode's training data is 6-18 months stale. Always verify.

1. •Context7 MCP FIRST - Use use_mcp_tool(context7, ...) for current docs, no hallucination
2. •Web Search MCP - Use Exa or Brave Search (equal priority, choose by use case):
   • •Exa MCP - use_mcp_tool(exa, web_search_exa) — AI-native semantic search, code search, company research
   • •Brave Search - use_mcp_tool(brave-search, brave_web_search) — Privacy-first, general queries, news
3. •browser_action LAST - Fallback for direct URL access or when MCPs unavailable

Exa Tools:

• •web_search_exa — Search web for any topic, get clean content
• •get_code_context_exa — Find code from GitHub, Stack Overflow, docs
• •company_research_exa — Research companies
• •deep_search_exa — Deep research with query expansion

See ~/.gsd/templates/discovery.md <discovery_protocol> for full protocol. </source_hierarchy>

Route to appropriate level workflow below. </step>

For: Single known library, confirming syntax/version still correct.

Process:

1. •

   Resolve library in Context7:

   code

   use_mcp_tool with server: "context7", tool: "resolve-library-id", arguments: { "libraryName": "[library]" }
   

2. •

   Fetch relevant docs:

   code

   use_mcp_tool with server: "context7", tool: "query-docs", arguments: {
     "libraryId": "[from step 1]",
     "query": "[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>

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:

   code

   For each library/framework:
   - use_mcp_tool(context7, resolve-library-id)
   - use_mcp_tool(context7, query-docs) for API and concepts
   

3. •

   Official docs for anything Context7 lacks (use Web Search MCP or browser_action).

4. •

   Web Search MCP for comparisons:

   • •"[option A] vs [option B] {current_year}"
   • •"[option] known issues"
   • •"[option] with [our stack]"
   • •use_mcp_tool(exa, web_search_exa) — Best for semantic/conceptual queries
   • •use_mcp_tool(exa, get_code_context_exa) — Best for code examples
   • •use_mcp_tool(brave-search, brave_web_search) — Best for news, general queries
5. •

   Cross-verify: Any Web Search finding → confirm with Context7/official docs.

6. •

   Create DISCOVERY.md using ~/.gsd/templates/discovery.md structure:

   • •Summary with recommendation
   • •Key findings per option
   • •Code examples from Context7
   • •Confidence level (should be MEDIUM-HIGH for Level 2)
7. •

   Return to plan-phase.md.

Output: .gsd/phases/XX-name/DISCOVERY.md </step>

For: Architectural decisions, novel problems, high-risk choices.

Process:

1. •

   Scope the discovery using ~/.gsd/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. •

   Web Search MCP for ecosystem context:

   • •How others solved similar problems
   • •Production experiences
   • •Gotchas and anti-patterns
   • •Recent changes/announcements
   • •use_mcp_tool(exa, deep_search_exa) — Thorough research with query expansion
   • •use_mcp_tool(exa, company_research_exa) — When researching vendors/companies
   • •use_mcp_tool(brave-search, brave_web_search) — News, general queries
   • •browser_action fallback for direct URL access
5. •

   Cross-verify ALL findings:

   • •Every Web Search claim → verify with authoritative source
   • •Mark what's verified vs assumed
   • •Flag contradictions
6. •

   Create comprehensive DISCOVERY.md:

   • •Full structure from ~/.gsd/templates/discovery.md
   • •Quality report with source attribution
   • •Confidence by finding
   • •If LOW confidence on any critical finding → add validation checkpoints
7. •

   Confidence gate: If overall confidence is LOW, present options before proceeding.

8. •

   Return to plan-phase.md.

Output: .gsd/phases/XX-name/DISCOVERY.md (comprehensive) </step>

Ask: What do we need to learn before we can plan this phase?

• •Technology choices?
• •Best practices?
• •API patterns?
• •Architecture approach? </step>

Include:

• •Clear discovery objective
• •Scoped include/exclude lists
• •Source preferences (official docs, Context7, current year)
• •Output structure for DISCOVERY.md </step>

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>

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>

What's next?

1. •Discuss phase context (/discuss-phase.md [current-phase])
2. •Create phase plan (/plan-phase.md [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 via use_mcp_tool for library/topic
- Current state verified or concerns escalated
- Verbal confirmation to proceed (no files)

**Level 2 (Standard):**
- Context7 consulted for all options
- Web Search 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 Web Search 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>