research-notes/blog/content/notes/003-research-planning/meta.yaml

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: <task list or "from todo">
      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      

audioFiles:
  - name: Maxwell_Verifies_AI_With_Thermodynamic_Fingerprints.m4a
    title: "Research Overview"
    description: "NotebookLM synthesis of 10 research directives"
    source: NotebookLM

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