Research Notebook System
Keep the reasoning with the experiments
Research Notebook connects questions, experimental evidence, and the decisions that follow. It keeps this account in linked Markdown files alongside the project's code.
A researcher or agent joining the project can see what was expected, what was observed, what remains uncertain, and what to do next.
- Continuity across people and sessions
- Researchers and agents can resume from recorded predictions, results, and next actions.
- Claims traceable to evidence
- A claim identifies the experiment, measured quantity, and design choices that support its stated scope.
Notebook files
Select a file to see what it records and who uses it. Experiment files contain the analysis of one experiment; findings combine evidence from several experiments.
plans/
experiments/
findings/
papers/
reports/
references/
STATUS.md
The project's current state: what's established, what's blocked, and what to do next. Links point to the supporting records.
Indexes and dashboards draw from these files. Add an optional record when the project needs it.
System features
| Feature | Benefit |
|---|---|
| Portable, version-controlled files | Markdown files work offline, support Git/jj diffs, and are searchable with ordinary tools. Obsidian provides linked navigation. The notebook can have its own version-control repository. |
| Research questions organize the work | Each experiment links to its research questions and keeps its hypothesis, method, runs, results, and interpretation together. Findings combine evidence from several experiments. |
| One home for each kind of information | STATUS describes the project's current state; QUESTIONS tracks inquiry; PRIORITIES identifies next work; PUBLICATION tracks submission readiness. Each links to the supporting records, so a result can be updated in one place. |
| Handoffs between sessions and agents | One session can design and launch an experiment, another process its results, and a third continue the work. Recorded predictions, decision rules, and follow-ups let each recover the reasoning behind the next step. |
| Registration for each measured quantity | An estimand is the quantity an experiment seeks to estimate. The notebook records what was fixed in advance for each estimand, plus what earlier evidence informed the design. This distinguishes planned tests from discoveries within the same run and makes post-hoc reinterpretation easier to detect. |
| Traceable claims and provenance | A claim cites a specific experiment estimand, such as EXP-042:E2. Links connect plans, experiments, jobs, claims, and papers. A reader can trace a claim's support and identify what needs reconsideration when evidence changes. |
| A result-processing workflow | After a run finishes, validate the output and instrument, record the result, apply the decision rule, update dependencies, preserve the artifacts, and report. Process failed and null results too, so their evidence and follow-ups remain available. |
| Mechanical checks and review tracking | Validators check defined formats and references. Human review decisions stay with the experiments, plans, and claims they govern. Content-hash review tracking can identify changed artifacts that need another review. |
| A path from evidence to publication | CLAIMS.md links paper claims to their evidence; PUBLICATION.md records paper scope, venues, and blockers. Manuscripts and supporting notes stay linked to the experiments they draw on. |
Session handoffs
- Design and launch
Write the hypothesis, predictions, and decision branches before inspecting results. Record what earlier evidence informed the design.
- Process the result
Check the output and instrument, record the outcome, apply the decision rule, update dependencies, and preserve the artifacts.
- Apply the recorded decision
The next session follows the decision rule and follow-ups. Failed and null results can close a branch as well as open one.
Check, interpret, and record results before moving on to the next experiment. The same requirement applies to laptop runs and remote jobs.
Installation
The public agent skill supplies the notebook conventions and workflows.
1. Install in a terminal
Run this command from your research project's directory:
npx skills add osteele/research-notebook -s research-lab-notebook -y2. Ask your coding agent to set up the notebook
After installation, send this prompt to the agent working in your project:
Use $research-lab-notebook to add a research notebook to this project. Jobs run through Slurm.
Name your project's runner or explain how you run scripts locally. The skill supplies instructions for working with those tools; it does not install a scheduler or research loop.
Start with the records your project needs, and keep them current as the research changes.
For designing a follow-up or assessing a claim, use the evidence and data-reuse workflow. It covers experiment records, confirmation reserves, and the claims ledger.
Integration with other research tools
Experiment files connect hypotheses and interpretations to outputs from metric trackers, computational notebooks, version control, and job runners.
| Tool | What it manages | Connection to the notebook |
|---|---|---|
| Weights & Biases / MLflow | Metrics, run comparisons, and hyperparameters. | Experiment records link to runs and recorded metrics, then document the hypothesis, interpretation, and resulting claims. |
| Jupyter | Interactive exploration and computational analysis. | Experiment records reference computational notebooks and their outputs, preserving the design and conclusions alongside the analysis. |
| Git / jj | Code history and versioned changes. | Notebook files are versioned; experiment records identify the code revision that produced a result. |
| Slurm / SkyPilot / Weft | Job execution, status, logs, and output retrieval. | Run records retain job IDs and artifact locations. Result processing records whether the output was validated, interpreted, and acted on. |
These connections use file links and project-specific commands. API integration requires a separate connector.
Read and edit the files in Obsidian, a text editor, or a coding agent.