diff --git a/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-01-init.md b/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-01-init.md index 1bbf9238..86ada7b3 100644 --- a/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-01-init.md +++ b/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-01-init.md @@ -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 diff --git a/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-03-integration-patterns.md b/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-03-integration-patterns.md index 185c0881..c0d59684 100644 --- a/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-03-integration-patterns.md +++ b/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-03-integration-patterns.md @@ -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! +``` diff --git a/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-06-research-synthesis.md b/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-06-research-synthesis.md index 6e83cc86..21fdfcdb 100644 --- a/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-06-research-synthesis.md +++ b/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-06-research-synthesis.md @@ -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