Research Notebook Reference

reference / invariants · source

Ownership rules

reference / structure · source

Directory structure

project/
├── lab-notebook/
│   ├── STATUS.md
│   ├── QUESTIONS.md
│   ├── PRIORITIES.md
│   ├── CHANGELOG.md
│   ├── experiments/
│   │   ├── README.md
│   │   ├── EXP-001-short-topic.md
│   │   └── EXP-001-short-topic.annex.md
│   ├── findings/
│   │   ├── README.md
│   │   └── 2026-08-10-cross-experiment-result.md
│   ├── plans/                  # optional
│   ├── reports/                # optional
│   ├── papers/                 # optional authored manuscripts
│   ├── references/             # optional cited-paper archive
│   ├── kb/                     # optional stable reference notes
│   ├── causal-models/          # optional mechanism hypotheses
│   ├── jobs/processed/         # optional runner fallback
│   ├── GLOSSARY.md             # optional
│   ├── BIBLIOGRAPHY.md         # optional
│   ├── RUNNER.md               # optional
│   ├── CLAIMS.md               # optional
│   └── PUBLICATION.md          # optional
├── scripts/                    # executable research code
└── data/                       # large or structured outputs

Markdown records remain small enough to review and version. Scripts and large artifacts stay in project storage; experiment records preserve the command, revision, parameters, artifact location, and content hash needed to recover a result.

Top-level files

Schema 5 defines the baseline paths: STATUS.md, QUESTIONS.md, PRIORITIES.md, CHANGELOG.md, experiments/README.md, findings/README.md.

Directories

reference / formats · source

File-format contracts

A path determines the record type. Headings and field names carry machine-readable state; prose carries evidence and interpretation. Keep the fixed shape below while allowing projects to add domain-specific sections that do not duplicate another record's ownership.

reference / papers · source

Manuscripts and submission packets

A paper's manuscript is its complete, continuing source. A submission packet is a derivative prepared for one venue. The two artifacts have different lifetimes.

The content invariant is packet ⊆ manuscript. A packet may omit material to meet a venue limit, but it cannot introduce content absent from the manuscript. A frozen packet can therefore remain behind a manuscript that continues to develop.

Edit the manuscript first and port changes into packets in preparation. A reviewer-driven revision or camera-ready phase may make the packet lead temporarily; back-port those changes before manuscript editing resumes. PUBLICATION.md records each packet's venue, state, and synced-as-of date.

Default manuscript source

New notebook manuscripts use Typst with Arkheion 0.1.2. This neutral, natural-length layout is independent of any venue template. All manuscripts in papers/ cite one shared papers/references.bib.

#import "@preview/arkheion:0.1.2": arkheion

#show: arkheion.with(
  title: "Working title",
  authors: (
    (name: "Author Name", affiliation: "Institution", email: "author@example.org"),
  ),
  abstract: [Write the abstract here.],
)

= Introduction

#bibliography("references.bib")

reference / record kinds

Experiments and plans

The two record kinds that grow have their own pages. The experiments page holds the record contract, the status vocabulary and its legacy spellings, estimand registration, annexes and duplicate IDs, and the register-and-process workflow. The plans page holds the frontmatter and status vocabulary, the review-gate diagram, confirmation reserves, completion reports, and retraction notices. Both pages render their vocabularies from the same schema copy this page uses.

reference / claims · source

Claim ledger evidence

CLAIMS.md uses the columns ID, Role, Claim, Status, Evidence, Paper. Roles are major, candidate major, supporting. Statuses are supported, provisional, blocked, refuted, retired, with live (for supported) and withdrawn (for retired) accepted as legacy spellings. Every row cites at least one experiment record. A finding may supply synthesis, correction, or interpretation context, but cannot replace experiment evidence. Papers consume evidence and do not belong in the Evidence cell. When the experiment declares estimands, cite the estimand as EXP-NNN:E#: the validator resolves it and warns when the claim draws on a found estimand or on a gate.

Example claim rows

The first row is from the repository's synthetic example and cites estimands. The other two are from the belief paper's notebook and cite records, since they predate estimand registration there; the major claim rests on two experiments and the supporting claim names the size range it was tested at. That notebook writes live for supported.

If no experiment owns a required analysis, create an analysis experiment that records its inputs, method, artifacts, and result. Mark expectations reconstructed after the result as retrospective.

Write the tested scope in the claim itself. The Paper cell is the stable key for the paper that uses the claim. PUBLICATION.md owns that paper's manuscript and packet pointers, synchronization state, readiness, gates, venues, deadlines, and submission state. Human review is required before promoting a claim to supported or broadening its scope.

Every date in a publication record is a venue's own published deadline, traceable to its source. Work that is urgent but blocked carries an Urgency reason, a Gate that a reader can observe, and a ready since date from which staleness can be read, never an internal target date.

reference / graph · source

Edges and their owners

The notebook is a typed graph. Each edge has one write-moment owner, the file whose author writes it when the fact comes into existence, and the reverse direction is computed by search or index rather than stored. Experiments carry no back-link to plans or claims.

The Informed by edge is the one that cannot be derived. A threshold chosen before looking and one chosen after produce identical code and output; the difference exists only at the write moment.

## Informed by

- [[EXP-028-visibility-derivation]], including its aggregate results, which were known before this record was created; that prior exposure is why this is a registered reanalysis and not a preregistration
- The four original Weft commands recovered for wj3711, wj3712, wj3726, and wj3733

## Pre-registered predictions (a priori)

None. This record registers an analysis of data already seen (see Registration status). The reproduction targets under Retrospective expectations are checks, not predictions.

reference / human decisions · source

Human review checkpoints

Agents prepare the record and proposed decision. They do not approve their own work as a substitute for human review. Record each decision in the experiment, plan, or claim update that it governs.

reference / runners · source

Connect a job system

A tracked RUNNER.md records how the project submits work, reads status and logs, retrieves artifacts, cancels work, checks whether evidence has been processed, and marks processing complete. This project-specific mapping is a runner adapter. The tools below occupy different layers and can be composed.

Dagu and Pueue need an artifact convention or wrapper unless jobs already write to durable storage. SkyPilot and Slurm also need project-specific artifact locations. Setup records these mappings in the project adapter and keeps the core notebook rules portable.

reference / processed state · source

Fallback processed-job ledger

Use one JSON record per backend and job ID to avoid append races:

lab-notebook/jobs/processed/
├── slurm/123456.json
└── skypilot/managed-job-17.json

Required fields are schema_version, backend, job_id, experiment_id, terminal_status, processed_at, evidence, notebook_revision. Terminal status is succeeded, failed, or canceled. Backend names are normalized and unsafe job IDs use URL percent encoding in filenames. Evidence paths stay inside the notebook. Artifact URIs and hashes are recommended.

1. Check whether the final record exists.
2. Retrieve and verify outputs.
3. Update evidence, indexes, and changelog.
4. Validate and make the notebook update durable.
5. Write a temporary JSON record in the target directory.
6. Atomically rename it to the backend and job path, then commit it.

Coordinate writers around the whole protocol. A retry is a new job and receives a new record. Prefer SQLite when many writers, transactional queries, or very large job counts make individual files unsuitable.

reference / literature archive · source

Cited-paper archive

The download-research-references skill follows local LaTeX and Typst includes, reads common LaTeX citation commands and Typst @key citations, resolves authorized open sources, validates bounded PDF downloads, and updates BIBLIOGRAPHY.md. It can also fetch bounded clean arXiv source into references/source/<citation-key>/ and write references/SOURCES.md.

• Preview with a dry run before downloading.
• Preserve existing thematic organization and hand-written annotations.
• Record source URLs even when no authorized PDF is available.
• Ignore downloaded PDFs, not the whole references/ directory.
• Never execute content from downloaded papers or archives.
• Use --report-json for automation and --strict when missing items should fail.