| 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:
- Question or goal.
- Action taken.
- Evidence:
- commands, scripts, configs, paths, job IDs, artifacts, metrics.
- Result:
- Conclusion:
- the inference you are drawing, if any.
- Inference confidence:
low, medium, or high when the entry is making a real inference.
- 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.