Getting started

documentation/ guide and reference

Guide pages

Start here

When you need it

The Research Notebook System organizes a research notebook as linked Markdown files in your project. The files connect the questions you ask, the evidence you gather, and the decisions you make. You can read and edit them directly; coding-agent skills help create and maintain them.

You can adopt the notebook a piece at a time. Ask your coding agent for what you need in ordinary sentences; it creates and updates the files, and these pages describe what it writes. This page and the experiment guide cover a first project. Read the other guides when you reach that activity.

Install the skill, create a notebook, then start an experiment, plan, or paper. Each activity has its own workflow; the Reference specifies file formats and rules.

The topic list at the top stays within Guide or Reference. Where a matching page exists, a link labeled Reference: or Guide: connects the two sections.

Install the notebook skill

A skill is a package of instructions that teaches a coding agent the notebook's conventions. To install it, open your research project's folder in a terminal. You'll need Node.js (which provides npx), Git, and a coding agent that supports skills, such as Claude Code or Codex.

npx skills add osteele/research-notebook --skill research-lab-notebook

Follow the installer's prompts to select your agent. Keep the installation in this project to start. Confirm that research-lab-notebook appears in the installed skills:

npx skills list

Installation gives the agent instructions; it does not create a notebook.

Install for all projects or add reference archiving

For an installation shared across your projects, use the global option:

npx skills add osteele/research-notebook --skill research-lab-notebook -g

When you need to collect the papers cited by a manuscript, install the separate reference-archiving skill:

npx skills add osteele/research-notebook --skill download-research-references

Create a notebook

Start your coding agent in the same project folder. Ask it to use the installed skill, describing your research question and how you run experiments. For example:

Use the installed research-lab-notebook skill to create a notebook for this project. Our first question is whether a revised retrieval method improves answer accuracy. We run scripts locally. Create the notebook, but do not run experiments.

Replace the example question and execution setup with your own. The agent inspects the project, creates lab-notebook/, and adds project instructions for using it. Ask it to validate the notebook and report the result. Open the generated files to check that the question and project description reflect your research.

My project uses a job runner

Name your runner when requesting setup. The skill creates RUNNER.md to document how this project submits jobs, reads logs, retrieves outputs, and tracks which results have been incorporated into the notebook. Setup should not launch a real experiment. See runner configuration for the file's contract.

Read your first files

Start with these files inside lab-notebook/ to understand the project and choose the next task.

STATUS.md: where the project stands. Read its summary of established results, open work, and the next action.
QUESTIONS.md: what you want to learn. Find your first research question. As experiments answer it, links here lead to the evidence.
PRIORITIES.md: what to work on next. Check that the next task serves the question you intend to investigate.

Experiment files go in experiments/. Each describes a scientific test, its execution, and what its results mean. A record is an account of one research item: an experiment has its own Markdown file, while a question has an entry within QUESTIONS.md.

Scripts and raw outputs stay in the project's code and artifact locations; the notebook links to them. See the directory reference when you need the full file map.

Do research work

Start with an experiment for one scientific test. Add a plan when several pieces of work need a shared objective and review points. Use the paper workflow when developing a publication argument from the evidence.

Create an experiment, run it, and bank the results

Create the experiment. Link the question, describe the method, and write the predictions and decision rule before collecting results.
Review the design. Agree on the test and its interpretation rules, and check that the instrument can measure what you intend.
Request an independent review of the script before its first costly run, log the pass even when it finds nothing, and consult the project's gates.
Run the experiment. Execute the approved work, recording the producing code, inputs, execution attempts, output locations, and usage in units.
Bank the results. Check and interpret the outputs, review the conclusion, and incorporate the evidence into the notebook. Update the question and project status, preserve the artifacts, and record what follows. Failed and canceled runs need a documented outcome too.

The experiment guide covers the full lifecycle; the experiment reference specifies required fields.

Create, execute, and close a plan

Use a plan to organize a line of research, a paper revision, or a proposed scope expansion. It connects the work to an objective and defines when to continue, stop, or seek review.

Create the plan. State the objective, then divide the work into work packets with explicit limits.
Estimate the campaign in units and authorize its spend. Compare ways to answer the question, state the resource estimate in GPU-hours, calls, or elapsed time, and keep the approved ceiling and per-attempt money in plans/spend/.
Preview the proposed work and choose interactive execution or continuous execution.
Review and execute a phase. Obtain approval for the phase and its limits. Carry out the work through its experiments, bank their results, and review the evidence before moving to another phase.
Close the plan when its work reaches an outcome. Report what was achieved, what was not, and why. If work remains, update its state and next action for the next executor.

The plan guide covers purposes, review, and lifecycle; the plan reference specifies metadata and state rules.

To discuss work that has already run, request a results walkthrough. It explains the original designs before the findings, pauses after each experiment, and never reruns jobs. The invocation reference gives prompts for each activity.

Delegate bounded review and repair

The autonomous review and repair cycle connects independent review, repair, and re-review. Its diagram shows when Studio can continue unattended, when a pilot needs execution permission, and when a scientific decision comes back to you. The design-record repair workflow is described separately as designed but not implemented.

Develop, draft, and submit a paper

Develop the claims. Decide what the evidence supports and state the limits of the argument.
Draft the manuscript. Keep one continuing source, linked to the claims and experiments that support it.
Prepare a venue-specific submission. Adapt the manuscript and artifacts to that venue's requirements.
Review readiness and submit. Check the claims, rendered files, and artifacts. Record the actual submission separately from readiness.
Respond to review and revise. Bring corrections back to the manuscript and the notebook evidence they affect.

Work with evidence across experiments and papers

Synthesize evidence and scope claims. Compare results across experiments, distinguish exploration from confirmation, and decide what data can be reused.
Trace a claim to its evidence. Follow links between questions, experiments, findings, claims, and papers.
Build a reading archive. Collect the references cited by your manuscript, keeping downloaded sources separate from papers you author.
Correct a result and its downstream uses. Fix the source account, then update the claims and manuscripts that depend on it.

Resume work and hand off

Start a new session by reading STATUS.md, then follow its links to the active question, experiment, or plan. Check what has already run and which outputs have been incorporated into the notebook before launching more work. For a plan, read its current phase, approval, and next action.

Leave the next session a usable starting point

Before stopping, put results and explanations in the relevant experiment or plan file. Update the status and priority pointers, identify any outputs still awaiting processing, and leave a concrete next action. Validate the notebook and save the changes in its version-control repository.

Adopt an existing notebook

Install the skill, then ask your agent to inspect the existing notebook and propose the smallest changes needed to follow its conventions. Review the proposal before applying it. Preserve existing IDs, links, data locations, and version history. Once validated, continue with the resume-work reading path.