Research Lab Notebook Guide

lab-notebook/ durable research record

Use this guide while doing research work. It starts with the smallest useful notebook, then follows evidence from a question through an experiment, a processed job, a finding, and a publication claim. Human review gates separate preparation, execution, interpretation, and promotion.

workflow / setup

Set up or adopt a notebook

Install the notebook skill into the current project with the cross-agent installer:

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

Goal	Command
Try without installing	`npx skills use osteele/agent-skills@research-lab-notebook`
Install globally for Claude Code and Codex	`npx skills add osteele/agent-skills -g -a claude-code -a codex -s research-lab-notebook -y`
Update this skill	`npx skills update research-lab-notebook`
Remove this skill	`npx skills remove research-lab-notebook`

From the research project, give the notebook skill one short instruction:

Use $research-lab-notebook to add a research notebook to this project. Jobs run through Slurm.

Substitute Weft, SkyPilot, Slurm, Dagu, Pueue, a local queue, or your own backend. Setup inspects the project, preserves useful conventions, writes the runner mapping, and adds a processed-job ledger when the backend does not provide suitable processed state. The prompt does not need a conditional ledger instruction.

Some agents use $research-lab-notebook for explicit invocation. In an agent without that syntax, say “Use the installed research-lab-notebook skill” instead.

STATUS.mdcurrent orientation

QUESTIONS.mdknown, open, blocked

PRIORITIES.mdcurrent focus and queue

CHANGELOG.mdresults and decisions

experiments/one record per experiment

findings/cross-experiment synthesis

Add other files only when they have a current job. The structure reference lists the available roles.

workflow / arrival

Orient before changing the record

Read
Project instructions, STATUS.md, and the relevant research question.
Trace
Follow links to the experiment, finding, plan, or claim that owns the evidence.
Locate
Confirm the notebook's version-control boundary and the project's command runner.
Choose
Edit the authoritative record. Update indexes with links instead of copying its conclusion.

This sequence is useful when an agent arrives with no chat history. STATUS.md should point to the active evidence and next actions, not retell the project.

workflow / human decisions

Pause where judgment changes the research

Agents can prepare designs, preregistrations, analyses, and proposed decisions. A human reviews the material before execution, before outcomes can influence the preregistration, before interpretation becomes synthesis, before a gated follow-up runs, and before a claim gains strength or scope. Record the decision in the owning experiment, plan, or claim update.

Experiment evidence path

PrepareExperiment designInstrument, controls, metrics
HumanDesign reviewRevise or approve
RecordPreregistrationPredictions and branches
HumanPreregistration reviewApprove before outcomes
ExecuteBounded runJobs, artifacts, provenance
EvaluateAnalysis and interpretationPrimary outcomes first
HumanInterpretation reviewScope, exclusions, uncertainty
Human · gatedFollow-up approvalStop, revise, or run again
SynthesizeFindingCross-experiment evidence
HumanClaim promotionWording, status, scope
PublishSupported claimDirect experiment evidence

Gated The follow-up node is used only when evidence opens another branch. It never authorizes itself.

workflow / evidence

Register and run one experiment

Reserve a stable ID such as EXP-012. Record the instrument, data, conditions, primary and secondary metrics, code revision, key command, preregistered predictions, and decision rule before inspecting outcomes. Pause for design review before preregistration and for preregistration review before execution. Attach backend job IDs and immutable artifact locations to the same experiment record. After analysis, obtain interpretation review before recording a synthesis or approving a follow-up.

Synthetic example

Does gradient accumulation reproduce true large-batch training?

QUESTIONS.md: RQ1 asks whether optimization behavior is preserved at fixed effective batch.
plans/completed/2026-08-12-accumulation-controls.md: The plan was reviewed before execution. Phase 2 starts only after human review of the pilot gate.
EXP-001-accumulation-pilot.md: P1 predicts final validation loss differs by less than 0.02. The pilot is slurm/48152.
EXP-002-accumulation-comparison.md: Three paired seeds test the same 0.02 margin after the pilot passes.
jobs/processed/slurm/: Records 48152.json and 48161.json point to the revisions that made each job's evidence durable.
findings/2026-08-16-accumulation-matches-large-batch.md: Synthesizes both experiments and preserves the toy simulator's scope limit.
CLAIMS.md: C1 cites both experiments directly and records human promotion review; the finding supplies synthesis context.

The complete fictional notebook and its deterministic toy command are in the repository example.

workflow / terminal job

Process a completed or failed job

Backend completion means compute stopped. Processing means its outputs were checked and incorporated into durable evidence. Keep those states separate.

Confirm
Read terminal status from the backend and check whether the job is already processed.
Retrieve
Collect logs, outputs, parameters, revision, environment, runtime, and cost when available.
Verify
Confirm expected outputs exist, belong to the intended run, and preserve immutable provenance.
Analyze
Evaluate primary outcomes first. Compare every preregistered prediction with the observed value.
Review
Ask a human to review exclusions, uncertainty, interpretation, and the proposed gate decision.
Record
Update the experiment, indexes, status, changelog, and claim pointers that the result changes.
Close
Validate and commit the notebook update, then write the processed mark last.

Treat an existing processed record as an idempotency signal. Verify its evidence links rather than creating a duplicate. Failed jobs can be processed after their failure mode and useful partial artifacts are recorded.

workflow / synthesis

Synthesize without duplicating evidence

If the statement depends on	Write it in
One experiment	That experiment's conclusion
Several experiments	A dated record under `findings/`
A paper-sized assertion	`CLAIMS.md`, linked to direct evidence
A changing long analysis	`reports/`
A mechanism hypothesis	`causal-models/`, separate from observed findings

State observed values, uncertainty, effect sizes, tested scope, and threats to validity. In the synthetic example, a finding can combine EXP-001 and EXP-002. A claim remains provisional outside the tested model and batch range.

Promotion is a human decision. Present the exact claim wording, direct experiment records, synthesis, threats, and proposed scope before changing a claim to supported or broadening it.

workflow / many sessions

Coordinate a durable campaign

Create a file under plans/ when one objective spans experiments, gated phases, agents, or sessions. It records the objective, existing evidence, dependencies, phases, acceptance and stop conditions, risks, expected notebook updates, terminal conditions, and one bounded next_action.

Durable plan with review gates

PrepareDraft planPhases, risks, terminal conditions

HumanPlan approvalRevise or activate

ExecuteOne bounded phaseRecord runs and evidence

UpdateProposed dispositionGate result and next action

HumanPost-phase gate reviewChoose the next state

ContinueApprove the next bounded phase.

GatedName the gate and reconsideration condition.

BacklogKeep the direction without active execution.

CloseComplete, supersede, or abandon with evidence.

Human follow-up approval moves a gated plan back to one bounded active phase.

Native agent plan	Notebook campaign plan
Coordinates the current task or conversation	Coordinates a research objective across experiments and phases
Lives in one product's task context	Lives in version control and survives context resets
Usually guides one agent's immediate work	Can be created, executed, and reviewed by separate agents or harnesses
Tracks implementation steps	Tracks evidence, gates, risks, stop conditions, and handoffs

Use Claude Code plan mode or Codex's task and multi-agent surfaces to reason about the immediate work. Pass a durable plan's path and phase name to another executor instead of copying the contract into a prompt. Creating or approving the plan does not authorize paid compute, destructive actions, publication, external writes, or an unattended execution loop.

Review the plan twice at minimum: before execution and after evidence returns. At a phase gate, the human chooses whether to continue, revise, wait, or close. A gated follow-up pauses again before any new job is submitted.

workflow / literature

Archive cited references

Ask the installed skill to inspect a manuscript before downloading:

Use $download-research-references to preview the cited papers for this draft, then archive the authorized open-access copies.

The skill puts third-party papers and source notes under references/ and maintains the annotated BIBLIOGRAPHY.md. It preserves papers/ for manuscripts authored by the project, records source URLs, validates PDFs, avoids duplicates, and does not bypass paywalls. Downloaded PDFs can remain ignored while tracked notes and source indexes stay in version control.

workflow / operations

Operate and repair the record

These recipes name the evidence to read, the authoritative record to change, and the condition for stopping.

Refresh status and priorities

Read: STATUS.md, QUESTIONS.md, PRIORITIES.md, active plans, and recent evidence.
Write: Short current-state and next-action pointers. Remove stale queue entries.
Done: Every active item points to an owner record and every blocked item names its blocker.

Process a sweep

Read: Runner terminal states, processed checks, run manifests, and the owning experiment.
Write: One outcome row per prediction, failures and anomalies, artifact pointers, indexes, then processed marks.
Done: Every terminal job links to durable evidence or remains explicitly unprocessed with a reason.

Correct or supersede a finding

Read: The dated finding, its source experiments, and the later evidence that changes it.
Write: A correction pointer for a factual error, or a new dated finding that supersedes the old one. Update claims and indexes.
Done: The historical record remains visible and current readers reach the newer conclusion.

Refute or retire a claim

Read: The claim, direct evidence, contradicting findings, promotion review, and publication text that uses it.
Write: The human-reviewed support status, scoped reason, counter-evidence links, and affected publication blockers.
Done: No active draft presents the claim more strongly than its evidence allows.

Resume, block, abandon, or close a plan

Read: The plan, current phase, terminal conditions, human gate decision, and evidence produced since its last update.
Write: Status, date, current phase, gate metadata, and one bounded next action. Terminal plans also need disposition and evidence; their next action is empty.
Done: A new executor can continue or understand why the campaign ended without chat history.

Reconcile notebook drift

Read: Version-control changes, record files, indexes, STATUS.md, and validator output.
Write: Missing authoritative evidence first, then thin pointers and lifecycle statuses.
Done: Links resolve, indexes are complete, ownership is unambiguous, and strict validation passes.

Move the notebook to its own repository

Read: Version-control boundaries, ignore rules, artifact paths, project instructions, and automation.
Write: The new tracked boundary, stable artifact references, and one project-instruction pointer to the notebook location.
Done: The notebook has one documented history and a fresh agent can locate and validate it from the code project.

Recover a missing ledger write

Read: The absent final record, backend job, preserved artifacts, and candidate evidence revision.
Write: If that revision already incorporates the exact job, add only the ledger record and cite it in notebook_revision.
Done: The processed check is idempotent and no experiment result or finding was duplicated.

workflow / close

Validate and hand work off

Validate
Run the notebook validator after structural edits.
Index
Update experiment and finding indexes, plus affected question and claim pointers.
Log
Add a changelog entry for a result, decision, failure, or publication milestone, not routine editing.
Commit
Make the record durable in the notebook's own version-control boundary.
Point
Leave STATUS.md and any active plan at a bounded next action.

For exact schemas and ownership rules, continue to the reference. The normative skill files remain in the agent-skills repository.