Konubinix' opinionated web of thoughts

How to Write a Literature Note

Braindump

Table of Contents

how to write and audit a note

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

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: note_hedges lists the hedges and emphasis markers lost between a passage and its rewrite.
rule
readability counts1.
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 complex2.
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 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.
  • 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 line of 120 characters or more, or a bullet of more than 300, with links counted as they render.
  • flaw: a link that does not resolve.
  • 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.
  • 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.
  • flaw: a footnote whose text sits in the line instead of at the foot.
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.
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.

A literature note

what
a literature note is a note whose subject calls for a literature search.
what
a literature search is the work of finding and reading sources.
what
the author is whoever wrote a source.

The subject drives the search

rule
the subject is the user’s, and the writer clarifies it before writing any other line.
rule
the writer cites what the subject assumes, or asks the user to reword it.
  • why: the assumption steers what is read and quoted.
rule
the literature search runs once the subject is settled.
rule
the note is finished when its subject is treated, not when every source is read.

The writer reports, never ever anything else

rule
the writer never states its own opinion; the note reports what the literature says.
rule
where the literature contradicts itself, the note shows the contradiction.
  • how: bullet points for simple linear reasoning, argdown for more complicated situations
rule
the writer is strictly forbidden to invent information not present in the literature

Source quality is part of the claim

Weighing a source

why
being a citation is not being evidence.
rule
the epistemic marker a source warrants is set by several dimensions, and no single one settles it.
  • proximity: primary — the thing itself or its maintainer; secondary — a third party reporting on it.
  • standing: the author’s standing in the domain the claim falls in — high where the author is known for that domain, none where the author is known for another.
  • remit: whether the claim falls inside what the source is authoritative about — a spec settles what it requires, not why it was designed so.
  • currency: whether the text still describes the current state — the version date read, the deprecation noticed.
  • interest: whether the author gains by the claim holding.
  • corroboration: whether an independent source says the same.
reserve
the dimensions are not exhaustive.

Citing a source

rule
a citation names its kind, primary or secondary.
rule
a secondary is cited only where the writer cannot reach the primary — paywalled, deprecated, untranslated — and carries the reason.
rule
the verbatim is the source’s own text, altered only by the note’s own typographic pass, taken under its canonical URL, the URL verified.
rule
the verbatim is trimmed to the single claim it backs.
rule
an unsigned source does not survive the audit — an anonymous post, an undated entry, a screenshot without provenance, an AI-generated summary.
  • why: internet is full of lies and bullshit

Source notes

rule
a source cited by several notes lives in a source note of its own
  • how: the source notes are
    base_de_sources_legales.org
rule
the writer is encouraged to read and improves a source note freely.

Chromium is the fallback for webfetch

rule
the writer fetches a source with webfetch, and with chromium where webfetch struggles.
  • why: chromium behaves like a real browser, so a site serves it a 403 less often.
rule
where chromium is not among the MCP tools, the writer stops and asks the user to enable it.

Notes linking here

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

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