lab-notebook git:20260320.999ac68A

Immutable. This exact content is served forever at /api/v1/blob/1d087746b921e507.

---
name: lab-notebook
description: "Record work in a lab notebook so it is both a literal activity log and an efficient re-entry aid. Use when the agent is running experiments, debugging workflows, triaging jobs, or updating project state that must be recoverable later."
---

# Lab Notebook

## Optimize For Re-entry And Auditability

- A notebook should answer both:
  - what exactly happened?
  - what do we currently believe?
- Prefer one low-friction chronological record plus a sparse current-summary layer.
- Reuse the project's existing notebook pattern instead of inventing a new structure.

## Choose The Notebook Shape

- If the project already uses one file with summary plus chronology, keep that shape.
- If the project already uses a detailed campaign notebook plus a sparse top-level lab notebook, keep that split.
- Do not create two equally detailed notebooks.
- Default rule:
  - detailed layer: append literal work record
  - summary layer: update only when the decision or current understanding changes

## Use This Entry Contract

For each meaningful experiment, debugging step, or job intervention, capture:

1. Question or goal.
2. Action taken.
3. Evidence:
   - commands, scripts, configs, paths, job IDs, artifacts, metrics.
4. Result:
   - what actually happened.
5. Conclusion:
   - the inference you are drawing, if any.
6. Inference confidence:
   - `low`, `medium`, or `high` when the entry is making a real inference.
7. Decision impact:
   - what changed in current understanding, or what the next step is.

## Update The Summary Sparingly

- Update the summary layer only when one of these changes:
  - current best explanation
  - current best branch or baseline
  - settled negative results
  - next discriminative check
  - success criterion or decision rule
- Do not rewrite the summary after every routine action.
- The summary should be short enough that a fresh agent can re-enter from it.
- If multiple live explanations matter, keep a tiny hypothesis registry in the summary layer:
  - hypothesis
  - strongest support
  - strongest weakening evidence
  - next falsifier

## Make Entries Useful

- Include exact evidence paths and identifiers.
- Include representative visual artifact paths when a plot, overlay, slice, curve, or diff view materially affected the decision.
- Record negative results explicitly when they rule out a family of ideas.
- If the entry draws an inference, state it explicitly instead of leaving it implicit in the next step.
- Keep inference confidence coarse: `low`, `medium`, or `high`.
- Do not add confidence to entries that are only reporting raw observations or routine actions.
- Preserve chronology so later readers can reconstruct what happened.
- End each entry with "so what?" in concrete form.
- If nothing changed in understanding, say that explicitly.

## Avoid Notebook Drift

- Do not let the summary become stale relative to the chronology.
- Do not dump raw metrics or images without interpretation.
- Do not record an interpretation without enough evidence to re-check it later.
- Do not duplicate the full chronological detail into the summary.

## References

- Read `references/templates.md` for one-file and two-layer notebook templates.