Enable optional DeepWiki integration for advanced repository analysis and UI library research.
This commit is contained in:
BOBDA DJIMO ARMEL HYACINTHE
parent
cf50f4935d
commit
951b66b037
|
|
@ -26,6 +26,7 @@
|
|||
- **Research goals = "{{research_goals}}"** - captured from initial discussion
|
||||
- Focus on technical architecture and implementation research
|
||||
- Web search is required to verify and supplement your knowledge with current facts
|
||||
- **DeepWiki MCP** may be available for authoritative repository documentation (optional enhancement)
|
||||
|
||||
## YOUR TASK:
|
||||
|
||||
|
|
@ -69,7 +70,101 @@ For **{{research_topic}}**, I will research:
|
|||
**All claims verified against current public sources.**
|
||||
|
||||
**Does this technical research scope and approach align with your goals?**
|
||||
[C] Continue - Begin technical research with this scope
|
||||
|
||||
### 2.5 Framework Integration Mode (Optional DeepWiki Enhancement)
|
||||
|
||||
After confirming scope, ask:
|
||||
|
||||
"**Does this research involve integrating multiple frameworks or libraries?**
|
||||
|
||||
If you're researching how frameworks work together (e.g., Tauri + Next.js, or React + a backend framework), I can query authoritative repository documentation via DeepWiki for verified API signatures and integration patterns.
|
||||
|
||||
[Y] Yes - Enable DeepWiki mode for authoritative framework documentation
|
||||
[N] No - Standard web research is sufficient for this topic"
|
||||
|
||||
#### If Y (Enable DeepWiki):
|
||||
|
||||
"**Which GitHub repositories should I query?** (Maximum 3 for optimal results)
|
||||
|
||||
Format: `owner/repo` (e.g., `tauri-apps/tauri`, `vercel/next.js`)
|
||||
|
||||
Enter repositories (comma-separated):"
|
||||
|
||||
#### Repository Type Classification (MANDATORY if enabled):
|
||||
|
||||
For each provided repository, classify its type based on name patterns:
|
||||
|
||||
| Pattern Match | Type | Query Focus |
|
||||
| ---------------------------------------- | -------------- | -------------------------------------- |
|
||||
| `shadcn/*`, `shadcn-ui/*`, `radix-ui/*` | `ui-primitive` | Primitives, composition, accessibility |
|
||||
| `chakra-ui/*`, `mui/*`, `ant-design/*` | `ui-library` | Components, theming, variants |
|
||||
| `*-ui/*`, `*ui/*` (general) | `ui-library` | Components, props, customization |
|
||||
| `tauri-apps/*`, `vercel/*`, `electron/*` | `framework` | APIs, protocols, extensions |
|
||||
| `*auth*`, `*-auth/*` | `auth-library` | Sessions, providers, security |
|
||||
| Other | `general` | Standard technical queries |
|
||||
|
||||
Display classification to user:
|
||||
"**Repository Classification:**
|
||||
| Repository | Type | Query Focus |
|
||||
|------------|------|-------------|
|
||||
| {repo_1} | {type} | {focus_description} |
|
||||
| {repo_2} | {type} | {focus_description} |
|
||||
|
||||
**Note:** UI libraries will receive additional component-focused queries for UX Designer downstream use."
|
||||
|
||||
#### DeepWiki Validation (MANDATORY if enabled):
|
||||
|
||||
For each provided repository:
|
||||
|
||||
1. Call `read_wiki_structure(repo)` to verify indexing
|
||||
2. If successful: Store repo with `indexed: true`, extract version if available, store `type` classification
|
||||
3. If fails: Warn user - "⚠️ {repo} is not indexed in DeepWiki. Continue without it? [Y/N]"
|
||||
|
||||
Display validation results:
|
||||
"**DeepWiki Repository Status:**
|
||||
| Repository | Indexed | Version |
|
||||
|------------|---------|---------|
|
||||
| {repo_1} | ✅/❌ | {version} |
|
||||
| {repo_2} | ✅/❌ | {version} |
|
||||
|
||||
**Query Budget:** This session will use approximately {estimated} queries. Maximum recommended: 15 queries."
|
||||
|
||||
#### DeepWiki Frontmatter Variables:
|
||||
|
||||
When DeepWiki is enabled, set:
|
||||
|
||||
```yaml
|
||||
deepwiki_enabled: true
|
||||
deepwiki_repos:
|
||||
- repo: 'owner/repo'
|
||||
indexed: true
|
||||
version: 'detected or unknown'
|
||||
type: 'framework|ui-library|ui-primitive|auth-library|general'
|
||||
deepwiki_query_budget: 15
|
||||
deepwiki_queries_used: 0
|
||||
deepwiki_has_ui_repos: true|false # Set true if any repo type is ui-library or ui-primitive
|
||||
```
|
||||
|
||||
#### If N (Standard Research):
|
||||
|
||||
Proceed with web-only research:
|
||||
|
||||
```yaml
|
||||
deepwiki_enabled: false
|
||||
```
|
||||
|
||||
### 2.6 Final Scope Confirmation
|
||||
|
||||
Present final confirmation with DeepWiki status:
|
||||
|
||||
"**Technical Research Configuration:**
|
||||
|
||||
✅ Research Topic: {{research_topic}}
|
||||
✅ Research Goals: {{research_goals}}
|
||||
✅ Data Sources: Web Search + DeepWiki (if enabled)
|
||||
✅ DeepWiki Repos: {list or 'None - web only'}
|
||||
|
||||
[C] Continue - Begin technical research with this configuration"
|
||||
|
||||
### 3. Handle Continue Selection
|
||||
|
||||
|
|
@ -104,6 +199,12 @@ When user selects 'C', append scope confirmation:
|
|||
- Confidence level framework for uncertain information
|
||||
- Comprehensive technical coverage with architecture-specific insights
|
||||
|
||||
**DeepWiki Configuration:**
|
||||
|
||||
- Enabled: {{deepwiki_enabled}}
|
||||
- Repositories: {{deepwiki_repos or 'None - web research only'}}
|
||||
- Query Budget: {{deepwiki_query_budget or 'N/A'}}
|
||||
|
||||
**Scope Confirmed:** {{date}}
|
||||
```
|
||||
|
||||
|
|
@ -115,6 +216,10 @@ When user selects 'C', append scope confirmation:
|
|||
✅ [C] continue option presented and handled correctly
|
||||
✅ Scope confirmation documented when user proceeds
|
||||
✅ Proper routing to next technical research step
|
||||
✅ DeepWiki mode offered for framework integration research
|
||||
✅ DeepWiki repos validated via read_wiki_structure() before proceeding
|
||||
✅ Query budget communicated to user
|
||||
✅ DeepWiki configuration saved to frontmatter
|
||||
|
||||
## FAILURE MODES:
|
||||
|
||||
|
|
@ -124,6 +229,10 @@ When user selects 'C', append scope confirmation:
|
|||
❌ Not presenting [C] continue option
|
||||
❌ Proceeding without user scope confirmation
|
||||
❌ Not routing to next technical research step
|
||||
❌ Enabling DeepWiki without validating repos are indexed
|
||||
❌ Exceeding 3 repo limit without warning
|
||||
❌ Not communicating query budget to user
|
||||
❌ Not saving DeepWiki configuration to frontmatter
|
||||
|
||||
❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
|
||||
❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
|
||||
|
|
|
|||
|
|
@ -28,6 +28,9 @@
|
|||
- **Research goals = "{{research_goals}}"** - established from initial discussion
|
||||
- Focus on APIs, protocols, and system interoperability
|
||||
- Web search capabilities with source verification are enabled
|
||||
- **DeepWiki MCP** - Check `deepwiki_enabled` from frontmatter for enhanced repository analysis
|
||||
- **DeepWiki repos** - If enabled, `deepwiki_repos` contains validated repositories to query
|
||||
- **Query budget** - Track `deepwiki_queries_used` against `deepwiki_query_budget`
|
||||
|
||||
## YOUR TASK:
|
||||
|
||||
|
|
@ -165,6 +168,342 @@ _Data Encryption: [Secure data transmission and storage]_
|
|||
_Source: [URL]_
|
||||
```
|
||||
|
||||
### 3.5 DeepWiki-Enhanced Cross-Repository Analysis (CONDITIONAL)
|
||||
|
||||
**⚠️ ONLY EXECUTE THIS SECTION IF `deepwiki_enabled: true` IN FRONTMATTER**
|
||||
|
||||
If DeepWiki is not enabled, skip directly to Section 5.
|
||||
|
||||
---
|
||||
|
||||
#### DeepWiki Query Protocol
|
||||
|
||||
**Confidence Label System:**
|
||||
| Label | Meaning | Source |
|
||||
|-------|---------|--------|
|
||||
| 🟢 `[REPO-VERIFIED]` | Direct from repo docs via DeepWiki | Single repo query |
|
||||
| 🟡 `[CROSS-REPO-DOCUMENTED]` | Explicit integration docs found | Rare - high value |
|
||||
| 🟠 `[LLM-SYNTHESIZED]` | Combined from per-repo facts | Requires POC |
|
||||
| 🔴 `[HYPOTHESIS-ONLY]` | Speculative, no supporting docs | Do not use without validation |
|
||||
|
||||
---
|
||||
|
||||
#### Phase 1: Cross-Reference Detection
|
||||
|
||||
For each pair of repositories (A, B) in `deepwiki_repos`:
|
||||
|
||||
```
|
||||
ask_question(repo_A, "Does {repo_A} document integration patterns with {repo_B} or similar frameworks in its category?")
|
||||
```
|
||||
|
||||
**If cross-reference found:**
|
||||
|
||||
- Mark as `[CROSS-REPO-DOCUMENTED]` - this is rare and high value
|
||||
- Extract the documented integration pattern
|
||||
- Note the source section in DeepWiki
|
||||
|
||||
**If not found:**
|
||||
|
||||
- Continue to Phase 2 for this pair
|
||||
- Mark any synthesis as `[LLM-SYNTHESIZED]`
|
||||
|
||||
**Update query count:** `deepwiki_queries_used += 1` per query
|
||||
|
||||
---
|
||||
|
||||
#### Phase 2: Structured Per-Repository Extraction
|
||||
|
||||
For each repository in `deepwiki_repos`, run these queries:
|
||||
|
||||
**Q1 - Integration APIs:**
|
||||
|
||||
```
|
||||
ask_question(repo, "What APIs does {repo} expose for external integration? Include function signatures and parameters.")
|
||||
```
|
||||
|
||||
**Q2 - Communication Protocols:**
|
||||
|
||||
```
|
||||
ask_question(repo, "What communication protocols and data formats does {repo} support for inter-process or inter-service communication?")
|
||||
```
|
||||
|
||||
**Q3 - Extension Points:**
|
||||
|
||||
```
|
||||
ask_question(repo, "What are the documented extension points, plugin architecture, or hooks in {repo}?")
|
||||
```
|
||||
|
||||
**Q4 - Third-Party Ecosystem:**
|
||||
|
||||
```
|
||||
ask_question(repo, "What third-party libraries, plugins, or bridges exist for {repo} integration with other frameworks?")
|
||||
```
|
||||
|
||||
**Q5 - Ecosystem Discovery (Enhanced):**
|
||||
|
||||
```
|
||||
ask_question(repo, "What official adapters, integrations, or framework-specific packages does {repo} provide? Include any Next.js, React, Vue, Svelte, or mobile adapters.")
|
||||
```
|
||||
|
||||
**Store results per repository with:**
|
||||
|
||||
- API signatures extracted
|
||||
- Protocol support identified
|
||||
- Extension mechanisms documented
|
||||
- Ecosystem libraries discovered
|
||||
- Official adapters/integrations listed
|
||||
|
||||
**Update query count:** `deepwiki_queries_used += 5` per repository
|
||||
|
||||
---
|
||||
|
||||
#### Phase 3: LLM Cross-Repository Synthesis
|
||||
|
||||
**⚠️ CRITICAL: This section produces `[LLM-SYNTHESIZED]` content. Label explicitly.**
|
||||
|
||||
Using Phase 1 and Phase 2 data, synthesize cross-repo integration patterns:
|
||||
|
||||
**For each repository pair (A, B):**
|
||||
|
||||
1. **Compare APIs:** Identify compatible integration points
|
||||
- Does A expose an API that B can consume?
|
||||
- Does B expose an API that A can consume?
|
||||
|
||||
2. **Compare Protocols:** Identify communication compatibility
|
||||
- Do they share common protocols (HTTP, WebSocket, IPC)?
|
||||
- Are data formats compatible (JSON, Protobuf)?
|
||||
|
||||
3. **Identify Bridge Patterns:**
|
||||
- Can A's extension points connect to B?
|
||||
- Are there ecosystem libraries that bridge A and B?
|
||||
|
||||
4. **Hypothesize Integration Architecture:**
|
||||
- How would data flow between A and B?
|
||||
- What is the recommended communication pattern?
|
||||
|
||||
**MANDATORY: Label all synthesis output as `[LLM-SYNTHESIZED]`**
|
||||
|
||||
---
|
||||
|
||||
#### Phase 3.5: UI Library Component Analysis (CONDITIONAL)
|
||||
|
||||
**⚠️ ONLY EXECUTE THIS SECTION IF ANY REPO IN `deepwiki_repos` HAS `type: ui-library` OR `type: ui-primitive`**
|
||||
|
||||
For each UI library/primitive repository, run these specialized queries:
|
||||
|
||||
**Q1 - Component Inventory:**
|
||||
|
||||
```
|
||||
ask_question(repo, "What UI components does {repo} provide? List all available components with their primary purpose.")
|
||||
```
|
||||
|
||||
**Q2 - Theming & Customization:**
|
||||
|
||||
```
|
||||
ask_question(repo, "How does {repo} handle theming and customization? What are the theming APIs, CSS variables, or design tokens available?")
|
||||
```
|
||||
|
||||
**Q3 - Composition Patterns:**
|
||||
|
||||
```
|
||||
ask_question(repo, "What composition patterns does {repo} support? How do components compose together, and what are the slot/children patterns?")
|
||||
```
|
||||
|
||||
**Q4 - Accessibility Features:**
|
||||
|
||||
```
|
||||
ask_question(repo, "What accessibility features are built into {repo}? List ARIA support, keyboard navigation, and screen reader considerations.")
|
||||
```
|
||||
|
||||
**Q5 - Variant & State System:**
|
||||
|
||||
```
|
||||
ask_question(repo, "How does {repo} handle component variants and states? What props control visual variations (size, color, disabled, etc.)?"
|
||||
```
|
||||
|
||||
**Update query count:** `deepwiki_queries_used += 5` per UI library repo
|
||||
|
||||
---
|
||||
|
||||
##### UI Component Capability Matrix Output
|
||||
|
||||
For each UI library, generate this matrix:
|
||||
|
||||
```markdown
|
||||
### {Repo} Component Capability Matrix [REPO-VERIFIED]
|
||||
|
||||
**Library Type:** {ui-library|ui-primitive}
|
||||
**Source:** DeepWiki query on {repo}
|
||||
|
||||
#### Available Components
|
||||
|
||||
| Component | Category | Variants | Accessibility | Composable |
|
||||
| --------- | -------- | -------------------- | -------------------- | ---------- |
|
||||
| Button | Action | size, color, variant | ✅ ARIA | ✅ |
|
||||
| Input | Form | size, state | ✅ Label association | ✅ |
|
||||
| ... | ... | ... | ... | ... |
|
||||
|
||||
#### Theming System
|
||||
|
||||
| Aspect | Support | Method |
|
||||
| --------------- | ------- | ------------- |
|
||||
| CSS Variables | ✅/❌ | {description} |
|
||||
| Design Tokens | ✅/❌ | {description} |
|
||||
| Runtime Theming | ✅/❌ | {description} |
|
||||
| Dark Mode | ✅/❌ | {description} |
|
||||
|
||||
#### Composition Patterns
|
||||
|
||||
- **Slot Pattern:** {supported/not supported} - {description}
|
||||
- **Compound Components:** {supported/not supported} - {description}
|
||||
- **Render Props:** {supported/not supported} - {description}
|
||||
- **Polymorphic `as` Prop:** {supported/not supported} - {description}
|
||||
|
||||
#### Accessibility Summary
|
||||
|
||||
| Feature | Coverage |
|
||||
| ------------------- | --------------------- |
|
||||
| ARIA Attributes | {auto/manual/partial} |
|
||||
| Keyboard Navigation | {full/partial/none} |
|
||||
| Focus Management | {automatic/manual} |
|
||||
| Screen Reader | {tested/untested} |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### Phase 4: POC Validation Checklist Generation
|
||||
|
||||
For each synthesized integration pattern, generate a validation checklist:
|
||||
|
||||
```markdown
|
||||
### POC Validation Checklist: {Repo A} ↔ {Repo B}
|
||||
|
||||
**Pattern:** {synthesized pattern description}
|
||||
**Confidence:** [LLM-SYNTHESIZED]
|
||||
|
||||
**Validation Steps:**
|
||||
|
||||
- [ ] {Repo A} API successfully called from integration code
|
||||
- [ ] {Repo B} receives data in expected format
|
||||
- [ ] Bidirectional communication works (if applicable)
|
||||
- [ ] Error handling propagates correctly across boundary
|
||||
- [ ] Performance acceptable for use case
|
||||
- [ ] No memory leaks or resource issues at boundary
|
||||
|
||||
**Unknown/Unverified:**
|
||||
|
||||
- [ ] Thread safety across framework boundaries
|
||||
- [ ] Lifecycle coordination between frameworks
|
||||
- [ ] Version compatibility for untested combinations
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### DeepWiki Output Structure
|
||||
|
||||
Append to document after web search content:
|
||||
|
||||
```markdown
|
||||
## Cross-Repository Integration Analysis [DEEPWIKI-ENHANCED]
|
||||
|
||||
**Data Sources:** DeepWiki MCP queries on {{deepwiki_repos}}
|
||||
**Queries Used:** {{deepwiki_queries_used}} / {{deepwiki_query_budget}}
|
||||
**Data Freshness:** DeepWiki indexes updated periodically - verify critical APIs against current release notes
|
||||
|
||||
---
|
||||
|
||||
### Per-Repository Integration Surfaces
|
||||
|
||||
#### {Repo A} Integration Surface [REPO-VERIFIED]
|
||||
|
||||
**Source:** DeepWiki query on {repo_A}
|
||||
|
||||
**Public APIs:**
|
||||
{extracted from Q1}
|
||||
|
||||
**Communication Protocols:**
|
||||
{extracted from Q2}
|
||||
|
||||
**Extension Points:**
|
||||
{extracted from Q3}
|
||||
|
||||
**Ecosystem Libraries:**
|
||||
{extracted from Q4}
|
||||
|
||||
---
|
||||
|
||||
#### {Repo B} Integration Surface [REPO-VERIFIED]
|
||||
|
||||
**Source:** DeepWiki query on {repo_B}
|
||||
|
||||
{same structure as above}
|
||||
|
||||
---
|
||||
|
||||
### Cross-Repository Integration Patterns
|
||||
|
||||
#### Direct Integration Documentation [CROSS-REPO-DOCUMENTED]
|
||||
|
||||
{Only if Phase 1 found actual cross-repo docs - often empty}
|
||||
|
||||
_No direct cross-repository documentation found._ (if empty)
|
||||
|
||||
---
|
||||
|
||||
#### Synthesized Integration Patterns [LLM-SYNTHESIZED]
|
||||
|
||||
**⚠️ WARNING: The following patterns are LLM synthesis based on per-repo facts.**
|
||||
**They require POC validation before use in architecture decisions.**
|
||||
|
||||
##### Pattern: {Repo A} ↔ {Repo B} Bridge
|
||||
|
||||
**Hypothesis:** {description of how they might integrate}
|
||||
|
||||
**Based on:**
|
||||
|
||||
- {Repo A}'s {api} [REPO-VERIFIED]
|
||||
- {Repo B}'s {api} [REPO-VERIFIED]
|
||||
|
||||
**Confidence:** 🟠 [LLM-SYNTHESIZED] - No direct documentation found
|
||||
|
||||
**Recommended Data Flow:**
|
||||
```
|
||||
|
||||
{Repo A} → {mechanism} → {Repo B}
|
||||
{Repo B} → {mechanism} → {Repo A} (if bidirectional)
|
||||
|
||||
````
|
||||
|
||||
**Code Example (Conceptual):**
|
||||
```{language}
|
||||
// Integration pattern - REQUIRES VALIDATION
|
||||
{conceptual code based on extracted APIs}
|
||||
````
|
||||
|
||||
---
|
||||
|
||||
### POC Validation Requirements
|
||||
|
||||
**⚠️ This research is INCOMPLETE until the following POC validations pass:**
|
||||
|
||||
{aggregated checklists from Phase 4}
|
||||
|
||||
---
|
||||
|
||||
### DeepWiki Query Log
|
||||
|
||||
| Query | Repository | Purpose | Result |
|
||||
| ----- | ---------- | ------------------------- | --------------- |
|
||||
| 1 | {repo} | Cross-reference detection | Found/Not found |
|
||||
| 2 | {repo} | Integration APIs | {summary} |
|
||||
| ... | ... | ... | ... |
|
||||
|
||||
**Total Queries:** {{deepwiki_queries_used}} / {{deepwiki_query_budget}}
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. Present Analysis and Continue Option
|
||||
|
||||
**Show analysis and present continue option:**
|
||||
|
|
@ -179,6 +518,12 @@ _Source: [URL]_
|
|||
- Microservices integration patterns mapped
|
||||
- Event-driven integration strategies identified
|
||||
|
||||
**DeepWiki Enhancement (if enabled):**
|
||||
- Per-repository integration surfaces documented [REPO-VERIFIED]
|
||||
- Cross-repository patterns synthesized [LLM-SYNTHESIZED]
|
||||
- POC validation checklists generated
|
||||
- Query budget: {{deepwiki_queries_used}} / {{deepwiki_query_budget}}
|
||||
|
||||
**Ready to proceed to architectural patterns analysis?**
|
||||
[C] Continue - Save this to document and proceed to architectural patterns
|
||||
|
||||
|
|
@ -206,6 +551,18 @@ Content is already written to document when generated in step 4. No additional a
|
|||
✅ Proper routing to next step (architectural patterns)
|
||||
✅ Research goals alignment maintained
|
||||
|
||||
### DeepWiki Success Metrics (if enabled):
|
||||
|
||||
✅ Phase 1 cross-reference detection executed for all repo pairs
|
||||
✅ Phase 2 structured extraction completed for all repos (5 queries each)
|
||||
✅ Phase 3 synthesis clearly labeled as `[LLM-SYNTHESIZED]`
|
||||
✅ Phase 3.5 UI Component Analysis executed for ui-library/ui-primitive repos (if any)
|
||||
✅ Phase 4 POC validation checklists generated for all synthesized patterns
|
||||
✅ Per-repo facts labeled as `[REPO-VERIFIED]`
|
||||
✅ Query budget tracked and displayed
|
||||
✅ DeepWiki output structure appended to document
|
||||
✅ UI Component Capability Matrix generated for each UI library (if applicable)
|
||||
|
||||
## FAILURE MODES:
|
||||
|
||||
❌ Relying solely on training data without web verification for current facts
|
||||
|
|
@ -217,6 +574,17 @@ Content is already written to document when generated in step 4. No additional a
|
|||
❌ Not presenting [C] continue option after content generation
|
||||
❌ Not routing to architectural patterns step
|
||||
|
||||
### DeepWiki Failure Modes (if enabled):
|
||||
|
||||
❌ Not checking `deepwiki_enabled` before executing DeepWiki section
|
||||
❌ Labeling synthesized content as `[REPO-VERIFIED]` (CRITICAL - trust violation)
|
||||
❌ Not generating POC validation checklists for synthesized patterns
|
||||
❌ Exceeding query budget without warning
|
||||
❌ Not tracking `deepwiki_queries_used` in frontmatter
|
||||
❌ Presenting synthesized patterns without confidence labels
|
||||
❌ Not executing Phase 3.5 UI queries when ui-library/ui-primitive repos are present
|
||||
❌ Missing UI Component Capability Matrix for UI library repos
|
||||
|
||||
❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
|
||||
❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
|
||||
❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
|
||||
|
|
@ -245,3 +613,4 @@ Content is already written to document when generated in step 4. No additional a
|
|||
After user selects 'C', load `./step-04-architectural-patterns.md` to analyze architectural patterns, design decisions, and system structures for {{research_topic}}.
|
||||
|
||||
Remember: Always write research content to document immediately and emphasize current integration data with rigorous source verification!
|
||||
```
|
||||
|
|
|
|||
|
|
@ -29,6 +29,9 @@
|
|||
- All technical research sections have been completed (overview, architecture, implementation)
|
||||
- Web search capabilities with source verification are enabled
|
||||
- This is the final synthesis step producing the complete technical research document
|
||||
- **DeepWiki MCP** - Check `deepwiki_enabled` from frontmatter for Integration Research Findings section
|
||||
- **DeepWiki data** - If enabled, cross-repo analysis from step-03 should be synthesized here
|
||||
- **Query usage** - `deepwiki_queries_used` / `deepwiki_query_budget` for final reporting
|
||||
|
||||
## YOUR TASK:
|
||||
|
||||
|
|
@ -59,6 +62,7 @@ Produce a comprehensive, authoritative technical research document on **{{resear
|
|||
- Strategic Technical Recommendations
|
||||
- Implementation Roadmap and Risk Assessment
|
||||
- Future Technical Outlook and Innovation Opportunities
|
||||
- **Integration Research Findings** (if DeepWiki enabled)
|
||||
- Technical Research Methodology and Source Documentation
|
||||
- Technical Appendices and Reference Materials
|
||||
```
|
||||
|
|
@ -411,6 +415,190 @@ _This comprehensive technical research document serves as an authoritative techn
|
|||
**Ready to complete this comprehensive technical research document?**
|
||||
[C] Complete Research - Save final comprehensive technical document
|
||||
|
||||
### 5.5 Integration Research Findings (CONDITIONAL)
|
||||
|
||||
**⚠️ ONLY INCLUDE THIS SECTION IF `deepwiki_enabled: true` IN FRONTMATTER**
|
||||
|
||||
If DeepWiki was not enabled, skip this section entirely.
|
||||
|
||||
---
|
||||
|
||||
#### Integration Research Findings Section
|
||||
|
||||
Append to the final document before the Methodology section:
|
||||
|
||||
```markdown
|
||||
## Integration Research Findings [DEEPWIKI-ENHANCED]
|
||||
|
||||
**⚠️ READ THIS FIRST - For Downstream Agents (Architect, DEV)**
|
||||
|
||||
This section contains two types of findings:
|
||||
|
||||
- **[REPO-VERIFIED]**: Facts extracted directly from repository documentation via DeepWiki
|
||||
- **[LLM-SYNTHESIZED]**: Cross-repo patterns inferred by combining per-repo facts
|
||||
|
||||
**DO NOT** treat synthesized patterns as validated until POC checklist passes.
|
||||
|
||||
---
|
||||
|
||||
### Data Source Summary
|
||||
|
||||
| Repository | DeepWiki Indexed | Version | Queries Used |
|
||||
| ---------- | ---------------- | ----------- | ------------ |
|
||||
| {{repo_1}} | ✅ | {{version}} | {{queries}} |
|
||||
| {{repo_2}} | ✅ | {{version}} | {{queries}} |
|
||||
| {{repo_3}} | ✅/❌ | {{version}} | {{queries}} |
|
||||
|
||||
**Total DeepWiki Queries:** {{deepwiki_queries_used}} / {{deepwiki_query_budget}}
|
||||
|
||||
**Data Freshness Notice:** DeepWiki indexes repositories periodically. For production implementations, verify critical API signatures against current official documentation and release notes.
|
||||
|
||||
---
|
||||
|
||||
### Confidence Level Legend
|
||||
|
||||
| Label | Icon | Meaning | Action Required |
|
||||
| ------------------------- | ---- | -------------------------------------- | --------------------------------- |
|
||||
| `[REPO-VERIFIED]` | 🟢 | Direct from repo docs via DeepWiki | Normal confidence |
|
||||
| `[CROSS-REPO-DOCUMENTED]` | 🟡 | Explicit integration docs found (rare) | High confidence |
|
||||
| `[LLM-SYNTHESIZED]` | 🟠 | Combined from per-repo facts | **POC required before use** |
|
||||
| `[HYPOTHESIS-ONLY]` | 🔴 | Speculative, no supporting docs | **Do not use without validation** |
|
||||
|
||||
---
|
||||
|
||||
### Framework Compatibility Matrix
|
||||
|
||||
| Framework A | Framework B | Integration Pattern | Confidence | POC Status |
|
||||
| ------------------ | ------------------ | ------------------- | -------------------- | ---------------- |
|
||||
| {{repo_A}}@{{ver}} | {{repo_B}}@{{ver}} | {{pattern_summary}} | {{confidence_label}} | ⬜ Not validated |
|
||||
|
||||
---
|
||||
|
||||
### For Downstream Agents
|
||||
|
||||
#### For Architect Agent
|
||||
|
||||
When using this research for architecture decisions:
|
||||
|
||||
1. **[REPO-VERIFIED] facts**: Use with normal confidence for design decisions
|
||||
2. **[LLM-SYNTHESIZED] patterns**: Treat as hypotheses, not validated approaches
|
||||
3. **Before committing to an integration pattern**: Ensure DEV has validated via POC checklist
|
||||
4. **Version awareness**: Note the documented versions; your project may use different versions
|
||||
|
||||
#### For DEV Agent
|
||||
|
||||
When implementing based on this research:
|
||||
|
||||
1. **Start with POC validation**: Before full implementation, validate synthesized patterns
|
||||
2. **Use the POC checklists**: Each synthesized pattern has a validation checklist
|
||||
3. **Report discrepancies**: If actual behavior differs from research, flag for Analyst
|
||||
4. **Version check**: Verify your project's framework versions match documented versions
|
||||
|
||||
#### For UX Designer (CONDITIONAL - only if UI library repos were queried)
|
||||
|
||||
**⚠️ ONLY INCLUDE THIS SECTION IF `deepwiki_has_ui_repos: true` IN FRONTMATTER**
|
||||
|
||||
When using this research for design decisions:
|
||||
|
||||
1. **Component Capability Matrix**: Reference the matrix for available components and their variants
|
||||
2. **Theming System**: Check documented theming approach before designing custom themes
|
||||
3. **Composition Patterns**: Understand how components compose before designing complex UIs
|
||||
4. **Accessibility**: Note built-in accessibility features and gaps that need manual handling
|
||||
|
||||
##### UI Library Summary for UX Designers
|
||||
|
||||
| Library | Components | Theming | Dark Mode | Accessibility |
|
||||
| ---------- | ---------- | ---------- | ----------- | ------------- |
|
||||
| {{repo_1}} | {{count}} | {{method}} | {{support}} | {{level}} |
|
||||
| {{repo_2}} | {{count}} | {{method}} | {{support}} | {{level}} |
|
||||
|
||||
##### Component Availability Quick Reference
|
||||
|
||||
| Component Type | {{repo_1}} | {{repo_2}} | Notes |
|
||||
| --------------- | ---------- | ---------- | --------- |
|
||||
| Buttons | ✅/❌ | ✅/❌ | {{notes}} |
|
||||
| Forms/Inputs | ✅/❌ | ✅/❌ | {{notes}} |
|
||||
| Navigation | ✅/❌ | ✅/❌ | {{notes}} |
|
||||
| Data Display | ✅/❌ | ✅/❌ | {{notes}} |
|
||||
| Feedback/Alerts | ✅/❌ | ✅/❌ | {{notes}} |
|
||||
| Layout | ✅/❌ | ✅/❌ | {{notes}} |
|
||||
| Overlay/Modal | ✅/❌ | ✅/❌ | {{notes}} |
|
||||
|
||||
##### Theming Compatibility
|
||||
|
||||
| Aspect | {{repo_1}} | {{repo_2}} | Integration Notes |
|
||||
| ------------- | ----------- | ----------- | ----------------- |
|
||||
| CSS Variables | {{support}} | {{support}} | {{notes}} |
|
||||
| Design Tokens | {{support}} | {{support}} | {{notes}} |
|
||||
| Custom Themes | {{support}} | {{support}} | {{notes}} |
|
||||
| Color Schemes | {{support}} | {{support}} | {{notes}} |
|
||||
|
||||
##### Design System Recommendations [LLM-SYNTHESIZED]
|
||||
|
||||
Based on the component capability analysis:
|
||||
|
||||
1. **Primary UI Library**: {{recommendation}} - {{rationale}}
|
||||
2. **Supplement with**: {{recommendation}} - {{rationale}}
|
||||
3. **Custom Components Needed**: {{list of gaps}}
|
||||
4. **Accessibility Gaps to Address**: {{list}}
|
||||
|
||||
**⚠️ Note:** Design system recommendations are synthesized and should be validated with a UI prototype.
|
||||
|
||||
---
|
||||
|
||||
### POC Validation Summary
|
||||
|
||||
**⚠️ This research is INCOMPLETE until the following POC validations pass:**
|
||||
|
||||
#### {Repo A} ↔ {Repo B} Integration
|
||||
|
||||
**Pattern:** {{pattern_description}}
|
||||
**Confidence:** 🟠 [LLM-SYNTHESIZED]
|
||||
|
||||
**Validation Checklist:**
|
||||
|
||||
- [ ] {{Repo A}} API successfully called from integration code
|
||||
- [ ] {{Repo B}} receives data in expected format
|
||||
- [ ] Bidirectional communication works (if applicable)
|
||||
- [ ] Error handling propagates correctly across boundary
|
||||
- [ ] Performance acceptable for use case
|
||||
- [ ] No memory leaks or resource issues at boundary
|
||||
|
||||
**Unknown/Unverified:**
|
||||
|
||||
- [ ] Thread safety across framework boundaries
|
||||
- [ ] Lifecycle coordination between frameworks
|
||||
- [ ] Version compatibility for untested combinations
|
||||
|
||||
---
|
||||
|
||||
### Known Limitations and Gaps
|
||||
|
||||
Based on DeepWiki research, the following areas require additional investigation:
|
||||
|
||||
- [ ] {{Gap 1}}: {{description}}
|
||||
- [ ] {{Gap 2}}: {{description}}
|
||||
- [ ] {{Gap 3}}: {{description}}
|
||||
|
||||
---
|
||||
|
||||
### DeepWiki Query Audit Trail
|
||||
|
||||
For transparency and reproducibility:
|
||||
|
||||
| # | Repository | Query Purpose | Result Summary |
|
||||
| --- | ---------- | ------------------------- | ------------------- |
|
||||
| 1 | {{repo}} | Cross-reference detection | {{found/not found}} |
|
||||
| 2 | {{repo}} | Integration APIs | {{summary}} |
|
||||
| 3 | {{repo}} | Communication protocols | {{summary}} |
|
||||
| ... | ... | ... | ... |
|
||||
|
||||
**Research Date:** {{date}}
|
||||
**DeepWiki MCP Endpoint:** https://mcp.deepwiki.com/sse
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. Handle Final Technical Completion
|
||||
|
||||
#### If 'C' (Complete Research):
|
||||
|
|
@ -436,6 +624,26 @@ When user selects 'C', append the complete comprehensive technical research docu
|
|||
✅ [C] complete option presented and handled correctly
|
||||
✅ Technical research workflow completed with comprehensive document
|
||||
|
||||
### DeepWiki Success Metrics (if enabled):
|
||||
|
||||
✅ Integration Research Findings section included in final document
|
||||
✅ Data Source Summary with repo versions and query counts
|
||||
✅ Confidence Level Legend clearly displayed
|
||||
✅ Framework Compatibility Matrix populated
|
||||
✅ Downstream Agent Instructions for Architect and DEV
|
||||
✅ POC Validation Summary with all checklists aggregated
|
||||
✅ Known Limitations and Gaps documented
|
||||
✅ DeepWiki Query Audit Trail for transparency
|
||||
|
||||
### UI Library Success Metrics (if deepwiki_has_ui_repos: true):
|
||||
|
||||
✅ "For UX Designer" section included with guidance
|
||||
✅ UI Library Summary table populated
|
||||
✅ Component Availability Quick Reference matrix generated
|
||||
✅ Theming Compatibility matrix documented
|
||||
✅ Design System Recommendations with [LLM-SYNTHESIZED] label
|
||||
✅ Component Capability Matrix from step-03 referenced
|
||||
|
||||
## FAILURE MODES:
|
||||
|
||||
❌ Not producing compelling technical introduction
|
||||
|
|
@ -447,6 +655,24 @@ When user selects 'C', append the complete comprehensive technical research docu
|
|||
❌ Producing technical document without professional structure
|
||||
❌ Not presenting completion option for final technical document
|
||||
|
||||
### DeepWiki Failure Modes (if enabled):
|
||||
|
||||
❌ Not checking `deepwiki_enabled` before including Integration Research Findings
|
||||
❌ Missing Downstream Agent Instructions (Architect/DEV guidance)
|
||||
❌ Not including POC Validation Summary
|
||||
❌ Omitting confidence labels from final output
|
||||
❌ Not reporting total query usage
|
||||
❌ Missing Data Freshness Notice
|
||||
|
||||
### UI Library Failure Modes (if deepwiki_has_ui_repos: true):
|
||||
|
||||
❌ Not checking `deepwiki_has_ui_repos` before including UX Designer section
|
||||
❌ Missing UI Library Summary table
|
||||
❌ Not including Component Availability Quick Reference
|
||||
❌ Missing Theming Compatibility analysis
|
||||
❌ Design System Recommendations without [LLM-SYNTHESIZED] label
|
||||
❌ Not referencing Component Capability Matrix from step-03
|
||||
|
||||
❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
|
||||
❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
|
||||
❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
|
||||
|
|
|
|||
Loading…
Reference in New Issue