Scaffold a new research question (or sub-question) with the standard folder structure, README, KNOWLEDGE.md, and IDEALOG.md. Use when starting a new investigation.
Scaffold a new research question or sub-question with the standard structure.
Input: $ARGUMENTS
MASTER.md — project dashboard (update when adding questions)
Research/Active/{question}/ — active research (README.md, KNOWLEDGE.md, literature/, papers/, figures/)
Research/Complete/{question}/ — answered questions
Research/Backlog/{question}/ — parked questions
Research/Knowledge/ — promoted knowledge files from Complete questions
{Engine}/experiments/{experiment}/ — code + outputs (EXPERIMENT.md with backlinks, run.py, outputs/)
Engines/cross_engine/{question}/ — cross-engine experiments
Research/ = writing only (no .py). Engines/ = code only.
Determine whether this is a top-level question or a sub-question:
"anisotropic boundaries" → top-level in Research/Active/"boundary_conduction_speedup/anisotropic_boundaries" → sub-question under existing parentIf the input looks like a sub-question (contains /), verify the parent exists in Research/Active/. If it doesn't, ask the user whether to create the parent first.
Convert the question name to a folder name:
boundary_conduction_speedup, hipsc_cm_ionic_models, anisotropic_boundariesBefore scaffolding, gather:
If the user already provided enough context (e.g., from a conversation), infer the answers and confirm rather than asking.
Research/Active/{question_name}/
├── README.md
├── KNOWLEDGE.md
├── IDEALOG.md
├── WHITEBOARD.md # Ephemeral diagrams for tmux workspace
├── literature/ # Paper summaries go here
├── papers/ # PDFs go here
├── code_examples/ # Reference implementations (if any)
├── results/ # Simulation outputs, data, plots
└── plans/ # Archived completed PLAN.md files
Research/Active/{parent}/{sub_question_name}/
├── README.md
└── results/
Sub-questions are lightweight. They share the parent's literature/, papers/, and code_examples/ unless they grow large enough to need their own.
After creating the folder, rename the tmux window to the question's readable title:
tmux rename-window "{Question Title}" 2>/dev/null
(Capitalize each word, e.g., "Boundary Conduction Speedup".) For sub-questions, use the sub-question title.
# {Question Title}
## Question
{One sentence — the specific thing we're trying to answer}
## Status: Active
## Why It Matters
{1-2 sentences — what depends on the answer, which engines/pipelines are affected}
## Engines
{List of engines this touches, with what role each plays}
## Completion Criteria
- [ ] {Concrete criterion 1}
- [ ] {Concrete criterion 2}
- [ ] ...
## Sub-Questions
| Sub-Question | Status | Key Finding |
|-------------|--------|-------------|
| {sub if any} | — | — |
## Key Findings So Far
{Empty initially — updated as work progresses}
## Literature
| Paper | Summary | Key Insight |
|-------|---------|-------------|
| {empty initially} | | |
## Future Work
{No deferred items yet.}
# {Sub-Question Title}
**Parent**: [{parent name}](../README.md)
## Question
{One sentence}
## Status: Active
## Completion Criteria
- [ ] {criterion}
## Findings
{Empty initially}
Only for top-level questions (sub-questions contribute to the parent's KNOWLEDGE.md).
# {Question Title} — Knowledge File
> This file is a running synthesis. Updated as findings accumulate.
> When the question is complete, a copy is promoted to `Research/Knowledge/`.
## Current Understanding
{What we know so far — even if just "nothing yet, starting investigation"}
## Key Decisions
{Decisions made based on this research, with rationale}
## Open Questions
{Things we still don't know}
## Connections
- **Engines**: {which engines implement or depend on this}
- **Related research**: {links to other research questions that interact}
- **Pipelines**: {Optimizer, Surrogate, Builder if relevant}
Only for top-level questions (sub-questions don't get their own IDEALOG.md).
# {Question Title} — Idea Log
> Thinking trail: how our understanding evolved, what we tried, what failed.
> Scan this in 30 seconds to remember where we are and how we got here.
> Not promoted on completion — archived for historical record.
## Current Direction
{What we're currently pursuing and why — same as README.md status initially}
## Next Step
{First step from completion criteria}
## Thread
## Failed Approaches
## Session Log
Add a row to the Active Research table in MASTER.md:
| [{question_name}](Research/Active/{question_name}/) | {engines} | Just started | {first step} |
If this is a sub-question, don't add to MASTER.md — update the parent's README.md sub-question table instead.
If creating a sub-question, update the parent's README.md:
Output:
Research/Knowledge/ and MASTER.md)Research/Active/. Never create directly in Complete/ or Backlog/.