subtext-read

name

subtext-read

description

Read a subtext document — a .subtext.json file (or pasted JSON) containing a sentence-level document tree in the contextdoc/columnar-v1 format, where sentences carry author-supplied clarifications answering questions a reader might have. Use when the user shares a .subtext.json file or JSON whose "$format" is "contextdoc/columnar-v1" (or a nested tree with sections/blocks/sentences), and wants to read it, summarize it, or ask questions about it.

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.

   Sentence text is quoted verbatim, never paraphrased. Clarifications are the author's words too — do not embellish them. For a clarified sentence inside a list, nest the note as an indented sub-line of its list item rather than breaking the list. When embedding the rendered document inside your response, demote its heading levels as needed so they nest under your own headings. For a long document, offer the rendered version rather than dumping it unprompted; lead with the TL;DR and section summaries.

3. Open questions — if metadata.open_questions is non-empty, list them as known gaps: quote each affected sentence and the unanswered question. (A sentence can have an open question without any clarifications — the two are complementary.) Never guess an answer to an open question; they are flagged precisely because the author could not answer them.

Never show internal sentence IDs (s-NNNN) to the user — quote the sentence text instead; the IDs are bookkeeping inside the file.

Step 3 — Answer follow-ups

When the user asks about the document:

• Ground every answer in the verbatim sentence text plus its clarifications. Clarifications are authoritative author-supplied context — prefer them over your own inference, and attribute them ("the author clarified that…") so they aren't mistaken for the original prose.
• Resolve citations through sources and give the URL when a claim's backing is asked about.
• If the answer touches an open question, say so explicitly instead of speculating.
• If provenance is present (non--1 columns / authored_by fields), you can answer who wrote what, when, and whether it was a human or an agent (dict.type / author_type); requested_by names the human behind an agent's edit. Most subtext files carry no provenance — then say the file doesn't record it.