Research Notebook Reference

reference / skill invocation

Invoke a skill with a task and its scope

The public package supplies research-lab-notebook for notebook operations and download-research-references for cited-paper archiving. After installing a skill, name it in a message to your coding agent. Send the example prompts in the agent conversation. Replace PLAN_PATH and the manuscript paths with your own files.

Notebook operations

Use research-lab-notebook to create or adapt a notebook, register experiments, process results, maintain plans, and track claims. Specify whether the agent should propose changes, write them to the notebook, or execute approved work.

Use research-lab-notebook to register an experiment for the retrieval question in lab-notebook/QUESTIONS.md. Describe the design, predictions, and decision rule for review. Do not run it.

Reference archiving

Give download-research-references a manuscript, its bibliography, and a destination. The archive reference describes retained files and access limits.

Use download-research-references to archive the papers cited by lab-notebook/papers/paper.typ, using lab-notebook/papers/references.bib. Put the archive in lab-notebook/references/ and report any sources you cannot retrieve.

Plan execution modes

Name an execution mode with the skill and plan path. An explicit user choice takes precedence over the plan or delegation prompt, which takes precedence over the default. The agent states its selected mode before starting. Put the mode name in the prompt.

All modes retain scope, budget, scientific, and human-approval gates. A mode does not grant authority to spend, publish, change a design, or execute an unapproved phase. In stepped mode, the agent processes and records results before pausing. The pause is per experiment; request per-job pauses explicitly when needed.

Use research-lab-notebook to execute PLAN_PATH in stepped mode within its approved scope and budget. Explain each original design before its findings, then wait for my reply.

Read-only plan activities

Plan preview explains proposed work. Results walkthrough explains existing experiments and results; walkthrough is the short form and replay is a synonym for the same activity. These are review activities, not execution modes.

• Neither activity launches, retries, or reruns jobs, repairs scripts, recomputes measurements, changes plan state, or takes execution ownership.
• A results walkthrough inventories the available experiments, states their count, and follows dependency order. For each experiment it presents the design recorded at the time, setup, controls, predictions, and null criteria before observed results.
• It distinguishes the intended design, actual execution, and retrospective explanation. It discusses defects, when they became detectable, and proposed repairs, then waits for the user before the next experiment.
• Missing records or artifacts are disclosed, never silently regenerated. Repair proposals and requests to continue the discussion do not authorize execution or file changes. Writing review corrections to the notebook requires a separate instruction.

Use research-lab-notebook to preview PLAN_PATH. Explain the proposed experiments, dependencies, controls, decision rules, costs, and uncertainties. Do not execute or edit it.

Use research-lab-notebook for a results walkthrough of PLAN_PATH. Use existing records and outputs only. Explain each original design before its findings and stop after each experiment. Do not run jobs, recompute results, or change files.

To execute first and review afterward, request both activities explicitly:

Use research-lab-notebook to execute PLAN_PATH in narrated mode within its approved scope and budget. When execution stops, give me an interactive results walkthrough using only the saved records and outputs. Do not rerun anything during the walkthrough.

Requesting a walkthrough or replay alone never starts execution, even when the plan is incomplete. The plan execution guide gives prompts for interactive execution and continuous execution followed by a walkthrough.

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
│   │   └── spend/              # optional: AUTHORITY.json and LEDGER.md
│   ├── 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
│   ├── REVIEW-LEDGER.md        # optional review register and gates
│   ├── CLAIMS.md
│   └── 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 7 defines the baseline paths: STATUS.md, QUESTIONS.md, PRIORITIES.md, CHANGELOG.md, CLAIMS.md, experiments/README.md, findings/README.md.

Directories

reference / formats · source

File formats

A path determines the record type. Headings and field names carry machine-readable state; prose carries evidence and interpretation. Preserve the required structure when adding domain-specific sections, and link to information another record owns.

reference / papers · source

Manuscripts and submission packets

A manuscript is the paper's complete source and can keep developing after publication. A submission packet adapts that source for one venue.

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: "[email protected]"),
  ),
  abstract: [Write the abstract here.],
)

= Introduction

#bibliography("references.bib")

reference / record kinds

Experiments and plans

Use the experiment reference for record structure, statuses, estimand registration, annexes, duplicate IDs, and result processing. The plan reference covers frontmatter, statuses, review gates, confirmation reserves, completion reports, and retraction notices.

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.

To decide what a result supports before changing a claim, follow the claim promotion workflow. It connects these fields to gates, data reuse, selection history, and independent confirmation.

Example claim rows

The first row comes from the repository's synthetic example and cites estimands. The belief-paper rows cite whole records, which do not declare estimands. Their major claim rests on two experiments; the supporting claim names the tested size range. That notebook uses 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.

Submission deadlines must come from the venue and link to its published source. For urgent but blocked work, record an Urgency reason, an observable Gate, and a ready since date that shows how long the work has waited. Do not substitute an internal target date for a venue deadline.

reference / graph · source

Edges and their owners

Records form a graph of typed links. Each link has one owner: the file where its author first records the relationship. Search or an index supplies the reverse lookup. Experiments carry no back-link to plans or claims.

An Informed by link records history that code and results cannot establish. The same threshold can be chosen before or after seeing the data. Record that exposure when choosing the design.

## 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.

Independent reviews of plans, designs, scripts, and results are a separate practice. A person or the project's instructions request them, and the optional REVIEW-LEDGER.md records each one and the gates founded on its findings.

reference / runners · source

Connect a job system

A version-controlled RUNNER.md records the project's commands for submission, status, logs, artifact retrieval, cancellation, and processing state. This mapping is a runner adapter. A project can combine the tools below.

Dagu and Pueue need an artifact convention or wrapper unless jobs already write to storage that survives the job. SkyPilot and Slurm also need project-specific artifact locations. Setup records these locations and commands in the runner adapter.

Document supported usage and billing queries in RUNNER.md, including their units, billing scope, update lag, and missing-data behavior. Use the runner or provider's documented CLI or API, not private state files. Usage evidence goes in per-attempt resource records in units; money goes in the spend ledger, which the spend account compares with the approved ceiling. Also describe which duration, concurrency, and spending controls the runner actually enforces. Billing can settle after a job is marked processed; record pending charges in the spend ledger.

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

Give the download-research-references skill a LaTeX or Typst manuscript and its bibliography. It identifies the cited works and assembles a local reading archive with source links. Use the archive to check related work, revisit a method, or share references with a collaborator.

Preview the cited works and available copies, then approve the selection to download. The archive retains authorized PDFs. Each unavailable paper keeps a source link and an explanation of the retrieval failure. Follow the paper guide to build an archive for your manuscript.

Track annotations, source indexes, and URLs in version control. Downloaded PDFs can be ignored individually; do not ignore the whole directory.