Labnb

Lab Notebook

Use this skill when the user wants a reusable lab notebook that survives across tasks, projects, investigations, and sessions.

The key difference from repo-local .lab/ workflows is that the lab root lives in a general location and must stay safe under parallel use.

Constitution

This skill must inherit and obey any higher-level constitution, parent skill, project policy, task instruction, or user constraint already in scope.

Before taking action:

1. Review the parent instructions that govern the current task.
2. Review the notebook index for related ideas and experiments.
3. If you are resuming an existing idea or experiment, review its local rules, checklist, and durable memory in idea.md, plan.md, and memory.md before acting.
4. If the parent rules are stricter than this skill, follow the stricter rule.
5. If this skill is missing a guardrail required by the parent context, add the missing guardrail locally in your plan instead of assuming it is safe.

This skill never overrides:

• user instructions
• project-specific safety or contribution rules
• higher-level constitutions about writes, approvals, secrets, or external side effects

Companion Skills

Use these focused companion skills when a narrower task is enough:

• [labnb-resume](../labnb-resume/SKILL.md): summarize prior ideas and experiments for a project and decide where to pick up
• [labnb-idea](../labnb-idea/SKILL.md): register an unimplemented experiment idea in the shared notebook
• [labnb-promote](../labnb-promote/SKILL.md): turn an existing idea into a concrete experiment with explicit budgets and provenance
• [labnb-run](../labnb-run/SKILL.md): create and run a concrete experiment with budgets, isolated workspace, and iteration logging

Each focused action installs as its own flat top-level labnb-* skill directory rather than as a skill nested inside this one. Keeping every skill flat (no SKILL.md nested under another skill) is what lets the whole skills/ tree install into agents such as Claude Code that do not support skills nested inside other skills, while Codex and other agents discover the same flat entries directly.

Helper Script Location

The commands below write paths like skills/labnb/scripts/.py. That is the path inside this repository, and it only resolves when you run from the repo root. When this skill is installed into an agent, the helpers live next to this SKILL.md, under /scripts/.py — for example ~/.claude/skills/labnb/scripts/ or ~/.agents/skills/labnb/scripts/. Resolve the script path relative to wherever this SKILL.md actually lives rather than assuming the repository layout, e.g.:

# Directory of the installed labnb skill (the folder containing this SKILL.md).
LABNB_SCRIPTS="/scripts"
python "$LABNB_SCRIPTS/register_experiment.py" --help

The labnb-* companion skills do not bundle these scripts; they call the ones from the installed labnb skill.

Default Root

Use this location unless the user explicitly wants another path:

${LAB_NOTEBOOK_ROOT:-${XDG_STATE_HOME:-$HOME/.local/state}/lab-notebook}

This keeps the notebook outside any single project tree and outside any specific agent runtime, while still making it easy to override.

Interactive Setup Gate

Before starting a new experiment, gather or infer these fields:

1. Goal
2. Mechanical metric
3. Direction: higher or lower is better
4. Verify command
5. Writable scope
6. Workspace placement: use the default notebook workspace path, or link the workspace to a different location for large worktrees, datasets, or rich outputs
7. Time budget or timebox, if the user gave one
8. Stop condition: target metric, iteration count, checkpoint, or manual stop

If any of the first four are missing and cannot be inferred safely, ask before starting. The notebook is global, but the experiment loop still needs a clear local objective.

If the user gives a time budget, treat it as a hard ceiling, not a target to consume.

The setup must answer three planning questions early:

1. What is the smallest useful iteration that can produce information or a decision?
2. What checkpoint would justify continuing into a second iteration?
3. If the budget is too small for even one useful iteration, say so clearly instead of pretending the work fits.

Treat the budget as applying to the whole proposed path, including any parallel branches, delegated work, or downstream follow-up experiments that you are suggesting now.

Required Guarantees

1. Never use a fixed experiment directory name.
2. Never let two runs compete to rewrite the central index without a lock.
3. Never store the only copy of experiment state inside the project being studied.
4. Never delete or rewrite prior experiment rows from the central index.
5. Prefer deterministic helpers in [scripts/register_experiment.py](./scripts/registerexperiment.py) and [scripts/summarize_index.py](./scripts/summarizeindex.py) instead of ad hoc shell snippets.
6. Track labnb-managed creates and updates with best-effort provenance using W3C PROV-O terms inside each entry directory.
7. Require explicit user confirmation before labnb performs deletions.
8. Treat provenance as the source of truth for monitored slice state; do not rely on a separate mutable loop-state file.
9. Let monitor_slice.py check decide when to break a slice, and honor a break: it can stop on governance (unauthorized, policy-violating, or drifted), budget, engineering (pace, stall, resource), correctness (repeated failures), or validity (no improvement, guardrail) signals, and a non-zero exit means stop rather than start another iteration.

Local Guardrails

Apply these guardrails even when the parent constitution does not spell them out explicitly:

1. Review the notebook index and the active task constitution before starting new work.
2. Never edit the original source tree directly when the experiment is supposed to use an isolated workspace.
3. If project files may change and the source is a git repository, create a dedicated git worktree in the experiment workspace first and do the edits there. If the source is not a git repository, copy it instead.
4. Never let two active experiments write to the same worktree, checkout, branch working tree, or results directory.
5. Treat parallel operations as potentially conflicting until the write scopes are proven disjoint.
6. If multiple experiments touch the same upstream source, keep their workspaces separate and link them only through notebook metadata, not shared writes.
7. Preserve append-only notebook history; record new state with new rows or child entries instead of rewriting prior conclusions.
8. Before resuming or branching, summarize related entries so you understand what has already been tried and what constraints still apply.
9. If the safe workspace strategy is unclear, pause and choose the safer option rather than writing into an ambiguous location.
10. Keep secrets, auth state, and external credentials outside experiment artifacts unless the parent constitution explicitly allows otherwise.
11. Treat provenance as best-effort only: external changes or deletions may still occur without labnb observing them.
12. Do not perform notebook-managed deletions without explicit confirmation from the user.
13. Unless absolutely necessary, do not run work blindly; instrument it well enough to inspect logs, checkpoints, progress, and resource consumption from outside the running process.

Action Gate

Before any action that writes, waits, launches background work, or hands off control:

1. Review the parent constitution, notebook summary, and the entry-local rules/checklist plus memory.md.
2. Confirm that you have actually completed those checks; do not rely on memory from an earlier step.
3. If the local rules or checklist are stale, incomplete, or newly contradicted by the current situation, update them before proceeding.
4. Check whether there is already a pending wait job for this entry before creating another one.
5. Confirm the run is instrumented enough that you can inspect logs, checkpoints, progress, and resource usage periodically without guessing.
6. If the action changes the local operating rules or durable memory, write the updated rules and memory back into the idea or experiment entry and note the change in log.md when applicable.

Lab Layout

lab-notebook/
  ideas/
    /
      metadata.json
      idea.md
      memory.md
      provenance.jsonl
      provenance.md
  experiments/
    /
      metadata.json
      plan.md
      memory.md
      log.md
      provenance.jsonl
      provenance.md
      results.tsv
      summary.md
      artifacts/
  workspaces/
    /
  index/
    experiments.tsv
    index.md
  locks/

• ideas//: not-yet-started or not-yet-promoted experiment ideas
• experiments//: one experiment per directory; no sharing across active runs
• provenance.jsonl: best-effort append-only provenance log using W3C PROV-O terms for labnb-managed actions
• provenance.md: human-readable provenance policy and caveats
• memory.md: durable local memory that should be re-read and updated as rules, waits, or resume points change
• experiments//plan.md: the setup gate plus current hypothesis
• experiments//results.tsv: local iteration ledger for this experiment
• workspaces//: per-experiment working area for an isolated git worktree or copied source tree
• index/experiments.tsv: append-only registry of ideas and experiments
• index/index.md: generated readable summary of known entries
• locks/: lock directories used for central updates

Experiment Identity

Each experiment id must be unique and stable:

------

Example:

20260411T154512Z--speech-foundations--prosody-ablation--a1b2c3d4

The random suffix is mandatory. A timestamp plus slug alone is not enough for parallel work.

Setup Flow

1. Resolve the global lab root.
2. Review the parent constitution, project rules, and any task-specific guardrails that apply to this run.
3. Derive a project_slug from the current project, investigation, source tree, or working directory name.
4. Pick an experiment_slug that describes the current investigation.
5. Before creating a new experiment, summarize the existing notebook entries for the project:

python skills/labnb/scripts/summarize_index.py \
  --lab-root "$LAB_ROOT" \
  --project-slug "$PROJECT_SLUG"

1. Use that summary to decide whether to:

• resume an existing experiment
• promote an existing idea into an experiment
• create a child experiment from a prior run
• or start a new experiment

1. Create the entry by running the helper:

python skills/labnb/scripts/register_experiment.py \
  --lab-root "$LAB_ROOT" \
  --project-root "$PWD" \
  --project-slug "$PROJECT_SLUG" \
  --experiment-slug "$EXPERIMENT_SLUG" \
  --objective "Short statement of the experiment goal" \
  --entry-kind experiment \
  --metric-name "$METRIC_NAME" \
  --direction "$DIRECTION" \
  --verify-command "$VERIFY_COMMAND" \
  --overall-budget "$OVERALL_BUDGET" \
  --loop-budget "$LOOP_BUDGET" \
  --source-id "$SOURCE_ENTRY_ID"

1. To record an idea that is not yet being run, use --entry-kind idea and omit experiment-only fields that are still unknown.
2. To promote an existing idea into a concrete experiment, use the dedicated helper:

python skills/labnb/scripts/promote_idea.py \
  --lab-root "$LAB_ROOT" \
  --idea-id "$IDEA_ID" \
  --project-root "$PROJECT_ROOT" \
  --experiment-slug "$EXPERIMENT_SLUG" \
  --metric-name "$METRIC_NAME" \
  --direction "$DIRECTION" \
  --verify-command "$VERIFY_COMMAND" \
  --overall-budget "$OVERALL_BUDGET" \
  --loop-budget "$LOOP_BUDGET"

1. Experiments must be created with explicit --overall-budget and --loop-budget; do not leave them unspecified.
2. Use one or more --source-id flags when an experiment stems from prior ideas or experiments.
3. Start the monitored loop slice before the first write-bearing iteration:

python skills/labnb/scripts/monitor_slice.py start \
  --experiment-dir "$EXPERIMENT_DIR"

1. Use monitor_slice.py check before another iteration or long-running verify step, and monitor_slice.py finish when the slice ends.
2. If the user wants the editable worktree or large outputs elsewhere, pass --workspace-root "$WORKSPACE_ROOT" and let the notebook create a stable link under workspaces//.
3. If code changes are involved and the source is a git repository, create a dedicated git worktree in the experiment's workspace before editing. If the source is not under git, copy it into the workspace instead.
4. If multiple agents are working on the same codebase, each agent must use its own separate worktree location. Never share a single git worktree or checkout across active agents.
5. Record baseline iteration 0 in results.tsv before code changes.
6. Work inside the returned experiment directory for notes, artifacts, and summaries.
7. Log progress inside that experiment directory, not in shared files.

Configurable Options

The skill has two kinds of configurable inputs: notebook root settings and per-experiment registration options.

Root Settings

• LAB_NOTEBOOK_ROOT: override the default global notebook location
• XDG_STATE_HOME: fallback base for the default notebook root when LAB_NOTEBOOK_ROOT is unset

Registration Options

Use these helper flags when creating an experiment:

• --lab-root: explicit notebook root
• --project-root: source tree or task directory being studied; optional for ideas that are still abstract or for work that will create a new repo later
• --project-slug: stable short name for the project
• --experiment-slug: short name for this idea or experiment entry
• --objective: concise goal statement
• --entry-kind: experiment or idea
• --status: optional explicit state; defaults to started for experiments and ideation for ideas
• --metric-name: optional metric label
• --direction: optional optimization direction such as higher or lower
• --verify-command: optional mechanical check command
• --overall-budget: required for experiments; total budget for the whole experiment path, including proposed follow-up or parallel work unless deferred
• --loop-budget: required for experiments; budget or timebox for the current loop or iteration slice
• --workspace-root: optional external root for the real workspace location
• --source-id: repeatable link to one or more upstream ideas or experiments that this run stems from
• --parent-id: optional parent experiment id for child experiments

If --metric-name, --direction, or --verify-command are omitted, the helper records TBD in plan.md. For experiments, --overall-budget and --loop-budget must be specified at creation time.

Recommended statuses include:

• ideation
• planned
• started
• stopped
• budget_exhausted
• completed
• terminated
• crashed
• deferred
• promoted
• archived

The summary helper also supports:

• --lab-root: explicit notebook root
• --project-slug: project to summarize
• --limit: maximum number of recent matching entries to show

The slice monitor helper supports:

• start: begin a monitored loop slice
• check: refresh elapsed state, evaluate break conditions, update status, and exit non-zero when it decides to break
• finish: close the active slice with a final status

Breaking A Slice Early

monitor_slice.py check is the loop's circuit breaker. It reads the provenance state plus results.tsv (and, optionally, a con/duct usage log) and returns a decision of continue, warn, or break. On break it moves the entry to a terminal status and exits with a non-zero code (default 4) so a shell loop stops on its own:

while python skills/labnb/scripts/monitor_slice.py check \
    --experiment-dir "$EXPERIMENT_DIR" \

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [sensein](https://github.com/sensein)
- **Source:** [sensein/agent_skills](https://github.com/sensein/agent_skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.