id: "003" slug: 003-research-planning date: "2026-02-07" title: Research Planning preview: "Identifying unknowns in the roadmap and creating research directives for parallel investigation." prompts: - id: create-directives label: Create directives content: | /do-parallel for each topic, create a directive for our research team to research and write it in research-requests/{name}.md - id: deep-research label: Deep research (Gemini) content: | For each directive in research-requests/: 1. Open gemini.google.com/app 2. Click Tools → Deep Research 3. Paste the entire directive 4. Review the comprehensive report skillsUsed: - name: research-directive command: /research-directive description: Create research directives for deep research tools (Gemini Deep Research, Perplexity, etc.) usage: | --- name: research-directive description: Create research directives for deep research tools (Gemini Deep Research, Perplexity, etc.) --- You are a research architect who creates self-contained research directives. These directives are designed to be pasted directly into AI deep research tools like Gemini Deep Research. ## When to Use - Researching technical unknowns before implementation - Validating assumptions in architecture docs - Investigating feasibility of novel approaches - Finding prior art, papers, and implementations ## Directive Structure Every research directive follows this format: ```markdown # [Topic] Research Directive You are [Expert Name], [credentials]. [1-2 sentences on their expertise]. You are going to research [specific topic] to answer: [core question]. --- ## Context [Why this research matters. What decision depends on the answer.] --- ## Research Questions Answer these specific questions: 1. [Measurable question with success criteria] 2. [Measurable question with success criteria] 3. [Measurable question with success criteria] --- ## Methodology ### Phase 1: [First research phase] - [Specific search queries or sources] - [What to look for] ### Phase 2: [Second research phase] - [Deeper investigation] - [Cross-referencing] ### Phase 3: Synthesis - Compare findings across sources - Identify consensus vs. disagreement - Note gaps in available research --- ## Deliverables Produce a report with: 1. **Executive Summary** - Key findings in 3-5 bullets 2. **Detailed Findings** - Answer each research question 3. **Evidence** - Citations, benchmarks, code examples 4. **Recommendations** - What to do based on findings 5. **Open Questions** - What still needs investigation --- ## Success Criteria Research is complete when: - [ ] All research questions have evidence-based answers - [ ] Findings include specific numbers/benchmarks where applicable - [ ] Sources are cited and verifiable - [ ] Recommendations are actionable ``` ## Expert Selection Match the expert to the domain: | Domain | Expert Example | |--------|----------------| | Systems performance | Brendan Gregg | | Distributed systems | Martin Kleppmann | | Cryptography | Dan Boneh | | ML systems | Jeff Dean | | Mechanism design | Paul Milgrom | | Linux kernel | Linus Torvalds | | Databases | Andy Pavlo | ## Output Save directives to `research-requests/{topic-slug}.md` When creating multiple directives, use `/do-parallel`: ``` /do-parallel for each topic, create a research directive and write it to research-requests/{name}.md ``` ## Execution After creating directives: 1. Open [gemini.google.com/app](https://gemini.google.com/app) 2. Click **Tools → Deep Research** 3. Paste the entire directive 4. Wait 5-10 minutes for comprehensive report 5. Save results to `research/{topic-slug}.md` - name: do-parallel command: /do-parallel description: Execute tasks in parallel waves with optimal agent selection and review usage: | --- description: Execute tasks in parallel waves with optimal agent selection and review argument-hint: allowed-tools: Task, Read, Write, Edit, Glob, Grep, Bash, TodoWrite --- Execute these tasks in parallel waves with proper review: $ARGUMENTS ## Instructions Load the `orchestrated-execution` skill, then: ### Philosophy: Do It Right **Take your time. No shortcuts.** Every implementation should be: - **Clean** - Readable, well-named, minimal complexity - **Maintainable** - Future developers can understand and modify it - **Extensible** - Easy to add features without rewriting - **Refactored** - If existing code is messy, clean it up as you go When you encounter code that could be better: - Refactor it. Don't work around bad patterns. - Extract helpers, rename unclear variables, simplify nesting - Leave the codebase better than you found it **Prefer proper solutions over quick fixes.** A 50-line clean implementation beats a 10-line hack. ### Phase 1: Parse & Analyze 1. **Parse tasks** - From todo list or provided 2. **Analyze dependencies** - Which tasks depend on which 3. **Group into waves** - Tasks without mutual dependencies go in same wave ### Phase 2: Wave Planning For each wave, determine: ```markdown ## Wave [N] | Task | Implementer | Why | Reviewer | Why | |------|-------------|-----|----------|-----| | [Name] | [Agent] | [domain match] | [Agent] | [risk match] | **Parallelizable because:** [No dependencies between these tasks] **Blocked until:** [Wave N-1 complete] or [Nothing] ``` Present the wave plan to user before executing. ### Phase 3: Execute Each Wave ``` Wave N: ┌─────────────────────────────────────────────┐ │ 1. LAUNCH ALL IMPLEMENTERS (parallel) │ │ │ │ Task(agent1, task1) ──┐ │ │ Task(agent2, task2) ──┼── concurrent │ │ Task(agent3, task3) ──┘ │ └─────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────┐ │ 2. COLLECT RESULTS │ │ Wait for all to complete │ │ Gather implementation outputs │ └─────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────┐ │ 3. LAUNCH ALL REVIEWERS (parallel) │ │ │ │ Task(reviewer1, review1) ──┐ │ │ Task(reviewer2, review2) ──┼── concurrent│ │ Task(reviewer3, review3) ──┘ │ └─────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────┐ │ 4. PROCESS REVIEW RESULTS │ │ │ │ PASS → mark complete │ │ NEEDS_FIX → fix loop (can parallelize) │ │ BLOCK → escalate immediately │ └─────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────┐ │ 5. VERIFY WAVE COMPLETE │ │ All tasks in wave done? │ │ Any conflicts from parallel execution? │ └─────────────────────────────────────────────┘ │ ▼ Continue to Wave N+1 ``` ### Phase 4: Loose Ends (Critical for Parallel) After all waves, explicitly check: 1. **File conflicts** - Did parallel tasks modify same files? 2. **Integration gaps** - Do the pieces work together? 3. **Merge issues** - Any conflicting changes to resolve? 4. **Cross-cutting** - Consistent patterns across all tasks? 5. **Quality gate** - Full build, test, lint ### Phase 5: Final Report ```markdown ## Parallel Execution Complete ### Wave Summary | Wave | Tasks | Parallel Time | Status | |------|-------|---------------|--------| | 1 | 3 | ~2min | ✓ | | 2 | 2 | ~1min | ✓ | | 3 | 1 | ~1min | ✓ | ### Task Details | Task | Wave | Implementer | Reviewer | Issues Fixed | Status | |------|------|-------------|----------|--------------|--------| ### Loose Ends Resolved - [Conflicts fixed] - [Integration issues addressed] ### Quality Gate - Build: PASS - Tests: PASS - Lint: PASS ``` ## Dependency Detection Tasks depend on each other when: ``` Task A: "Create User model" Task B: "Add validation to User model" ← Depends on A Task A: "Implement auth backend" Task B: "Write auth tests" ← Depends on A Task A: "Update config schema" Task B: "Migrate existing configs" ← Depends on A ``` Tasks are independent when: ``` Task A: "Add logging to ingestion" Task B: "Add metrics to query" ← Different modules, independent Task A: "Write User docs" Task B: "Write Config docs" ← Different files, independent ``` ## Agent Selection ### Implementers Select agents based on the task domain. Examples: | Task Type | Agent Example | |-----------|---------------| | Backend code | `primary-developer` | | Tests | `quality-engineer` | | Auth | `auth-engineer` | | Storage | `storage-architect` | | K8s/Ops | `ops-engineer` | | UI | `ux-prototyper` | | Docs | `tech-doc-writer` | Check `~/.claude/agents/` for available agents. ### Reviewers | Risk Type | Reviewer Example | |-----------|------------------| | Code quality | `quality-engineer` | | Security | `security-reviewer` | | Performance | `performance-lead` | | E2E | `e2e-validator` | ## Critical Rules - NEVER put dependent tasks in same wave - ALWAYS review even in parallel mode - ALWAYS check for conflicts after parallel execution - ALWAYS run quality gate at the end - ANNOUNCE wave plan before executing - MAX 3 fix cycles per task, then escalate filesCreated: - name: firecracker-latency-benchmarks.md description: Benchmarking pause/resume latency for thermal emergencies - name: ebpf-overhead-validation.md description: Validating eBPF instrumentation overhead under production load - name: rapl-accuracy-calibration.md description: Calibrating Intel RAPL power reporting accuracy across hardware - name: thermal-time-constant-validation.md description: Measuring actual thermal time constants for different hardware - name: thermal-coupling-measurement.md description: Quantifying heat transfer between adjacent cores - name: gsp-thermal-stability.md description: Analyzing GSP auction stability under thermal dynamics - name: high-frequency-auction-research.md description: Researching 100Hz market clearing without CPU overhead - name: power-trace-verification.md description: Distinguishing inference from mining via power signatures - name: proof-of-inference.md description: Cryptographic verification of ML workload execution - name: thermal-gossip-consensus-research.md description: Coordinating thermal state across distributed clusters navigation: prev: slug: 002-building-the-scaffolding id: "002" title: Understanding the Project next: slug: 004-hydrating-the-roadmap id: "004" title: Hydrating the Roadmap