Konubinix' opinionated web of thoughts

How to Write and Audit a Note

Braindump

Table of Contents
what
a note is a self contained org-mode file digging into one subject — a question to answer, or a topic to explore.
how
the title summarizes that subject, and a heading states it in full when the title cannot.
who
the agent that writes is the writer, the agent that audits is the auditor, and the human is the user.
rule
the user talks informally, and the writer lands what they mean in the note’s own words and form.

values that an ia agent must respect

Continuous improvement

rule
a bad tool is surfaced to the user.
  • why: tools improve by being reported.
rule
a bad tool is fixed.
  • why: a workaround hides the defect and ships it again next time.

Intellectual honesty

rule
the conclusion says what the source supports and no more.
  • why: overreading a source to reach a neater result is advocacy, not reporting.
rule
the why behind a choice is always a real one.
  • why: it is the easiest thing to fake — a plausible justification reads almost exactly like a real one.
  • how: a reason the writer does not know is asked of the user.
  • scope: landing one in a note needs the user’s consent too, backed or not, per the form of a bullet.
rule
nothing is asserted without a backing.
  • how: a claim the note does not need is cut, not backed.
  • how: the user backs a why they accepted, and it needs nothing else.
  • how: the user backs a definition they stipulate, with their consent.
  • how: backed premises back a claim that follows from them.
  • how: a source backs a claim.
    • how: a footnote holds the verbatim and a link to the source.
    • scope: a source is the only backing that comes in degrees.
      • how: a claim a source backs says where on that range its support sits.
  • how: with no backing, a claim is established, held as a reserve, or asked — never asserted bare.
rule
the writer is strictly forbidden to draw conclusion the premises do not entail.
  • how: the premises are read to the letter.

Epistemic modesty

rule
you are the worst-positioned reader of your own work.
  • why: the bias that chose a quote reads it as supporting more than it does.
rule
a conclusion is trusted only after surviving an attack.
  • how: before concluding X, go looking for what would establish not-X.
    • why: the warrant for X is the weakness of that case, not the absence of a search for it.
  • scope: calling a question settled is itself such a conclusion.
rule
doubt is recorded, not hedged.
  • why: « some say », « it is generally accepted », the writer’s « I believe » let an unsourced claim wear the costume of a sourced one.
  • rule: a note that ends in cited, unresolved disagreement is finished, not failed.
  • rule: a claim carries the epistemic marker its support warrants.
    • why: truth comes in degrees — a claim is rarely wholly established or wholly baseless, and the marker is where it sits on that range.
rule
everything the note says a source backs is verified, or said to be unknown.
  • why: a placeholder is a lie shaped like a link.
rule
a reason the user holds is weighed in the work.
rule
never conclude in the absence because of the lack of evidence
  • why: “Absence of evidence is not evidence of absence”1

How one reads a note

rule
a tl;dr sits before the first heading.
  • why: a human reads a note top to bottom and needs to get a feeling whether reading the note is useful
  • scope: a note with nothing useful to say yet carries none.
rule
the writer focuses on the subject and nothing else — no detour, no meta-commentary, no secondary justification, no iteration, no mistake, whatever the circumstances.
  • why: a writer drifts by default, and no one cares that the writer worked badly on the way.
rule
the user and writer make sure the content stays coherent when transcluded and never mention transclusion in the note
  • why: the human reading the note don’t know about transclusion and stuff
rule
when discovering a note, the writer reads it thoroughly, as well as the transcluded part before working on it
  • why: the human reading the note will see that content

The outline

rule
past 50 lines of body before the first subheading, or 7 siblings excluding a footnotes or unexported heading, go deeper — headings under a parent heading, bullets into sub-bullets.
  • scope: where a heading has no subheading, the body runs to the end of its section.
  • scope: source blocks, export blocks, their results and footnote definitions do not count toward the 50.
  • scope: the count of 7 does not reach a catalog note.
rule
a note whose structure lives in its tags declares itself a catalog.
  • why: the rule above guards against a nest of headings nobody can read; where the tags carry the structure and agenda views pull the content out, it has nothing left to guard.
  • how: a #+MODE: catalog line, among the keywords at the top of the note, puts it in that mode.
  • rule: the writer never writes that line — the exemption is the user’s to grant.
rule
a note whose outline has grown too long to hold in the head carries a table of contents.
  • why: the whole structure is then visible at a glance and every heading is one click away.
  • how: in org-mode, a #+TOC: headlines N directive placed where the overview belongs, or #+OPTIONS: toc:t to let the exporter render one.
  • scope: a short note with two or three headings does without it.
  • scope: a catalog note does without it too — its agenda views are the overview.
rule
each heading moves by exactly one step — the next concept the note depends on, or a candidate the subject could have been confused with, ruled out.

The words

rule
fewer words is the default.
  • check: readonly_note_hedges lists the hedges and emphasis markers lost between a passage and its rewrite.
rule
readability counts2.
rule
one word per meaning — a second name for the same thing reads as a second thing.
  • how: when the user gives a second word for something already named, the writer asks which of the two to keep, rather than adopting the new one.

Where each piece goes

scope
an argdown map takes a graph — an objection, a premise two conclusions share, reasons that hold only combined — since bullet nesting already covers a tree.
rule
nothing is stated twice — inside a note the duplicate is cut, across notes it is refactored out and pointed at.
  • why: simple is better than complex3.
rule
the writer asks the user what to do with a cut piece.
rule
the writer reads or links another note only if the user agrees.
rule
the note being written is the only one edited.

The form of a bullet

rule
the narrative of a note is structured — every body line is a bullet of the form - <intention word> :: <claim>.
  • why: the writer pads when writing free-form text, so a list of bullets carries more than a paragraph of useless writer words.
  • why: the structure also makes a flaw easier to find, and that is worth the cost in readability.
  • how: the « intention word » is the single word before ::, naming what the line does, and it is taken from the vocabulary.
  • scope: tables, quote blocks and footnote definitions keep their own form.
rule
one meaning per bullet.
rule
a bullet stays under 300 characters, links counted as they render.
  • why: without a cap the writer pads the bullet itself with useless words.
  • scope: a nested bullet counts on its own, not toward the one above it.
rule
a reason the user holds is a why, and it needs no other backing.
rule
a why is written by the user.
  • scope: the writer rewrites its wording, never its meaning or its intention word.
rule
a why the user has not explicitly accepted is never written.
  • why: a writer that writes a why unasked invents the user’s reason rather than recording it.
  • why: the user is the one who checks, a justification being easiest to fake and the writer worst-positioned to catch its own.

The vocabulary

rule
an « intention word » comes from the list below, and no other word names a bullet.
  • rule: the writer creates no « intention word » without the explicit consent of the user.
  • rule: the writer never uses an « intention word » for a meaning other than the one the list gives it.
  • why: it keeps the writer from writing carelessly.
rule
a note that needs one more word declares it in itself.
  • how: a #+INTENTION_WORDS: word word line, anywhere in the note, adds those words for that note alone.
(defconst konix/note-intention-words
  '(("tl;dr"      . "what the note says, in one line")
    ("authorship" . "who wrote this note")
    ("what"       . "the thing the bullet names or defines")
    ("why"        . "the user's reason for what precedes")
    ("therefore"  . "the conclusion that follows from what precedes")
    ("how"        . "the way it is done, the mechanism")
    ("who"        . "the party the bullet is about")
    ("rule"       . "what has to hold")
    ("scope"      . "where the rule above reaches, and where it stops")
    ("example"    . "one instance of what precedes"))
  "The intention words a note may use, each with what it does.")

What a checker can decide

rule
only these flaws are mechanical.
  • what: the bullet’s form.
    • flaw: a body line that is not a bullet, or a bullet with no ::.
    • flaw: an « intention word » that is more than one word.
      • scope: one word is a run with no whitespace in it — au-delà, peut-être, tl;dr — so a mark inside a word is part of it.
    • flaw: an « intention word » the vocabulary does not define, the note’s #+INTENTION_WORDS counted in.
    • flaw: a tl;dr or authorship bullet that sits under a heading instead of before the first one.
    • flaw: a why or therefore bullet with nothing preceding it.
      • scope: a heading precedes the bullets under it, so only a bullet at the very top of a note is caught.
  • what: the length of a line or a bullet.
    • flaw: a line of 120 characters or more, or a bullet of more than 300, with links counted as they render.
  • what: the outline.
    • flaw: a heading with more than 7 children.
      • scope: not in a catalog note.
    • flaw: a heading with more than 50 lines of body.
    • flaw: more than 7 headings and no table of contents.
      • scope: not in a catalog note.
  • what: a link.
    • flaw: a link that does not resolve.
  • what: a footnote.
    • flaw: a footnote whose text sits in the line instead of at the foot.
    • flaw: a footnote reference with no definition.
    • flaw: a footnote label defined more than once, which is what a reference wrapped to the start of a line becomes.
rule
the rest is not mechanisable, and a silent checker is not conformance.
check
note_mechanics reports those flaws for an open note, and a count for each « intention word » in use.

How the file is typeset

rule
the user sets #+filetags, #+KONIX_ORG_PUBLISH_KIND, every :CUSTOM_ID: and the authorship bullet, and the writer neither adds nor edits one, nor mentions one to the user.
rule
an authorship bullet sits before the first heading.
  • scope: no note is obliged to carry one.
rule
a file is opened with the ensure_file_open MCP tool.
rule
the text under a heading is indented two spaces, as in this note.
rule
every line stays under 120 characters, text wrapping to fit.
  • how: a link counts only its visible part, the target being invisible in the rendered line.
  • scope: a keyword line and a table row cannot be wrapped and are exempt.
  • scope: a line babel wrote is not the writer’s line and is exempt too.
rule
French prose carries the espace insécable where French typography asks for one.
  • how: note_insecables inserts U+00A0 before : ; ? ! » and after «.
rule
the writer strips the insécables before editing a typeset note, and restores them after.
  • how: note_strip_insecables runs, then the whole edit pass, then note_insecables.

The audit loop

rule
the auditor is a different party from the writer, and judges without ever editing.
rule
each audit covers one fix — the whole patched passage against every rule, not « does this fix it? ».
  • why: a batch is read at one pace, and the fix that needed a fresh look goes by with the rest.
rule
each audit reports every objective flaw found, in one verdict.
  • why: subjective battles never end.
rule
each audit runs on the model the work needs — not Opus for a straightforward command.
rule
the writer asks the user to confirm a new term before using it.
  • why: writers coin very poor terms.
rule
when a fact changes, the writer asks rather than assumes.
  • why: the user may change their mind.
rule
a contested flaw escalates to an adversarial debate.

  1. Absence of evidence is not evidence of absence.

    — https://en.wikipedia.org/wiki/Evidence_of_absence ([2026-08-22 Sat])

     ↩︎

  2. « Readability counts. » — PEP 20, The Zen of Python, Tim Peters. ↩︎

  3. « Simple is better than complex. » — PEP 20, The Zen of Python, Tim Peters. ↩︎