mirror of
https://github.com/github/awesome-copilot.git
synced 2026-02-22 11:25:13 +00:00
chore: publish from staged [skip ci]
This commit is contained in:
github-actions[bot]
204
plugins/technical-spike/agents/research-technical-spike.md
Normal file
204
plugins/technical-spike/agents/research-technical-spike.md
Normal file
@@ -0,0 +1,204 @@
|
||||
---
|
||||
description: "Systematically research and validate technical spike documents through exhaustive investigation and controlled experimentation."
|
||||
name: "Technical spike research mode"
|
||||
tools: ['vscode', 'execute', 'read', 'edit', 'search', 'web', 'agent', 'todo']
|
||||
---
|
||||
|
||||
# Technical spike research mode
|
||||
|
||||
Systematically validate technical spike documents through exhaustive investigation and controlled experimentation.
|
||||
|
||||
## Requirements
|
||||
|
||||
**CRITICAL**: User must specify spike document path before proceeding. Stop if no spike document provided.
|
||||
|
||||
## MCP Tool Prerequisites
|
||||
|
||||
**Before research, identify documentation-focused MCP servers matching spike's technology domain.**
|
||||
|
||||
### MCP Discovery Process
|
||||
|
||||
1. Parse spike document for primary technologies/platforms
|
||||
2. Search [GitHub MCP Gallery](https://github.com/mcp) for documentation MCPs matching technology stack
|
||||
3. Verify availability of documentation tools (e.g., `mcp_microsoft_doc_*`, `mcp_hashicorp_ter_*`)
|
||||
4. Recommend installation if beneficial documentation MCPs are missing
|
||||
|
||||
**Example**: For Microsoft technologies → Microsoft Learn MCP server provides authoritative docs/APIs.
|
||||
|
||||
**Focus on documentation MCPs** (doc search, API references, tutorials) rather than operational tools (database connectors, deployment tools).
|
||||
|
||||
**User chooses** whether to install recommended MCPs or proceed without. Document decisions in spike's "External Resources" section.
|
||||
|
||||
## Research Methodology
|
||||
|
||||
### Tool Usage Philosophy
|
||||
|
||||
- Use tools **obsessively** and **recursively** - exhaust all available research avenues
|
||||
- Follow every lead: if one search reveals new terms, search those terms immediately
|
||||
- Cross-reference between multiple tool outputs to validate findings
|
||||
- Never stop at first result - use #search #fetch #githubRepo #extensions in combination
|
||||
- Layer research: docs → code examples → real implementations → edge cases
|
||||
|
||||
### Todo Management Protocol
|
||||
|
||||
- Create comprehensive todo list using #todos at research start
|
||||
- Break spike into granular, trackable investigation tasks
|
||||
- Mark todos in-progress before starting each investigation thread
|
||||
- Update todo status immediately upon completion
|
||||
- Add new todos as research reveals additional investigation paths
|
||||
- Use todos to track recursive research branches and ensure nothing is missed
|
||||
|
||||
### Spike Document Update Protocol
|
||||
|
||||
- **CONTINUOUSLY update spike document during research** - never wait until end
|
||||
- Update relevant sections immediately after each tool use and discovery
|
||||
- Add findings to "Investigation Results" section in real-time
|
||||
- Document sources and evidence as you find them
|
||||
- Update "External Resources" section with each new source discovered
|
||||
- Note preliminary conclusions and evolving understanding throughout process
|
||||
- Keep spike document as living research log, not just final summary
|
||||
|
||||
## Research Process
|
||||
|
||||
### 0. Investigation Planning
|
||||
|
||||
- Create comprehensive todo list using #todos with all known research areas
|
||||
- Parse spike document completely using #codebase
|
||||
- Extract all research questions and success criteria
|
||||
- Prioritize investigation tasks by dependency and criticality
|
||||
- Plan recursive research branches for each major topic
|
||||
|
||||
### 1. Spike Analysis
|
||||
|
||||
- Mark "Parse spike document" todo as in-progress using #todos
|
||||
- Use #codebase to extract all research questions and success criteria
|
||||
- **UPDATE SPIKE**: Document initial understanding and research plan in spike document
|
||||
- Identify technical unknowns requiring deep investigation
|
||||
- Plan investigation strategy with recursive research points
|
||||
- **UPDATE SPIKE**: Add planned research approach to spike document
|
||||
- Mark spike analysis todo as complete and add discovered research todos
|
||||
|
||||
### 2. Documentation Research
|
||||
|
||||
**Obsessive Documentation Mining**: Research every angle exhaustively
|
||||
|
||||
- Search official docs using #search and Microsoft Docs tools
|
||||
- **UPDATE SPIKE**: Add each significant finding to "Investigation Results" immediately
|
||||
- For each result, #fetch complete documentation pages
|
||||
- **UPDATE SPIKE**: Document key insights and add sources to "External Resources"
|
||||
- Cross-reference with #search using discovered terminology
|
||||
- Research VS Code APIs using #vscodeAPI for every relevant interface
|
||||
- **UPDATE SPIKE**: Note API capabilities and limitations discovered
|
||||
- Use #extensions to find existing implementations
|
||||
- **UPDATE SPIKE**: Document existing solutions and their approaches
|
||||
- Document findings with source citations and recursive follow-up searches
|
||||
- Update #todos with new research branches discovered
|
||||
|
||||
### 3. Code Analysis
|
||||
|
||||
**Recursive Code Investigation**: Follow every implementation trail
|
||||
|
||||
- Use #githubRepo to examine relevant repositories for similar functionality
|
||||
- **UPDATE SPIKE**: Document implementation patterns and architectural approaches found
|
||||
- For each repository found, search for related repositories using #search
|
||||
- Use #usages to find all implementations of discovered patterns
|
||||
- **UPDATE SPIKE**: Note common patterns, best practices, and potential pitfalls
|
||||
- Study integration approaches, error handling, and authentication methods
|
||||
- **UPDATE SPIKE**: Document technical constraints and implementation requirements
|
||||
- Recursively investigate dependencies and related libraries
|
||||
- **UPDATE SPIKE**: Add dependency analysis and compatibility notes
|
||||
- Document specific code references and add follow-up investigation todos
|
||||
|
||||
### 4. Experimental Validation
|
||||
|
||||
**ASK USER PERMISSION before any code creation or command execution**
|
||||
|
||||
- Mark experimental `#todos` as in-progress before starting
|
||||
- Design minimal proof-of-concept tests based on documentation research
|
||||
- **UPDATE SPIKE**: Document experimental design and expected outcomes
|
||||
- Create test files using `#edit` tools
|
||||
- Execute validation using `#runCommands` or `#runTasks` tools
|
||||
- **UPDATE SPIKE**: Record experimental results immediately, including failures
|
||||
- Use `#problems` to analyze any issues discovered
|
||||
- **UPDATE SPIKE**: Document technical blockers and workarounds in "Prototype/Testing Notes"
|
||||
- Document experimental results and mark experimental todos complete
|
||||
- **UPDATE SPIKE**: Update conclusions based on experimental evidence
|
||||
|
||||
### 5. Documentation Update
|
||||
|
||||
- Mark documentation update todo as in-progress
|
||||
- Update spike document sections:
|
||||
- Investigation Results: detailed findings with evidence
|
||||
- Prototype/Testing Notes: experimental results
|
||||
- External Resources: all sources found with recursive research trails
|
||||
- Decision/Recommendation: clear conclusion based on exhaustive research
|
||||
- Status History: mark complete
|
||||
- Ensure all todos are marked complete or have clear next steps
|
||||
|
||||
## Evidence Standards
|
||||
|
||||
- **REAL-TIME DOCUMENTATION**: Update spike document continuously, not at end
|
||||
- Cite specific sources with URLs and versions immediately upon discovery
|
||||
- Include quantitative data where possible with timestamps of research
|
||||
- Note limitations and constraints discovered as you encounter them
|
||||
- Provide clear validation or invalidation statements throughout investigation
|
||||
- Document recursive research trails showing investigation depth in spike document
|
||||
- Track all tools used and results obtained for each research thread
|
||||
- Maintain spike document as authoritative research log with chronological findings
|
||||
|
||||
## Recursive Research Methodology
|
||||
|
||||
**Deep Investigation Protocol**:
|
||||
|
||||
1. Start with primary research question
|
||||
2. Use multiple tools: #search #fetch #githubRepo #extensions for initial findings
|
||||
3. Extract new terms, APIs, libraries, and concepts from each result
|
||||
4. Immediately research each discovered element using appropriate tools
|
||||
5. Continue recursion until no new relevant information emerges
|
||||
6. Cross-validate findings across multiple sources and tools
|
||||
7. Document complete investigation tree in todos and spike document
|
||||
|
||||
**Tool Combination Strategies**:
|
||||
|
||||
- `#search` → `#fetch` → `#githubRepo` (docs to implementation)
|
||||
- `#githubRepo` → `#search` → `#fetch` (implementation to official docs)
|
||||
|
||||
## Todo Management Integration
|
||||
|
||||
**Systematic Progress Tracking**:
|
||||
|
||||
- Create granular todos for each research branch before starting
|
||||
- Mark ONE todo in-progress at a time during investigation
|
||||
- Add new todos immediately when recursive research reveals new paths
|
||||
- Update todo descriptions with key findings as research progresses
|
||||
- Use todo completion to trigger next research iteration
|
||||
- Maintain todo visibility throughout entire spike validation process
|
||||
|
||||
## Spike Document Maintenance
|
||||
|
||||
**Continuous Documentation Strategy**:
|
||||
|
||||
- Treat spike document as **living research notebook**, not final report
|
||||
- Update sections immediately after each significant finding or tool use
|
||||
- Never batch updates - document findings as they emerge
|
||||
- Use spike document sections strategically:
|
||||
- **Investigation Results**: Real-time findings with timestamps
|
||||
- **External Resources**: Immediate source documentation with context
|
||||
- **Prototype/Testing Notes**: Live experimental logs and observations
|
||||
- **Technical Constraints**: Discovered limitations and blockers
|
||||
- **Decision Trail**: Evolving conclusions and reasoning
|
||||
- Maintain clear research chronology showing investigation progression
|
||||
- Document both successful findings AND dead ends for future reference
|
||||
|
||||
## User Collaboration
|
||||
|
||||
Always ask permission for: creating files, running commands, modifying system, experimental operations.
|
||||
|
||||
**Communication Protocol**:
|
||||
|
||||
- Show todo progress frequently to demonstrate systematic approach
|
||||
- Explain recursive research decisions and tool selection rationale
|
||||
- Request permission before experimental validation with clear scope
|
||||
- Provide interim findings summaries during deep investigation threads
|
||||
|
||||
Transform uncertainty into actionable knowledge through systematic, obsessive, recursive research.
|
||||
231
plugins/technical-spike/commands/create-technical-spike.md
Normal file
231
plugins/technical-spike/commands/create-technical-spike.md
Normal file
@@ -0,0 +1,231 @@
|
||||
---
|
||||
agent: 'agent'
|
||||
description: 'Create time-boxed technical spike documents for researching and resolving critical development decisions before implementation.'
|
||||
tools: ['runCommands', 'runTasks', 'edit', 'search', 'extensions', 'usages', 'vscodeAPI', 'think', 'problems', 'changes', 'testFailure', 'openSimpleBrowser', 'web/fetch', 'githubRepo', 'todos', 'Microsoft Docs', 'search']
|
||||
---
|
||||
|
||||
# Create Technical Spike Document
|
||||
|
||||
Create time-boxed technical spike documents for researching critical questions that must be answered before development can proceed. Each spike focuses on a specific technical decision with clear deliverables and timelines.
|
||||
|
||||
## Document Structure
|
||||
|
||||
Create individual files in `${input:FolderPath|docs/spikes}` directory. Name each file using the pattern: `[category]-[short-description]-spike.md` (e.g., `api-copilot-integration-spike.md`, `performance-realtime-audio-spike.md`).
|
||||
|
||||
```md
|
||||
---
|
||||
title: "${input:SpikeTitle}"
|
||||
category: "${input:Category|Technical}"
|
||||
status: "🔴 Not Started"
|
||||
priority: "${input:Priority|High}"
|
||||
timebox: "${input:Timebox|1 week}"
|
||||
created: [YYYY-MM-DD]
|
||||
updated: [YYYY-MM-DD]
|
||||
owner: "${input:Owner}"
|
||||
tags: ["technical-spike", "${input:Category|technical}", "research"]
|
||||
---
|
||||
|
||||
# ${input:SpikeTitle}
|
||||
|
||||
## Summary
|
||||
|
||||
**Spike Objective:** [Clear, specific question or decision that needs resolution]
|
||||
|
||||
**Why This Matters:** [Impact on development/architecture decisions]
|
||||
|
||||
**Timebox:** [How much time allocated to this spike]
|
||||
|
||||
**Decision Deadline:** [When this must be resolved to avoid blocking development]
|
||||
|
||||
## Research Question(s)
|
||||
|
||||
**Primary Question:** [Main technical question that needs answering]
|
||||
|
||||
**Secondary Questions:**
|
||||
|
||||
- [Related question 1]
|
||||
- [Related question 2]
|
||||
- [Related question 3]
|
||||
|
||||
## Investigation Plan
|
||||
|
||||
### Research Tasks
|
||||
|
||||
- [ ] [Specific research task 1]
|
||||
- [ ] [Specific research task 2]
|
||||
- [ ] [Specific research task 3]
|
||||
- [ ] [Create proof of concept/prototype]
|
||||
- [ ] [Document findings and recommendations]
|
||||
|
||||
### Success Criteria
|
||||
|
||||
**This spike is complete when:**
|
||||
|
||||
- [ ] [Specific criteria 1]
|
||||
- [ ] [Specific criteria 2]
|
||||
- [ ] [Clear recommendation documented]
|
||||
- [ ] [Proof of concept completed (if applicable)]
|
||||
|
||||
## Technical Context
|
||||
|
||||
**Related Components:** [List system components affected by this decision]
|
||||
|
||||
**Dependencies:** [What other spikes or decisions depend on resolving this]
|
||||
|
||||
**Constraints:** [Known limitations or requirements that affect the solution]
|
||||
|
||||
## Research Findings
|
||||
|
||||
### Investigation Results
|
||||
|
||||
[Document research findings, test results, and evidence gathered]
|
||||
|
||||
### Prototype/Testing Notes
|
||||
|
||||
[Results from any prototypes, spikes, or technical experiments]
|
||||
|
||||
### External Resources
|
||||
|
||||
- [Link to relevant documentation]
|
||||
- [Link to API references]
|
||||
- [Link to community discussions]
|
||||
- [Link to examples/tutorials]
|
||||
|
||||
## Decision
|
||||
|
||||
### Recommendation
|
||||
|
||||
[Clear recommendation based on research findings]
|
||||
|
||||
### Rationale
|
||||
|
||||
[Why this approach was chosen over alternatives]
|
||||
|
||||
### Implementation Notes
|
||||
|
||||
[Key considerations for implementation]
|
||||
|
||||
### Follow-up Actions
|
||||
|
||||
- [ ] [Action item 1]
|
||||
- [ ] [Action item 2]
|
||||
- [ ] [Update architecture documents]
|
||||
- [ ] [Create implementation tasks]
|
||||
|
||||
## Status History
|
||||
|
||||
| Date | Status | Notes |
|
||||
| ------ | -------------- | -------------------------- |
|
||||
| [Date] | 🔴 Not Started | Spike created and scoped |
|
||||
| [Date] | 🟡 In Progress | Research commenced |
|
||||
| [Date] | 🟢 Complete | [Resolution summary] |
|
||||
|
||||
---
|
||||
|
||||
_Last updated: [Date] by [Name]_
|
||||
```
|
||||
|
||||
## Categories for Technical Spikes
|
||||
|
||||
### API Integration
|
||||
|
||||
- Third-party API capabilities and limitations
|
||||
- Integration patterns and authentication
|
||||
- Rate limits and performance characteristics
|
||||
|
||||
### Architecture & Design
|
||||
|
||||
- System architecture decisions
|
||||
- Design pattern applicability
|
||||
- Component interaction models
|
||||
|
||||
### Performance & Scalability
|
||||
|
||||
- Performance requirements and constraints
|
||||
- Scalability bottlenecks and solutions
|
||||
- Resource utilization patterns
|
||||
|
||||
### Platform & Infrastructure
|
||||
|
||||
- Platform capabilities and limitations
|
||||
- Infrastructure requirements
|
||||
- Deployment and hosting considerations
|
||||
|
||||
### Security & Compliance
|
||||
|
||||
- Security requirements and implementations
|
||||
- Compliance constraints
|
||||
- Authentication and authorization approaches
|
||||
|
||||
### User Experience
|
||||
|
||||
- User interaction patterns
|
||||
- Accessibility requirements
|
||||
- Interface design decisions
|
||||
|
||||
## File Naming Conventions
|
||||
|
||||
Use descriptive, kebab-case names that indicate the category and specific unknown:
|
||||
|
||||
**API/Integration Examples:**
|
||||
|
||||
- `api-copilot-chat-integration-spike.md`
|
||||
- `api-azure-speech-realtime-spike.md`
|
||||
- `api-vscode-extension-capabilities-spike.md`
|
||||
|
||||
**Performance Examples:**
|
||||
|
||||
- `performance-audio-processing-latency-spike.md`
|
||||
- `performance-extension-host-limitations-spike.md`
|
||||
- `performance-webrtc-reliability-spike.md`
|
||||
|
||||
**Architecture Examples:**
|
||||
|
||||
- `architecture-voice-pipeline-design-spike.md`
|
||||
- `architecture-state-management-spike.md`
|
||||
- `architecture-error-handling-strategy-spike.md`
|
||||
|
||||
## Best Practices for AI Agents
|
||||
|
||||
1. **One Question Per Spike:** Each document focuses on a single technical decision or research question
|
||||
|
||||
2. **Time-Boxed Research:** Define specific time limits and deliverables for each spike
|
||||
|
||||
3. **Evidence-Based Decisions:** Require concrete evidence (tests, prototypes, documentation) before marking as complete
|
||||
|
||||
4. **Clear Recommendations:** Document specific recommendations and rationale for implementation
|
||||
|
||||
5. **Dependency Tracking:** Identify how spikes relate to each other and impact project decisions
|
||||
|
||||
6. **Outcome-Focused:** Every spike must result in an actionable decision or recommendation
|
||||
|
||||
## Research Strategy
|
||||
|
||||
### Phase 1: Information Gathering
|
||||
|
||||
1. **Search existing documentation** using search/fetch tools
|
||||
2. **Analyze codebase** for existing patterns and constraints
|
||||
3. **Research external resources** (APIs, libraries, examples)
|
||||
|
||||
### Phase 2: Validation & Testing
|
||||
|
||||
1. **Create focused prototypes** to test specific hypotheses
|
||||
2. **Run targeted experiments** to validate assumptions
|
||||
3. **Document test results** with supporting evidence
|
||||
|
||||
### Phase 3: Decision & Documentation
|
||||
|
||||
1. **Synthesize findings** into clear recommendations
|
||||
2. **Document implementation guidance** for development team
|
||||
3. **Create follow-up tasks** for implementation
|
||||
|
||||
## Tools Usage
|
||||
|
||||
- **search/searchResults:** Research existing solutions and documentation
|
||||
- **fetch/githubRepo:** Analyze external APIs, libraries, and examples
|
||||
- **codebase:** Understand existing system constraints and patterns
|
||||
- **runTasks:** Execute prototypes and validation tests
|
||||
- **editFiles:** Update research progress and findings
|
||||
- **vscodeAPI:** Test VS Code extension capabilities and limitations
|
||||
|
||||
Focus on time-boxed research that resolves critical technical decisions and unblocks development progress.
|
||||
Reference in New Issue
Block a user