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?"

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

/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

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

Freeform Mode Gates

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

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

Common Mistakes

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.