QUESTIONS.mdAskName what is known, open, or blocked.
Research Notebook System
File format · Workflow · Agent skill
Research Notebook is a system for managing research with coding agents. It connects publication claims to the experiments that support them. A shared Markdown record preserves the context needed to continue the work across sessions.
lab-notebook/ Explore the files in a research project's notebook.
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.
Claims stay connected to their evidence
A research claim depends on how the evidence was produced. A threshold chosen before a run and one chosen after seeing the result can produce identical code and output, but support different conclusions. Metrics alone cannot tell them apart.
Research Notebook records predictions and decision criteria before compute, then puts the outcomes beside them. Publication claims link back to the experiments that support them, with explicit scope and unresolved limitations. Researchers and agents use that chain to decide what the evidence warrants and what still needs testing.
Each record has one job
experiments/TestKeep method, predictions, runs, and results together.
findings/SynthesizeCombine evidence only when a conclusion spans experiments.
CLAIMS.mdArgueLink paper-sized claims to direct evidence and scope.
Other files appear when they earn a role. GLOSSARY.md stabilizes local terms,
BIBLIOGRAPHY.md annotates related work, and plans/ holds bounded
campaigns that must survive several sessions or move between agents. The separation matters
more than the filenames: one record owns each fact, and short indexes point to it.
Predictions and outcomes stay together
Record ranges, nulls, controls, and decision branches before inspecting outcomes.
Place observed values beside each prediction, then record scope and uncertainty.
Follow the recorded branch without reconstructing intent from a vanished chat.
Each quantity the experiment measures is named as an estimand and marked as registered in advance, found after the fact, or a gate on reading another. A claim cites the estimand, so a claim that rests on a found result is visibly a found result, and the record also says what the designer had already seen when the design was fixed. Those two facts exist only at the design moment; a threshold chosen before looking and one chosen after produce identical code and output.
Process completion and evidence processing are different states. A finished run is not processed until its outputs have been checked, the notebook update validates, and the durable write succeeds. That holds for a script run on a laptop as much as for a cluster job; the local run differs only in having no copy but the one on disk. Weft can provide the processed distinction directly. Setup adds a small processed-job ledger for SkyPilot, Slurm, Dagu, Pueue, and other backends that do not.
Documentation
The guide and the reference
The workflow guide covers setup, experiments, completed jobs, synthesis, durable campaign plans, literature archiving, and handoffs with a synthetic example. The paired reference catalogs every file and directory, runner and ledger rules, and the experiment and plan schemas.
Install it, then start small
npx skills add osteele/research-notebook -s research-lab-notebook -yUse $research-lab-notebook to add a research notebook to this project. Jobs run through Slurm.
Substitute your runner. The notebook works when every job is launched by hand; the public collection contains no autonomous research loop, unattended plan executor, code-audit hooks, private compute configuration, or job runner implementation.
The useful idea is smaller: research context belongs in durable, inspectable files. Once the context exists, both a human and an agent can pick up the work without asking a vanished session what happened.
Read the guide Use the reference Repository and installation