What are logbooks?

A logbook is a small structured table a skill writes to during a run and reads from at the start of the next. One table, or a few connected ones — same columns every time, so anything that wrote to it can read from it.

The shape

The simplest logbook is a single table:

id, title, status, owner, next_step, updated_at

Anything more involved adds a few connected tables for annotations, comments, or action history:

research-logbook/
├── findings.csv      # main entries
├── comments.csv      # optional annotations
└── actions.csv       # optional action history

Two things are load-bearing. First, columns don't drift — the same row shape is used by every writer, every run, and every reader. Second, rows can be patched in place, not just appended. A row's status moves from open to fixed; it doesn't become a second row with a "fixed" annotation tacked on.

What it isn't

The fastest way to describe a logbook is by what it isn't. It sits adjacent to several familiar things, but it's not any of them.

Three properties make it work

A logbook earns its keep when three properties hold. Drop any one and it stops being useful.

01 Stable entry contract

Every row has the same columns regardless of which producer wrote it. A finding from the security lens is structurally identical to one from the performance lens. That's what makes rows mergeable, queryable, and patchable across runs.

02 Tool-queried, not reread

Readers hit the logbook with structured queries — status=open AND severity=high, last_seen<7d — instead of rereading transcripts. The reader doesn't need to know what previous runs did. The query answers.

03 Outlives the session

Rows persist beyond the run that wrote them. A test added today can close a gap reported last week, because the gap is a row — not a sentence in a transcript no one will reread.

The loop

Three things happen every time, in order.

1. Write

A skill produces a row and appends or patches it.

f4, security, medium, "API key in repo history", open

2. Query

A reader — the same skill, another skill, or a human — asks the logbook a structured question.

findings WHERE status=open AND severity IN (high, medium)

3. Act

The result drives a downstream action: a reviewer reads the filtered list, tickets get created, or the next run picks up where this one left off.

That loop is how partial work compounds, instead of dissolving with the session.

Where to go next