lab-notes

Use when starting experiments, planning features with hypothesis-first approach, checking experiment status, logging observations, or wrapping up trials. Triggers: start an experiment, new trial, begi

SKILL.md

GitHub

Lab Notes

Structured experiment management with append-only running logs, optional hypotheses, and formal verdicts. Two modes: Rigorous (full scientific method) and Freeform (exploratory, structure grows organically). Works for any hypothesis-first exploration — technical experiments, feature planning, product ideas, infrastructure changes.

Workflow: FRAME -> SETUP -> RUN -> ANALYZE -> VERDICT

FRAME  ->  SETUP  ->  RUN  ->  ANALYZE  ->  VERDICT
  |                    |                       |
  |  (freeform: skip to)   |   (freeform: skip to)     |
  +--------------------+                       |
                                               v
                                    GRADUATE / ARCHIVE / ITERATE / PIVOT

Mode Selection

Ask at experiment start: "Is this a structured experiment or are you just trying something out?"

Answer Mode Behavior
"Structured" / "rigorous" / "I have a hypothesis" Rigorous All REQUIRED sections enforced via phase gates
"Just trying" / "exploring" / vague / casual Freeform Title + motivation required; everything else optional, asked but skippable

Set mode: rigorous or mode: freeform in LOG frontmatter. Mode can be upgraded (freeform -> rigorous) at any time.

In Freeform mode, still ASK for hypothesis, success criteria, and fail condition — but accept "skip", casual one-liners, or "I'll figure that out later." A casual hypothesis is fine: "I bet we can do X with Y and it'd be really cool."

Dispatcher: /lab-notes

Analyzes current state and suggests next action:

  1. Scan experiments/*/LOG-*.md for YAML frontmatter
  2. Check timebox deadlines against today (if set)
  3. Detect if user is in an experiment directory
  4. Report status table:
## Active Experiments

| Experiment | Phase | Mode | Started | Timebox | Status |
|------------|-------|------|---------|---------|--------|
| local-llm  | RUN   | freeform | 2026-03-11 | open-ended | 3 log entries |
| ev-charging | FRAME | rigorous | 2026-03-12 | 2026-04-01 | OVERDUE |
  1. Suggest next action based on context

Timebox Handling

  • Past deadline: Prominent warning, suggest ANALYZE or VERDICT
  • Within 1 day: Gentle reminder
  • Open-ended: No nag — valid choice for hobby experiments
  • No timebox field: Ask once if they want one, then leave it

The skill does NOT auto-close experiments. It informs. The human decides.

Spoke Commands

Command Transition What It Does
/lab-notes new <slug>: <title> -> FRAME Create experiment from template
/lab-notes setup [slug] FRAME -> SETUP Validate framing, update phase
/lab-notes run [slug] SETUP -> RUN Validate setup, update phase
/lab-notes log <observation> (stays in RUN) Append dated entry to Running Log
/lab-notes analyze [slug] RUN -> ANALYZE Validate observations exist, update phase
/lab-notes verdict [slug] ANALYZE -> VERDICT Validate findings, prompt for verdict + next action

/lab-notes new

  1. Ask mode question (rigorous or freeform?)
  2. Create experiments/YYYY-MM-DD-slug/LOG-slug.md from ${CLAUDE_SKILL_DIR}/templates/log.md
  3. Fill frontmatter: phase, mode, started, slug
  4. In Rigorous mode: prompt for hypothesis, success criteria, fail condition, motivation, time-box, pre-committed decisions
  5. In Freeform mode: prompt for motivation (required), then ask for hypothesis (accept skip), ask about time-box (accept "open-ended")
  6. Commit: D: Start lab-notes <slug> — <title>

/lab-notes log

The most-used command. Must be frictionless:

/lab-notes log Tested model X — 84% accuracy, 990ms avg. Better than baseline.

Appends to the active experiment's Running Log:

### 2026-04-05 14:30 — Tested model X
84% accuracy, 990ms avg. Better than baseline.

If multiple experiments are active, ask which one (or detect from current directory).

Phase Gates

Phase gates are requirements in Rigorous mode and suggestions in Freeform mode.

Rigorous Mode Gates

Gate Required Before Advancing
FRAME -> SETUP Hypothesis non-empty, >=1 success criterion, fail condition stated
SETUP -> RUN Environment section non-empty
RUN -> ANALYZE >=1 dated entry in Running Log
ANALYZE -> VERDICT Findings section non-empty

Blocked transitions produce a clear message: "Cannot advance to SETUP — hypothesis is empty. Write your hypothesis first."

Freeform Mode Gates

Gate Required Before Advancing
FRAME -> RUN Motivation non-empty (can skip SETUP entirely)
RUN -> VERDICT >=1 dated entry in Running Log (can skip ANALYZE)

Freeform mode allows jumping: FRAME -> RUN -> VERDICT. The skill suggests intermediate steps but does not block.

Reference

For lab notebook conventions (do's and don'ts, electronic record-keeping), consult ${CLAUDE_SKILL_DIR}/references/nci-lab-records-guide.md — the NCI's official guide (public domain).

Context Loss Prevention

  • Every skill invocation that touches the LOG MUST append, never overwrite
  • Running Log uses append-only semantics: new entries at bottom
  • When entering a new session with an active experiment: prompt "Read LOG-slug.md to re-establish context"
  • Failed Attempts section captures what did NOT work (often more valuable than successes)

Verdict and Graduation

Verdict Structure

Two independent axes (completeness is phase; confidence is judgment):

**Outcome:** CONFIRMED | REFUTED | INCONCLUSIVE | ABANDONED
**Confidence:** certain | high | moderate | low

An experiment can be INCONCLUSIVE with high confidence ("we definitely don't have enough data") or CONFIRMED with low confidence ("it worked once but...").

Next Actions

Action When How
GRADUATE Confirmed AND needs ongoing work git mv experiments/YYYY-MM-DD-slug/ projects/slug/ — add README.md, update TODO.md
ARCHIVE Any verdict, no ongoing work needed Write verdict, set phase to VERDICT. No file moves.
ITERATE New questions raised Write verdict with pointer to new experiment. Create new experiment.
PIVOT Reframe hypothesis Reset phase to FRAME, append new hypothesis to same LOG.

Commit conventions:

  • D: Archive lab-notes <slug> — <one-line verdict>
  • R: Graduate lab-notes <slug> to projects/<slug>
  • D: Iterate from lab-notes <slug> -> <new-slug>

Integration

System How
Sessionlogs Complementary: sessionlogs = session narrative; LOG = experiment observations. A session touches multiple experiments; an experiment spans multiple sessions.
TODO.md Active experiments don't need TODO entries — /lab-notes is the tracker. VERDICT outcomes requiring follow-up (graduation, iteration) create TODO items.
Delegate-agents Tell the delegate: "Append all observations to experiments/YYYY-MM-DD-slug/LOG-slug.md". The LOG protects against context loss across compact/restart cycles.
Dossier skill Complementary: dossier = one-shot research deliverable; lab-notes = multi-session exploration. A dossier may feed into an experiment; an experiment may produce a dossier.
commit-notation D: for experiment docs, R: for graduation moves, E: for experiment work (code, scripts, eval harnesses).
system-maintenance Overdue timeboxes flagged as health check items.
tracer-bullets (in plot-pm/plot) Different purpose: tracer-bullets proves architecture works (vertical slice); lab-notes documents what was learned exploring. An experiment might USE a tracer bullet as its method.

Common Mistakes

Mistake Fix
Rewriting LOG entries Always append. Cross out with strikethrough if correcting.
Skipping motivation in Freeform mode Motivation is required even in Freeform — it's the minimum "why"
Forcing deadlines on exploratory work Time-box is optional. Ask, don't require.
Starting Rigorous when Freeform fits Ask the mode question. Most hobby experiments are Freeform.
Forgetting to log during execution /lab-notes log should be called frequently during RUN phase
Drawing verdict without evidence Findings/observations must support the verdict — even in Freeform mode

Migration for Existing Experiments

Existing experiments (pre-skill) are NOT retroactively restructured. When revisiting an old experiment, the skill can offer to add frontmatter and a Verdict section. All new experiments via /lab-notes new follow the full convention.