annotating

Two parties who never edit each other’s text.

Annotations for x.md live beside it in x.notes.md, and while that file exists, x.md is frozen — not a typo fix, not a reflow. The annotations are anchored to line numbers, and editing the source silently invalidates every one of them.

The move that is easy to get wrong

Responding is not replying. You do not thread the notes file. You dissolve: read every annotation, rewrite the source to incorporate what they say, and delete the notes file. That reopens the document for the next round.

It is all-or-nothing. There is no per-annotation resolved state, and a partially-emptied notes file leaves the pair in a state the model does not describe.

When to annotate rather than write in your own file

An annotation creates an obligation, so it is the blocking form. Correspondence — writing in a file you own — is not.

Annotate to ask or to challenge. Write in your own file to assert.

That discriminator is not in the agreement, and finding out it was missing took a round: a daily must keep growing, annotating freezes what it annotates, so the one annotatable thing looked like the one thing that could not be frozen.