# lab-notebook-starter.md A portable starter for a research-log file that records method changes, anomalies, findings, and reversals over the life of a research, data, or content project. Pattern lifted from the [Periodic Table of Taylor Swift](https://ts.hosette.net), where the Notebook is the most-loved page on the site because it admits the catalogue used to be wrong and explains how it got fixed. The premise: most research and data projects pretend to a polished finality. A lab notebook makes the messy middle visible by recording, in chronological order, every methodology change and every anomaly. The rule is simple. When something changes, you write a new entry. You do not rewrite the old one. Reversals are noted in place ("reversed YYYY-MM-DD because X"), not deleted. The polished result is trustworthy because the messy middle is readable. This is a sister file to [decisions-starter.md](/decisions-starter.md). The decisions log records *what we will not build*; the lab notebook records *what we observed and how the method changed*. Different audiences (PMs vs. researchers/analysts), different discipline, same load-bearing principle: write it down once, in the project's own voice, so it can be re-read on every turn. --- ## How to use it 1. Drop a copy at the root of your project, alongside the data or the writing it documents. Name it whatever fits the project, `notebook.md`, `lab.md`, `research-log.md`, `findings.md`. 2. Add a new entry every time you change a method, find an anomaly you can't yet explain, or arrive at a finding you'd defend. Each entry is dated, numbered, and titled. 3. Never quietly edit a past entry. If a method changes, write a new entry that names the change. If a finding is overturned, append a `[reversed YYYY-MM-DD]` line to the original entry; do not rewrite it. 4. Optional: wire the agent prompt at the bottom into your tooling so an AI assistant treats the notebook as authoritative. The notebook is its own deliverable. Many projects discover the Notebook page becomes more interesting to readers than the result page. Plan for that. --- ## Entry format Each entry follows the same shape: > **N005 — 2026-04-15 — short title** > > One paragraph: what changed, why, what data prompted it. Cite a > specific instance if possible. Voice is the project's, not a > formal report. > > *[reversed 2026-05-02, see N011]* (only when applicable) The numbering (N001, N002...) makes entries citable from elsewhere in the project. The date is what you trust six months later. The title is what makes the entry findable when the file is long. --- ## Method changes How the methodology shifted over time. Each entry names the choice made and the alternative considered. > **N001 — YYYY-MM-DD — schema before viz** > > Started by sketching the visualization. Realized I was drawing > a chart of an unconsidered dataset. Pivoted: define the schema > (columns, vocabularies, types) before drawing anything. The > chart took an afternoon once the schema stabilized; the schema > took a week. Worth it. > **N003 — YYYY-MM-DD — splitting a single column into two** > > Was treating "controversy" as a single 0-10 number. Realized the > public score (press, charts) and the fandom score (forum > activity, explicit complaints) were sometimes inverse. Split > into two columns. Re-scored the affected entries. ## Anomalies Data points that don't fit, with the working hypothesis. Anomalies that resolve into findings get a forward link. > **N002 — YYYY-MM-DD — the outlier that broke the grid** > > [Item X] doesn't fit the [primary-axis × secondary-axis] grid. > Initially considered adding a third axis or a "specials" row. > Decided against (would set a precedent for every future outlier). > Promoted [Item X] to a trait flag instead. *(see N006)* ## Findings Observations the data supports, each linked back to the methodology that produced them. > **N006 — YYYY-MM-DD — bonding is sharper than ranking** > > Confirmed: questions framed as "which item bonds with which" > produce more revealing answers than "which item is best." > Reactivity is a sharper question than ranking. *(method: N001)* > **N009 — YYYY-MM-DD — N missing entries recovered** > > Cross-referencing N independent sources recovered M catalogue > entries not present in any single source. The dataset is the > product; this work is the reason the rest of the project is > trustworthy. *(method: dataset reconciliation, week of YYYY-MM-DD)* ## Reversed entries When a past entry is overturned, do not delete it. Append the reversal in place; cross-link to the entry that replaces it. > **N004 — YYYY-MM-DD — initial definition of [property]** > > Defined [property] as [simple measure A]. Plays well with the > primary metaphor. > > *[reversed YYYY-MM-DD, see N011. The simple measure made > [edge case] artificially heavy and [other edge case] artificially > light. Replaced with a weighted score: 0.5 * normalized A + 0.5 * > normalized B.]* --- ## Agent prompt to wire this up Add this to your project's `CLAUDE.md`, system prompt, or `.cursorrules` if AI tooling is part of your workflow: > Before reasoning about this dataset, read `lab-notebook.md` at > the project root. Treat every entry as authoritative; the > entries record what we currently believe and how we arrived > there. Specifically: do not propose method changes that > contradict an existing entry without first reading the entry > that established the current method. Do not retroactively > rewrite a past entry; if something needs to change, write a new > entry naming the change and link back. Reversals append > `[reversed YYYY-MM-DD, see Nxx]` in place; they do not overwrite > history. --- ## Why this shape A few notes from running it in production. **Show the working.** The Notebook is the most-loved page on the TS site. Visitors trust the polished result because the messy middle is right there to read. Lab notebooks beat marketing copy. **Never edit history.** The "reversed YYYY-MM-DD" convention is load-bearing. If past entries can be quietly rewritten, the file loses authority. The discipline is what makes the notebook a reference instead of a draft. **Voice over format.** Write in the project's own voice. A formal third-person research log gets read once. A first-person notebook with personality and small sentences gets re-read. **Citable entries.** The N00N numbering matters. It lets the result page cite "N006" instead of restating the methodology, which keeps the rest of the writing tight. **The notebook is the deliverable.** Plan for visitors landing on the notebook page directly, not always arriving through the dataset or the visualization. Write entries as if a stranger will read them out of order. --- The full live Notebook for the Periodic Table of Taylor Swift is at [ts.hosette.net](https://ts.hosette.net) (look for the Lab Notebook tab). This template is the shape it follows; the entries are yours to write.