discovery-phase

name	discovery-phase
description	以适当的深度级别执行发现。生成 DISCOVERY.md 用于指导 PLAN.md 的创建。支持快速验证、标准和深度模式。

以适当的深度级别执行发现。 生成 DISCOVERY.md（用于 Level 2-3），指导 PLAN.md 的创建。

从 plan-phase.md 的主流程中调用：研究 → 发现 → 计划

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

Priority Order:

1. Context7 MCP FIRST - Use use_mcp_tool(context7, ...) for current library/framework docs
2. Copilot fetch (built-in) - Use for web search and fetching URLs (no MCP needed)
3. Exa / Brave Search MCP - Optional, for deep research when fetch insufficient:
   • 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

Why this order:

• Context7 has authoritative, current library documentation
• Copilot's fetch is built-in and requires no MCP setup
• Exa/Brave are external MCP servers (optional for users who install them)

Exa Tools (if installed):

• 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>

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.

**Level 1: Quick Verification (2-5 minutes)**

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

Process:

1. Resolve library in Context7:

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

2. Fetch relevant docs:

   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.

**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:
   - 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 fetch or browser_action).

4. Web search for comparisons:

   • "[option A] vs [option B] {current_year}"
   • "[option] known issues"
   • "[option] with [our stack]"
   • Use Copilot's built-in fetch tool first
   • If more depth needed and MCP installed:
     • 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

**Level 3: Deep Dive (1+ hour)**

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 for ecosystem context:

   • How others solved similar problems
   • Production experiences
   • Gotchas and anti-patterns
   • Recent changes/announcements
   • Use Copilot's built-in fetch tool first
   • If more depth needed and MCP installed:
     • 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

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)

**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?

Use ~/.gsd/templates/discovery.md.

Include:

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

Run the discovery: - Use web search for current info - Use Context7 MCP for library docs - Prefer current year sources - Structure findings per template Write `.gsd/phases/XX-name/DISCOVERY.md`: - Summary with recommendation - Key findings with sources - Code examples if applicable - Metadata (confidence, dependencies, open questions, assumptions) After creating DISCOVERY.md, check confidence level.

If confidence is LOW: Use HumanAgent MCP (HumanAgent_Chat):

• 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)."

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.

``` Discovery complete: .gsd/phases/XX-name/DISCOVERY.md Recommendation: [one-liner] Confidence: [level]

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>