Execute discovery at the appropriate depth level. Produces DISCOVERY.md that informs PLAN.md creation. Supports quick verify, standard, and deep dive depths.
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:
| 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 Web Search
Copilot's training data is 6-18 months stale. Always verify.
<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) <step name="level_1_quick_verify"> **Level 1: Quick Verification (2-5 minutes)** <step name="level_2_standard"> **Level 2: Standard Discovery (15-30 minutes)** <step name="level_3_deep_dive"> **Level 3: Deep Dive (1+ hour)** <step name="identify_unknowns"> **For Level 2-3:** Define what we need to learn. <step name="create_discovery_scope"> Use .planning/templates/discovery.md. <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. <step name="open_questions_gate"> If DISCOVERY.md has open_questions: <step name="offer_next"> ``` Discovery complete: .planning/phases/XX-name/DISCOVERY.md Recommendation: [one-liner] Confidence: [level]Priority Order:
use_mcp_tool(context7, ...) for current library/framework docsfetch (built-in) - Use for web search and fetching URLs (no MCP needed)fetch insufficient:
use_mcp_tool(exa, web_search_exa) — AI-native semantic search, code search, company researchuse_mcp_tool(brave-search, brave_web_search) — Privacy-first, general queries, newsWhy this order:
fetch is built-in and requires no MCP setupExa Tools (if installed):
web_search_exa — Search web for any topic, get clean contentget_code_context_exa — Find code from GitHub, Stack Overflow, docscompany_research_exa — Research companiesdeep_search_exa — Deep research with query expansionSee .planning/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:
Resolve library in Context7:
use_mcp_tool with server: "context7", tool: "resolve-library-id", arguments: { "libraryName": "[library]" }
Fetch relevant docs:
use_mcp_tool with server: "context7", tool: "query-docs", arguments: {
"libraryId": "[from step 1]",
"query": "[specific concern]"
}
Verify:
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>
For: Choosing between options, new external integration.
Process:
Identify what to discover:
Context7 for each option:
For each library/framework:
- use_mcp_tool(context7, resolve-library-id)
- use_mcp_tool(context7, query-docs) for API and concepts
Official docs for anything Context7 lacks (use fetch or browser_action).
Web search for comparisons:
fetch tool firstuse_mcp_tool(exa, web_search_exa) — Best for semantic/conceptual queriesuse_mcp_tool(exa, get_code_context_exa) — Best for code examplesuse_mcp_tool(brave-search, brave_web_search) — Best for news, general queriesCross-verify: Any Web Search finding → confirm with Context7/official docs.
Create DISCOVERY.md using .planning/templates/discovery.md structure:
Return to plan-phase.md.
Output: .planning/phases/XX-name/DISCOVERY.md
</step>
For: Architectural decisions, novel problems, high-risk choices.
Process:
Scope the discovery using .planning/templates/discovery.md:
Exhaustive Context7 research:
Official documentation deep read:
Web search for ecosystem context:
fetch tool firstuse_mcp_tool(exa, deep_search_exa) — Thorough research with query expansionuse_mcp_tool(exa, company_research_exa) — When researching vendors/companiesuse_mcp_tool(brave-search, brave_web_search) — News, general queriesCross-verify ALL findings:
Create comprehensive DISCOVERY.md:
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>
Ask: What do we need to learn before we can plan this phase?
Include:
If confidence is LOW: Use HumanAgent MCP (HumanAgent_Chat):
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:
These may affect implementation. Acknowledge and proceed? (yes / address first)"
If "address first": Gather user input on questions, update discovery. </step>
What's next?
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>