eins78/lab-notes

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 |

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