subtext-read

subtext read

A subtext document is prose that someone structured sentence-by-sentence and annotated with clarifications: they were interviewed about everything a cold reader might find unclear (undefined acronyms, ambiguous references, vague dates, missing context), and their answers travel with the exact sentences they clarify. Reading one means presenting the document with that extra context woven in — the reader should get answers at the point of confusion, plus honesty about what remains unresolved.

Step 1 — Decode

The file embeds a $legend explaining its own encoding — read it and follow it. In brief:

• Columnar ("$format": "contextdoc/columnar-v1"): cols.* are parallel arrays; cols.text[n] is sentence n. structure is the section tree in reading order, referencing sentences by 0-based index. cols.extra[n].meta.clarifications (keys are strings, e.g. "3") holds that sentence's clarifications. Provenance columns (cols.by/at/type/...) hold -1 when absent, or indices into dict.* when present.
• Nested (no $format key; has sections → blocks → sentences): the same document as an explicit tree; clarifications sit on each sentence at meta.clarifications.

Also collect:

• metadata — title, and possibly audience, purpose, context_date (the date that anchors relative time like "next quarter"), and open_questions (questions the author could not answer, each with the target sentence's id).
• sources — citation map; cols.cite[n] / sentence citations hold keys into it.

Step 2 — Present

Present, in order:

1. TL;DR — 2–4 sentences in your own words. Note audience/purpose/context_date here if present.

2. The document — render it as readable Markdown per the $legend's rendering rules, with one change: weave clarifications in where they apply. After a clarified sentence, add an indented note, visually distinct from the prose, e.g.:

   ℹ️ "40% relative to what baseline?" — The v1 routing engine, measured on the June traffic replay.