lab-notebook

What this skill does

# Lab Notebook

Establish mandatory, structured experiment logging for a project. Once initialized, every system modification, benchmark, configuration change, build attempt, and debugging step MUST be logged in `LAB_NOTEBOOK.md` — no exceptions.

The notebook combines three proven documentation patterns:
- **Scientific lab notebook** — hypothesis-driven entries with environment context and reproducibility
- **Architecture Decision Records** — decisions with alternatives considered and lifecycle tracking
- **Incident postmortem** — blameless failure analysis, action items, and "what went well"

## Proactive Triggers

Suggest this skill when:
1. The project involves **infrastructure or system administration** (servers, containers, GPU configs, networking)
2. Work is **experimental** — trying configurations, measuring performance, debugging issues
3. The project has **expensive failures** — changes that are hard to reverse, take time to diagnose, or affect shared systems
4. **Multiple sessions** will work on the same system (context loss between sessions is likely)
5. The user mentions "optimize", "benchmark", "debug", "configure", "deploy", or "experiment"

**Do NOT fire when:**
- The task is straightforward code implementation with git tracking
- The user explicitly declines structured logging
- A LAB_NOTEBOOK.md already exists and CLAUDE.md already has the lab notebook section

## Input

**Arguments:** `$ARGUMENTS`

Supported arguments:
- `init` — Full initialization: discover prior work, create LAB_NOTEBOOK.md, inject CLAUDE.md rules
- `entry "title"` — Add a new numbered entry to an existing notebook
- `status` — Show notebook health: entries, staleness, open action items, active decisions
- No arguments — Same as `init` if no notebook exists, same as `status` if one does

## Instructions

### On `init` (or no notebook exists):

Execute ALL steps below. Do not skip any.

#### Step 1: Discover Prior Work and Project Context

This is the most important step. Before creating the notebook, perform a THOROUGH survey of all existing work, history, and context. The goal: the notebook's opening section should be a coherent synthesis that lets anyone — including a future Claude session with zero context — understand exactly where things stand.

**1a. Read project documentation:**
- `CLAUDE.md` — operational rules, system configuration, known issues
- `README.md`, `docs/` — project purpose, architecture
- Any `*PLAN*.md`, `*TODO*.md`, `*STATUS*.md`, `*PROGRESS*.md` files — ongoing work, priorities, session handoffs
- `LEARNINGS.md` or similar — distilled insights from prior work
- Memory files (if accessible) — `MEMORY.md` and referenced memory files

**1b. Reconstruct history from artifacts:**
- `git log --oneline -30` — recent commits, what changed, who worked on what
- `git log --all --oneline --graph -20` — branch structure, parallel work streams
- `git diff HEAD~10 --stat` — scope of recent changes
- Check for config management artifacts (snapshots, backups, deployment scripts)
- Docker images and containers (`docker images`, `docker ps -a`) — what's been built, what's running
- Build logs, test results, benchmark outputs — any prior experiment data

**1c. Assess current system state (for infrastructure projects):**
- Running services, versions, health status
- Resource utilization (CPU, memory, GPU, disk)
- Configuration values that affect behavior
- Known issues, warnings in logs, error states

**1d. Check for undocumented work:**
- Stale branches with uncommitted experiments
- Docker images with meaningful tags (e.g., `v2-test`, `pre-migration`)
- Log files, temp files, benchmark results in `/tmp` or project dirs
- Config snapshots or backup files

**1e. Mine existing docs for decisions and action items:**

While reading project documentation, actively extract two things:

*Decisions* — look for them in:
- `CLAUDE.md` operational rules (each rule that reflects a choice, not just a universal constraint)
- `LEARNINGS.md` findings (each "we chose X over Y" is a decision)
- Config files with parameter choices (thresholds, backend selection)
- `*PLAN*.md` files with chosen approaches
- Git commit messages that explain "why" not just "what"

Not every operational rule is a decision. Focus on choices that have alternatives — where someone might reasonably ask "why not X instead?" Universal constraints (e.g., "never send data to cloud services") are project rules, not decisions. Decisions imply a choice was made: "We chose threshold 0.98 over 0.975 because..."

Each decision that affects future work goes in the Decision Log.

*Open action items* — look for them in:
- `PROGRESS*.md` and handoff files ("What Needs To Happen Next" sections)
- TODO comments in code (`grep -r "TODO\|FIXME\|HACK" --include="*.py"`)
- Stale branches (represent unfinished work streams)
- GitHub issues (if accessible)
- Any "future work" or "next steps" sections in documentation

Each open item goes in the Action Items table. Also capture 2-5 recently completed major milestones for the Completed table — this establishes the project's velocity and recent trajectory. Don't exhaustively list everything ever done, just significant recent completions that provide context.

**If existing `LAB_NOTEBOOK.md` is found:** Read it, verify CLAUDE.md has the mandatory logging section (Step 3), and skip to Step 4. Do NOT recreate or overwrite an existing notebook.

#### Step 2: Create LAB_NOTEBOOK.md

Create `LAB_NOTEBOOK.md` in the project root. The notebook has two kinds of content:

1. **Living sections** (top) — updated continuously as work progresses. These are the "dashboard" view.
2. **Chronological entries** (bottom) — append-only experiment log. These are the detailed record.

**Full structure:**

```markdown
# {Project Name} — Lab Notebook

**Project:** {Brief description — what this project IS and what it DOES}
**Started:** {Today's date}
**Systems:** {Key systems involved — servers, containers, services, etc.}

---

## Decision Log

Decisions are tracked here with their lifecycle. When a decision is revisited, update its status to SUPERSEDED and link to the new entry. Never delete old decisions. For decisions originating in another project's notebook, note the source.

| # | Decision | Date | Status | Entry | Alternatives Considered |
|---|----------|------|--------|-------|------------------------|
| D1 | {example: Use Marlin FP8 over CUTLASS} | {date} | ACTIVE | E001 | {CUTLASS FP8: works but 7.6% slower} |

Status values: ACTIVE · SUPERSEDED (by D#) · REVERSED (in E#)

## Action Items

Track follow-ups that emerge from experiments. Move to Completed when done.

### Open
| # | Action | Created | Source Entry | Priority |
|---|--------|---------|-------------|----------|
| A1 | {example: Re-test prefix caching on vLLM upgrade} | {date} | E005 | When upgrading |

### Completed
| # | Action | Created | Completed | Source Entry |
|---|--------|---------|-----------|-------------|

---

## Prior Work Summary

{A coherent, well-written synthesis of all work that happened BEFORE this notebook was created.

Target length: 500-1500 words for established projects with significant history, shorter for new projects. Focus on decisions, failures, current state, and open work. Don't reproduce the content of existing documentation — reference it. ("See LEARNINGS.md for detailed findings from each quality iteration.") The summary complements existing docs, it doesn't replace them.

This section answers:
- What has been accomplished so far?
- What approaches were tried? Which succeeded, which failed, and why?
- What is the current state of the system?
- What decisions were made, and what was the reasoning?
- What remains to be done?

Write as a narrative with structure — use tables for comparisons, timelines for history, and decision records for key choices.

Source from: git history, config snapshots, build logs, existing documentation, Docker artifacts, and any other evidence discovered in Step