A research notebook starts with six records and grows with the work. Evidence moves from a question through an experiment, a processed run, a finding, and a publication claim that cites the registered estimand it rests on. Human review gates separate preparation, execution, interpretation, and promotion. The two record kinds that grow, experiments and plans, have their own pages; this guide covers the rest of the work.
workflow / setup
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.
Research work may run through a local queue, Dagu, Pueue, SkyPilot, Slurm, or Weft. Setup inspects the project and records how agents submit work, read status and logs, retrieve outputs, cancel work, and mark its evidence processed. It adds a processed-job ledger when the system lacks suitable processed state. The prompt needs no 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 orientationQUESTIONS.mdknown, open, blockedPRIORITIES.mdcurrent focus and queueCHANGELOG.mdresults and decisionsexperiments/one record per experimentfindings/cross-experiment synthesisAdd other files only when they have a current job. The structure reference lists the available roles.
workflow / first reading
The baseline notebook has four files at its root and two indexed directories. Optional records appear only when the project needs them. Research scripts and large outputs remain beside the notebook in the project tree.
project/
├── lab-notebook/
│ ├── STATUS.md
│ ├── QUESTIONS.md
│ ├── PRIORITIES.md
│ ├── CHANGELOG.md
│ ├── experiments/
│ │ ├── README.md
│ │ └── EXP-001-short-topic.md
│ ├── findings/
│ │ ├── README.md
│ │ └── 2026-08-10-cross-experiment-result.md
│ ├── plans/ # optional multi-session work
│ ├── reports/ # optional living analyses
│ ├── papers/ # optional authored manuscripts
│ ├── references/ # optional cited-paper archive
│ ├── kb/ # optional stable reference notes
│ ├── causal-models/ # optional mechanism hypotheses
│ ├── GLOSSARY.md # optional local vocabulary
│ ├── BIBLIOGRAPHY.md # optional related-work notes
│ ├── RUNNER.md # optional compute adapter
│ ├── CLAIMS.md # optional paper argument
│ └── PUBLICATION.md # optional submission state
├── scripts/
└── data/Open STATUS.md. Its snapshot names the current phase, established result, open work, next action, and navigation links.
Follow the linked item in QUESTIONS.md. An RQ# entry names the falsifiable question, status, short answer when known, and evidence links.
Open experiments/README.md, then the experiment linked from the question. The index locates the record; the experiment owns its design, runs, results, and conclusion.
If the experiment links a dated finding, read it through findings/README.md. A finding combines evidence from several experiments and does not replace their records.
If the project is preparing a paper, trace the estimand into CLAIMS.md and then PUBLICATION.md. These files own claim strength and submission state.
Finish at PRIORITIES.md and any linked active plan. They state what is ready, what it gates, and where the next result must be recorded.
| Path | Shape | Purpose |
|---|---|---|
STATUS.md | A short Snapshot field list and Navigation links | Orientation, not detailed evidence |
QUESTIONS.md | Repeated ## RQ# entries with question, status, answer, and evidence fields | Stable inquiry IDs |
experiments/EXP-*.md | Metadata followed by hypothesis, method, estimands, predictions, runs, results, conclusion, and artifacts | One experiment from design through interpretation |
findings/YYYY-MM-DD-*.md | Dated metadata followed by claim, evidence, synthesis, scope, consequences, and sources | Immutable cross-experiment synthesis |
PRIORITIES.md | One current focus, a short checkbox queue, and optional prediction table | Next actions and their gates |
plans/*.md | YAML frontmatter followed by goals, phases, gates, state, and terminal disposition | Bounded work across phases or sessions |
CLAIMS.md | A six-column claim table with direct experiment or estimand evidence | The paper-sized argument |
The file-format reference gives the complete contracts, including optional records. The experiment and plan pages give the full schemas for the two records that change throughout their lifecycle.
workflow / arrival
Project instructions, STATUS.md, and the relevant research question.
Follow links to the experiment, finding, plan, or claim that owns the evidence.
Confirm the notebook's version-control boundary and the project's command runner.
Edit the authoritative record. Update indexes with links instead of copying its conclusion.
A new agent can reconstruct the work without chat history. STATUS.md points to
the active evidence and next actions; the owning records carry the details.
STATUS.md. From QUESTIONS.md, RQ1.### RQ1. Are coexisting spaces separably represented?
**Question**: When a context establishes a base-world property `P` and a
counterfactual-world counterpart property `P′` for the *same* entity, are `P` and `P′`
**both** decodable, and separately, from activations over a single later mention of the
entity?
**Hypothesis**: For a capable model, both are decodable above chance at some
mid/late layer, and decodability is not pure recency …
**Experiments**: [[EXP-001-counterfactual-space-decodability]]
**Status**: supported — outcome (b) on Qwen2.5-3B (0.95/0.95), Qwen2.5-7B (0.92/0.91), and
pythia-2.8b (0.96/0.97), i.e. two architectures × three sizes; survives the recency control …The status line carries the answer and its scope in one place; the numbers stay in the experiment the link names.
workflow / human decisions
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.
Gated The follow-up node is used only when evidence opens another branch. It never authorizes itself.
Essential provenance for the not-post-hoc reading: the preservation cells were demoted to secondary non-discriminating controls BEFORE wj3849 ran — peer vetting mail (2026-07-02 ~01:39, with the explicit shared-router walk-through of why matched-frame preservation cannot discriminate) and script commit e069ef7b (docstring: "kept only as secondary non-disruption controls"), both prior to wj3849's dispatch. The failure is confined to that pre-designated secondary control; the pre-registered discriminators (cross ratios ≤0.3, angles) support dissociation.
The review decision is dated, attributed, and tied to a commit, so a reader can check that the demotion preceded the result rather than explaining it away.
workflow / evidence
Reserve a stable ID, write the design and its estimands, pause for design and preregistration review, run a bounded job tagged with the ID, and process the result through the decision rule before anything else depends on it. The experiment record's contract, the status vocabulary, estimand registration, the register-and-run workflow, and the six processing steps are on the experiments page, with excerpts from EXP-034 and EXP-021.
workflow / synthesis
| 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 gradient-accumulation example on the
experiments page,
a finding combines EXP-001 and EXP-002, and a claim remains
provisional outside the tested simulator and batch range.
Promotion is a human decision. Present the exact claim wording, the estimands cited, the
synthesis, threats, role, paper key, and proposed scope before changing a claim to
supported or broadening it. A claim that cites a found estimand is
a found result and says so; making it confirmatory needs a fresh registered run.
When an experiment corrects a value, it states the superseded value beside the new one, and the same session searches the notebook for both the old numbers and the experiment ID. Findings found that way get a correction pointer or a superseding record; terminal plans get a retraction notice beneath the passage that stated the value. Notebook edges point forward, so nothing asks who relied on the old value unless the search does.
CLAIMS.md, C001.| ID | Role | Claim | Status | Evidence | Paper |
|---|---|---|---|---|---|
C001 | major | In the tested Qwen, Pythia, Falcon3, Mistral, and OLMo settings, mental-space values use a frame-agnostic value slot, while a query-position router selects the relevant frame. Cross-builder causal transfer identifies a shared routing mechanism across the tested builder types. | live | EXP-006, EXP-010, EXP-034, EXP-034b | shared-router |
Five model families are named in the claim, so a reader who opens only this row knows what
was tested. This notebook writes live where the contract writes
supported; the validator accepts the spelling with a warning.
The reality arm's 0.031 was the artifact. With
loc_otheralways mentioned second and never moved, it was an unattractive answer to "the key is now in the", so reality-arm errors went to the stale location instead. Counterbalancing mention order raises that share tenfold and collapses the asymmetry from ~13× to ~1.4×.Retracted outright: the absolute rates as entity-binding rates, and their use as registered denominators in EXP-222.
Untouched: the plain accuracies. 0.854 for the moved object, 0.788 for the unmoved one, against a 0.333 three-way chance rate, with off-format at 0.002. These carry no cross-entity readout, so the slot confound cannot reach them.
The original headline stays in the file under a heading that says to read the correction first. The superseded values are stated beside the new ones, and the record that consumed them as denominators is named, which is what the sweep needs.
workflow / many sessions
A file under plans/ is a version-controlled contract for one bounded research
objective, reviewed before execution and after each phase's evidence returns. A plan that
will end in a confirmatory claim seals its reserve at creation; a plan that closes writes its
completion report; a plan whose stated outcome an experiment later corrects gains a
retraction notice. The frontmatter and status vocabulary, the review-gate diagram, and the
three closing sections are on the plans
page, with excerpts from two of the notebook's plans.
workflow / literature
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 reserves 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
These recipes name the evidence to read, the authoritative record to change, and the condition for stopping.
STATUS.md, QUESTIONS.md, PRIORITIES.md, active plans, and recent evidence.STATUS.md, and validator output.notebook_revision.workflow / close
Run the notebook validator after structural edits.
Update experiment and finding indexes, plus affected question and claim pointers.
Add a changelog entry for a result, decision, failure, or publication milestone, not routine editing.
Make the record durable in the notebook's own version-control boundary.
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.