Research

Write a research prompt document — a structured set of questions designed to guide deep technical investigation of a domain. The output is a markdown file that can be fed to an AI (or used by the agent itself) for thorough research.

You are writing QUESTIONS, not answers. Do not research the topic yourself. Do not include findings, recommendations, or pre-baked conclusions. The entire point is to produce a document that drives research — not to do the research.

Workflow

Step 1: Understand the Topic

Ask the user what they want to research if it's not clear. Understand:

• What are they trying to build or decide?
• What do they already have? (Existing code, tools, context)
• What's the pain point driving this research?
• How far does it need to scale?

Step 2: Find the Research Prompts Folder

Look for an existing docs/research_prompts/ folder in the project. If it exists, read 1-2 existing prompts to match the project's established format and voice. If no folder exists, create docs/research_prompts/.

Step 3: Write the Prompt

Follow the format below exactly. Write it to docs/research_prompts/<topic-slug>.md.

Format

Every research prompt follows this structure:

# Research Prompt: <Clear Descriptive Title>

## Objective

1-2 paragraphs. What are we researching and why. State the core question in bold.
Frame it as exploration, not as a spec. Don't prescribe the answer.

## Context

### Current State / Pain Point
What exists today. What's broken or insufficient. Be specific — reference
actual code, tools, numbers. This grounds the research in reality.

### What We Want
Bullet list of desired capabilities. What the end state looks like.
Keep it high-level — the research should figure out HOW, not be told how.

## Key Questions

### 0. <First Major Topic Area>

0a. **<Specific sub-question>**
    - Concrete question that demands investigation
    - Follow-up angle or related concern
    - "How does X handle this?" type comparative question

0b. **<Next sub-question>**
    - ...

### 1. <Second Major Topic Area>

1a. **<Sub-question>**
    - ...

### 2. <Third Major Topic Area>
...

(Continue with as many sections as the topic demands. Typical range: 4-8 sections.)

## Desired Output

What the research should produce. NOT the answers — but the SHAPE of the answers.
Bullet list of deliverables:
- Recommendations on approach X vs Y
- Architecture diagram for Z
- Performance analysis at scale
- Trade-off matrix
- Phased roadmap
- etc.

Rules

1. Questions only. Never include answers, findings, recommendations, or conclusions in the prompt. If you know something about the topic, formulate it as a question that would uncover that knowledge — don't state it as fact.

1. Match existing voice. If the project already has research prompts, read them and match the tone, depth, and structure. Some projects are more technical, some more strategic. Adapt.

1. Be specific, not vague. Bad: "How does performance work?" Good: "At 5,000 building instances with Nanite enabled, what are the real bottlenecks — draw calls, ISM actor count, GPU memory, or CPU transform computation?"

1. Ground in context. Reference the project's actual code, tools, pain points, and existing systems. The prompt should feel like it was written by someone who knows the codebase, not a generic template.

1. Hierarchical questions. Major sections (0, 1, 2...) for broad topic areas. Lettered sub-questions (a, b, c...) for specific angles within each area. Sub-bullets for follow-up concerns or comparative angles.

1. Include "how do others do it" questions. For every major topic, ask how production systems, established tools, or industry leaders approach the same problem. Name specific systems (CitySample, Houdini, CityEngine, etc. — whatever's relevant to the domain).

1. Scale questions. Always include questions about how the approach scales — from small to large, from prototype to production.

1. Build-or-borrow questions. If there are existing tools/systems that could solve part of the problem, ask about them explicitly. "Should we build custom X or integrate existing Y? What do we gain and lose?"

1. End with Desired Output. List what the research should produce — not the content, but the format. (Recommendation, architecture, comparison matrix, roadmap, etc.)

1. No emojis, no fluff. Professional, direct, technical. The prompt should feel like a senior engineer scoping out a hard problem.

What NOT to Do

• Don't research the topic. Don't search the web, don't read docs, don't look up how things work. Just write the questions.
• Don't write a spec. A research prompt explores the space. A spec prescribes the solution. These are different documents.
• Don't pad with obvious questions. Every question should require real investigation to answer. Skip anything that could be answered with 5 seconds of thought.
• Don't add preamble or meta-commentary. No "This document aims to..." — just write the prompt.
• Don't include references/links unless the user provides them. The research will find its own sources.