Where a human argues with the record

2026-08-26 · commit 31d5484 · node 2026-08-26-cairn-notes-on-nodes

The premise of this project is that the agent doing the work writes the record. The consequence nobody planned for is that you become a reader of your own research log — and readers have reactions. A doubt. A correction. “The number here is wrong.” “This is the one that matters.”

Until this landed there were two places to put such a thought, and both were wrong:

A status change, which lies about what happened. Nothing about the work moved; you just read it.
The inbox, which detaches the thought from the node it is about — and a reaction that has lost its referent is close to worthless six weeks later.

So there is a third thing:

cairn note 2026-07-20-polyid-run-variance "the spread looks bimodal — seeds?"
cairn note polyid-run-variance                 # unique suffix is enough; opens $EDITOR
cairn note --list --project polyid

It appends a dated bullet under ## Notes in the node body:

- **2026-08-26** (jlaw) the spread looks bimodal — does it track the seed?

Three things about this are deliberate

It is a body edit, not a status change. status, updated and history do not move, because a note is not a claim about the state of the work. If it moved updated, the replay slider would show a status change that never happened — and the replay being trustworthy is worth more than the convenience.
No new field, against rule 4, which this is the case that most wants to break. The line carries its own date, so a note stays findable by reading the body — the same way ## Next was already read. A notes: list would be a fifth list to maintain and a sixth thing to validate.
“Unanswered” is derived. A note dated at or after the node's last history entry is one no later work has responded to; once the thread moves, the note stops being reported. That is what keeps it off a nag list — and a nag list is a thing people stop reading, at which point it is worse than nothing.

It commits by default, and that is the one exception

capture deliberately does not commit. note does — because decision 6 refuses to commit a node you have not seen, and a sentence you just typed is the definition of seen. The whole value is that it is visible from the other machine tomorrow.

The note is written to the file before the commit is attempted, so a commit that fails on unrelated schema drift costs it nothing.

The direction nobody asked about

This also works the other way round, which is the answer to “can the agent pick up on comments I left?”

Yes. Notes live in the node body, so they are in standup's resume packet, in the session-start context, and in the report. A note is how you hand an instruction to next week's session without writing a prompt.

One rule that is a matter of authorship rather than tooling: a note in a human's voice is theirs to write. An agent recording an observation of its own writes a history note on a status change, or an inbox/ capture — not a ## Notes bullet under someone else's name.