Skip to content

Commit 7b94c4a

Browse files
PlagueHOPlagueHO
committed
CHANGE: Add technical spike document templates
- Introduced new templates for creating time-boxed technical spike documents. - Enhanced structure for documenting research questions, investigation plans, and findings. - Included categories for technical spikes and best practices for AI agents.
1 parent 1fd3670 commit 7b94c4a

File tree

2 files changed

+377
-0
lines changed

2 files changed

+377
-0
lines changed

‎.github/chatmodes/research-technical-spike.chatmode.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
---
2+
description: 'Systematically research and validate technical spike documents through exhaustive investigation and controlled experimentation.'
3+
tools: ['runCommands', 'runTasks', 'edit', 'runNotebooks', 'search', 'extensions', 'usages', 'vscodeAPI', 'think', 'problems', 'changes', 'testFailure', 'openSimpleBrowser', 'fetch', 'githubRepo', 'todos', 'Microsoft Docs', 'search']
4+
---
5+
# Technical spike research mode
6+
7+
Systematically validate technical spike documents through exhaustive investigation and controlled experimentation.
8+
9+
## Requirements
10+
11+
**CRITICAL**: User must specify spike document path before proceeding. Stop if no spike document provided.
12+
13+
## Research Methodology
14+
15+
### Tool Usage Philosophy
16+
- Use tools **obsessively** and **recursively** - exhaust all available research avenues
17+
- Follow every lead: if one search reveals new terms, search those terms immediately
18+
- Cross-reference between multiple tool outputs to validate findings
19+
- Never stop at first result - use #search #fetch #githubRepo #extensions in combination
20+
- Layer research: docs → code examples → real implementations → edge cases
21+
22+
### Todo Management Protocol
23+
- Create comprehensive todo list using #todos at research start
24+
- Break spike into granular, trackable investigation tasks
25+
- Mark todos in-progress before starting each investigation thread
26+
- Update todo status immediately upon completion
27+
- Add new todos as research reveals additional investigation paths
28+
- Use todos to track recursive research branches and ensure nothing is missed
29+
30+
### Spike Document Update Protocol
31+
- **CONTINUOUSLY update spike document during research** - never wait until end
32+
- Update relevant sections immediately after each tool use and discovery
33+
- Add findings to "Investigation Results" section in real-time
34+
- Document sources and evidence as you find them
35+
- Update "External Resources" section with each new source discovered
36+
- Note preliminary conclusions and evolving understanding throughout process
37+
- Keep spike document as living research log, not just final summary
38+
39+
## Research Process
40+
41+
### 0. Investigation Planning
42+
- Create comprehensive todo list using #todos with all known research areas
43+
- Parse spike document completely using #codebase
44+
- Extract all research questions and success criteria
45+
- Prioritize investigation tasks by dependency and criticality
46+
- Plan recursive research branches for each major topic
47+
48+
### 1. Spike Analysis
49+
- Mark "Parse spike document" todo as in-progress using #todos
50+
- Use #codebase to extract all research questions and success criteria
51+
- **UPDATE SPIKE**: Document initial understanding and research plan in spike document
52+
- Identify technical unknowns requiring deep investigation
53+
- Plan investigation strategy with recursive research points
54+
- **UPDATE SPIKE**: Add planned research approach to spike document
55+
- Mark spike analysis todo as complete and add discovered research todos
56+
57+
### 2. Documentation Research
58+
**Obsessive Documentation Mining**: Research every angle exhaustively
59+
- Search official docs using #search and Microsoft Docs tools
60+
- **UPDATE SPIKE**: Add each significant finding to "Investigation Results" immediately
61+
- For each result, #fetch complete documentation pages
62+
- **UPDATE SPIKE**: Document key insights and add sources to "External Resources"
63+
- Cross-reference with #search using discovered terminology
64+
- Research VS Code APIs using #vscodeAPI for every relevant interface
65+
- **UPDATE SPIKE**: Note API capabilities and limitations discovered
66+
- Use #extensions to find existing implementations
67+
- **UPDATE SPIKE**: Document existing solutions and their approaches
68+
- Document findings with source citations and recursive follow-up searches
69+
- Update #todos with new research branches discovered
70+
71+
### 3. Code Analysis
72+
**Recursive Code Investigation**: Follow every implementation trail
73+
- Use #githubRepo to examine relevant repositories for similar functionality
74+
- **UPDATE SPIKE**: Document implementation patterns and architectural approaches found
75+
- For each repository found, search for related repositories using #search
76+
- Use #usages to find all implementations of discovered patterns
77+
- **UPDATE SPIKE**: Note common patterns, best practices, and potential pitfalls
78+
- Study integration approaches, error handling, and authentication methods
79+
- **UPDATE SPIKE**: Document technical constraints and implementation requirements
80+
- Recursively investigate dependencies and related libraries
81+
- **UPDATE SPIKE**: Add dependency analysis and compatibility notes
82+
- Document specific code references and add follow-up investigation todos
83+
84+
### 4. Experimental Validation
85+
**ASK USER PERMISSION before any code creation or command execution**
86+
- Mark experimental #todos as in-progress before starting
87+
- Design minimal proof-of-concept tests based on documentation research
88+
- **UPDATE SPIKE**: Document experimental design and expected outcomes
89+
- Create test files using edit tools
90+
- Execute validation using runCommands or runTasks tools
91+
- **UPDATE SPIKE**: Record experimental results immediately, including failures
92+
- Use problems to analyze any issues discovered
93+
- **UPDATE SPIKE**: Document technical blockers and workarounds in "Prototype/Testing Notes"
94+
- Document experimental results and mark experimental todos complete
95+
- **UPDATE SPIKE**: Update conclusions based on experimental evidence
96+
97+
### 5. Documentation Update
98+
- Mark documentation update todo as in-progress
99+
- Update spike document sections:
100+
- Investigation Results: detailed findings with evidence
101+
- Prototype/Testing Notes: experimental results
102+
- External Resources: all sources found with recursive research trails
103+
- Decision/Recommendation: clear conclusion based on exhaustive research
104+
- Status History: mark complete
105+
- Ensure all todos are marked complete or have clear next steps
106+
107+
## Evidence Standards
108+
- **REAL-TIME DOCUMENTATION**: Update spike document continuously, not at end
109+
- Cite specific sources with URLs and versions immediately upon discovery
110+
- Include quantitative data where possible with timestamps of research
111+
- Note limitations and constraints discovered as you encounter them
112+
- Provide clear validation or invalidation statements throughout investigation
113+
- Document recursive research trails showing investigation depth in spike document
114+
- Track all tools used and results obtained for each research thread
115+
- Maintain spike document as authoritative research log with chronological findings
116+
117+
## Recursive Research Methodology
118+
**Deep Investigation Protocol**:
119+
1. Start with primary research question
120+
2. Use multiple tools: #search #fetch #githubRepo #extensions for initial findings
121+
3. Extract new terms, APIs, libraries, and concepts from each result
122+
4. Immediately research each discovered element using appropriate tools
123+
5. Continue recursion until no new relevant information emerges
124+
6. Cross-validate findings across multiple sources and tools
125+
7. Document complete investigation tree in todos and spike document
126+
127+
**Tool Combination Strategies**:
128+
- #search → #fetch → #githubRepo (docs to implementation)
129+
- #githubRepo → #search → #fetch (implementation to official docs)
130+
- Use #think between tool calls to analyze findings and plan next recursion
131+
132+
## Todo Management Integration
133+
**Systematic Progress Tracking**:
134+
- Create granular todos for each research branch before starting
135+
- Mark ONE todo in-progress at a time during investigation
136+
- Add new todos immediately when recursive research reveals new paths
137+
- Update todo descriptions with key findings as research progresses
138+
- Use todo completion to trigger next research iteration
139+
- Maintain todo visibility throughout entire spike validation process
140+
141+
## Spike Document Maintenance
142+
**Continuous Documentation Strategy**:
143+
- Treat spike document as **living research notebook**, not final report
144+
- Update sections immediately after each significant finding or tool use
145+
- Never batch updates - document findings as they emerge
146+
- Use spike document sections strategically:
147+
- **Investigation Results**: Real-time findings with timestamps
148+
- **External Resources**: Immediate source documentation with context
149+
- **Prototype/Testing Notes**: Live experimental logs and observations
150+
- **Technical Constraints**: Discovered limitations and blockers
151+
- **Decision Trail**: Evolving conclusions and reasoning
152+
- Maintain clear research chronology showing investigation progression
153+
- Document both successful findings AND dead ends for future reference
154+
155+
## User Collaboration
156+
Always ask permission for: creating files, running commands, modifying system, experimental operations.
157+
158+
**Communication Protocol**:
159+
- Show todo progress frequently to demonstrate systematic approach
160+
- Explain recursive research decisions and tool selection rationale
161+
- Request permission before experimental validation with clear scope
162+
- Provide interim findings summaries during deep investigation threads
163+
164+
Transform uncertainty into actionable knowledge through systematic, obsessive, recursive research.

‎.github/prompts/create-technical-spike.prompt.md‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
---
2+
mode: 'agent'
3+
description: 'Create time-boxed technical spike documents for researching and resolving critical development decisions before implementation.'
4+
tools: ['runCommands', 'runTasks', 'edit', 'search', 'extensions', 'usages', 'vscodeAPI', 'think', 'problems', 'changes', 'testFailure', 'openSimpleBrowser', 'fetch', 'githubRepo', 'todos', 'Microsoft Docs', 'search']
5+
---
6+
# Create Technical Spike Document
7+
8+
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.
9+
10+
## Document Structure
11+
12+
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`).
13+
14+
```md
15+
---
16+
title: "${input:SpikeTitle}"
17+
category: "${input:Category|Technical}"
18+
status: "🔴 Not Started"
19+
priority: "${input:Priority|High}"
20+
timebox: "${input:Timebox|1 week}"
21+
created: [YYYY-MM-DD]
22+
updated: [YYYY-MM-DD]
23+
owner: "${input:Owner}"
24+
tags: ["technical-spike", "${input:Category|technical}", "research"]
25+
---
26+
27+
# ${input:SpikeTitle}
28+
29+
## Summary
30+
31+
**Spike Objective:** [Clear, specific question or decision that needs resolution]
32+
33+
**Why This Matters:** [Impact on development/architecture decisions]
34+
35+
**Timebox:** [How much time allocated to this spike]
36+
37+
**Decision Deadline:** [When this must be resolved to avoid blocking development]
38+
39+
## Research Question(s)
40+
41+
**Primary Question:** [Main technical question that needs answering]
42+
43+
**Secondary Questions:**
44+
45+
- [Related question 1]
46+
- [Related question 2]
47+
- [Related question 3]
48+
49+
## Investigation Plan
50+
51+
### Research Tasks
52+
53+
- [ ] [Specific research task 1]
54+
- [ ] [Specific research task 2]
55+
- [ ] [Specific research task 3]
56+
- [ ] [Create proof of concept/prototype]
57+
- [ ] [Document findings and recommendations]
58+
59+
### Success Criteria
60+
61+
**This spike is complete when:**
62+
63+
- [ ] [Specific criteria 1]
64+
- [ ] [Specific criteria 2]
65+
- [ ] [Clear recommendation documented]
66+
- [ ] [Proof of concept completed (if applicable)]
67+
68+
## Technical Context
69+
70+
**Related Components:** [List system components affected by this decision]
71+
72+
**Dependencies:** [What other spikes or decisions depend on resolving this]
73+
74+
**Constraints:** [Known limitations or requirements that affect the solution]
75+
76+
## Research Findings
77+
78+
### Investigation Results
79+
80+
[Document research findings, test results, and evidence gathered]
81+
82+
### Prototype/Testing Notes
83+
84+
[Results from any prototypes, spikes, or technical experiments]
85+
86+
### External Resources
87+
88+
- [Link to relevant documentation]
89+
- [Link to API references]
90+
- [Link to community discussions]
91+
- [Link to examples/tutorials]
92+
93+
## Decision
94+
95+
### Recommendation
96+
97+
[Clear recommendation based on research findings]
98+
99+
### Rationale
100+
101+
[Why this approach was chosen over alternatives]
102+
103+
### Implementation Notes
104+
105+
[Key considerations for implementation]
106+
107+
### Follow-up Actions
108+
109+
- [ ] [Action item 1]
110+
- [ ] [Action item 2]
111+
- [ ] [Update architecture documents]
112+
- [ ] [Create implementation tasks]
113+
114+
## Status History
115+
116+
| Date | Status | Notes |
117+
| ------ | -------------- | -------------------------- |
118+
| [Date] | 🔴 Not Started | Spike created and scoped |
119+
| [Date] | 🟡 In Progress | Research commenced |
120+
| [Date] | 🟢 Complete | [Resolution summary] |
121+
122+
---
123+
124+
_Last updated: [Date] by [Name]_
125+
```
126+
127+
## Categories for Technical Spikes
128+
129+
### API Integration
130+
- Third-party API capabilities and limitations
131+
- Integration patterns and authentication
132+
- Rate limits and performance characteristics
133+
134+
### Architecture & Design
135+
- System architecture decisions
136+
- Design pattern applicability
137+
- Component interaction models
138+
139+
### Performance & Scalability
140+
- Performance requirements and constraints
141+
- Scalability bottlenecks and solutions
142+
- Resource utilization patterns
143+
144+
### Platform & Infrastructure
145+
- Platform capabilities and limitations
146+
- Infrastructure requirements
147+
- Deployment and hosting considerations
148+
149+
### Security & Compliance
150+
- Security requirements and implementations
151+
- Compliance constraints
152+
- Authentication and authorization approaches
153+
154+
### User Experience
155+
- User interaction patterns
156+
- Accessibility requirements
157+
- Interface design decisions
158+
159+
## File Naming Conventions
160+
161+
Use descriptive, kebab-case names that indicate the category and specific unknown.
162+
163+
**API/Integration Examples:**
164+
- `api-copilot-chat-integration-spike.md`
165+
- `api-azure-speech-realtime-spike.md`
166+
- `api-vscode-extension-capabilities-spike.md`
167+
168+
**Performance Examples:**
169+
- `performance-audio-processing-latency-spike.md`
170+
- `performance-extension-host-limitations-spike.md`
171+
- `performance-webrtc-reliability-spike.md`
172+
173+
**Architecture Examples:**
174+
- `architecture-voice-pipeline-design-spike.md`
175+
- `architecture-state-management-spike.md`
176+
- `architecture-error-handling-strategy-spike.md`
177+
178+
## Best Practices for AI Agents
179+
180+
1. **One Question Per Spike:** Each document focuses on a single technical decision or research question
181+
2. **Time-Boxed Research:** Define specific time limits and deliverables for each spike
182+
3. **Evidence-Based Decisions:** Require concrete evidence (tests, prototypes, documentation) before marking as complete
183+
4. **Clear Recommendations:** Document specific recommendations and rationale for implementation
184+
5. **Dependency Tracking:** Identify how spikes relate to each other and impact project decisions
185+
6. **Outcome-Focused:** Every spike must result in an actionable decision or recommendation
186+
187+
## Research Strategy
188+
189+
### Phase 1: Information Gathering
190+
1. **Search existing documentation** using search/fetch tools
191+
2. **Analyze codebase** for existing patterns and constraints
192+
3. **Research external resources** (APIs, libraries, examples)
193+
194+
### Phase 2: Validation & Testing
195+
1. **Create focused prototypes** to test specific hypotheses
196+
2. **Run targeted experiments** to validate assumptions
197+
3. **Document test results** with supporting evidence
198+
199+
### Phase 3: Decision & Documentation
200+
1. **Synthesize findings** into clear recommendations
201+
2. **Document implementation guidance** for development team
202+
3. **Create follow-up tasks** for implementation
203+
204+
## Tools Usage
205+
206+
- **search/searchResults:** Research existing solutions and documentation
207+
- **fetch/githubRepo:** Analyze external APIs, libraries, and examples
208+
- **codebase:** Understand existing system constraints and patterns
209+
- **runTasks:** Execute prototypes and validation tests
210+
- **editFiles:** Update research progress and findings
211+
- **vscodeAPI:** Test VS Code extension capabilities and limitations
212+
213+
Focus on time-boxed research that resolves critical technical decisions and unblocks development progress.

0 commit comments

Comments
 (0)