Omar SobhandClaude Opus 5
f4adc8d0f9
Two things the operator found by listening to a real episode.
**1. Identifiers were spoken as digit soup.** The script genuinely said
"arxiv 2608.12888", which the voice reads as "two six zero eight point one two
eight eight eight". Same for three-decimal values: "0.506" and "0.004" became
long strings of spoken digits. A listener on a treadmill cannot write an
identifier down and does not need a third decimal place.
`speakable()` strips arXiv references and bare identifier-shaped numbers, and
rounds decimals to two places — with a carve-out that matters: 0.004 rounds to
0.00, which would claim the value was ZERO when the whole point was that it
collapsed to nearly nothing, so it says "under 0.01" instead.
Deliberately narrow: it removes identifiers and shortens over-precise decimals,
and does not paraphrase, reorder or summarise. The agents' words are still the
episode. It also preserves the sentence's full stop — swallowing it turned
"…financial retrieval, arxiv 2608.00183. This one's a catch." into one run-on
sentence, and the pause is how a listener knows a thought ended.
Note that `podcast-dialogue-writing.md` ALREADY said "no arXiv ids" and the
writer included them anyway. That is this project's recurring lesson restated:
an instruction is a request, and a listener deserves a guarantee. The prose asks
and the code enforces.
**2. It was written for someone who already knew the field.** The skill and the
script phase's task now target a bright sixteen-year-old: define an acronym in
the sentence that first uses it, describe the mechanism rather than naming it
("a road map with motorways and side streets" instead of "a hierarchical
navigable small world graph"), one idea per sentence. The test offered is
whether the listener could explain the finding to a friend afterwards.
That is not dumbing down — it is the constraint that forces a writer to say what
a thing actually does rather than what it is called.
Tested against the exact lines from the episode that was listened to.
366 tests pass.
Co-Authored-By: Claude Opus 5 <[email protected]>
100 lines
4.0 KiB
Markdown
100 lines
4.0 KiB
Markdown
---
|
|
name: podcast-dialogue-writing
|
|
description: How to turn a paper analysis into a two-host script a bright sixteen-year-old can follow while running, and the hard limits the audio pipeline imposes.
|
|
when_to_use: You are writing the script phase of a Continuous Research mission, turning analysis.md into script.md and episode.json.
|
|
tags: [research, writing]
|
|
---
|
|
|
|
# Writing for someone on a treadmill
|
|
|
|
The listener is moving. They cannot scroll back, cannot see a table, and are
|
|
half-listening. Everything below follows from that.
|
|
|
|
## Pitch it at a bright sixteen-year-old
|
|
|
|
Assume someone curious and clever who has **not** read the paper, does not know
|
|
the jargon, and cannot pause to look things up. That is not dumbing down — it is
|
|
the discipline that forces you to say what a thing actually does.
|
|
|
|
**Define an acronym the first time, in the sentence, then use it.**
|
|
|
|
> Bad: "NDCG at 10 of 0.15 on SciDocs."
|
|
> Good: "Their accuracy score was about 0.15 — where 1.0 is perfect. That is
|
|
> low."
|
|
|
|
**Say the mechanism, not the label.**
|
|
|
|
> Bad: "They use HNSW with hierarchical navigable small world graphs."
|
|
> Good: "The index works like a road map with motorways and side streets: you
|
|
> take the fast road most of the way, then drop down to local roads to
|
|
> find the exact house."
|
|
|
|
**One idea per sentence.** If a sentence needs a comma-spliced clause to
|
|
survive, it needs to be two sentences.
|
|
|
|
A good test: could the listener explain the finding to a friend afterwards? If
|
|
the only honest answer is "they would repeat a phrase they did not understand",
|
|
rewrite it.
|
|
|
|
## Numbers are spoken, not read
|
|
|
|
The audio pipeline strips identifiers and rounds over-precise decimals before
|
|
speech, but write it right in the first place — the safety net should never fire.
|
|
|
|
- **Never write an arXiv id.** "arxiv 2608.12888" is heard as "two six zero
|
|
eight point one two eight eight eight". Name the paper instead: "the ReFind
|
|
paper". The id is in the vault note if anyone wants it.
|
|
- **Two decimal places, maximum.** "0.506" becomes "about 0.51", and better
|
|
still "about half".
|
|
- **Round in speech.** "roughly a third faster" beats "34.7% faster". "About
|
|
three thousand questions" beats "2,847".
|
|
- **No URLs, no figure or table references, no version suffixes.** If it cannot
|
|
be held in the ear, it does not belong in the audio.
|
|
|
|
## Structure
|
|
|
|
Lead with the conclusion, then support it. A paper-by-paper walk is the wrong
|
|
shape: the listener does not know which papers matter until you tell them.
|
|
|
|
```
|
|
COLD OPEN one sentence: the single thing that changed today
|
|
THE MAIN the paper that actually matters, 3-4 minutes
|
|
THE REST two or three, a minute each
|
|
NOTHING what you looked at and dismissed, 20 seconds
|
|
```
|
|
|
|
"Nothing" is not filler. Knowing that eleven papers were read and eight did not
|
|
matter is what makes the three that did credible.
|
|
|
|
## Two hosts, with a reason to be two
|
|
|
|
HOST carries the thread and asks what the listener would ask — including "wait,
|
|
what does that mean?". GUEST has read the paper and answers in plain words. The
|
|
second voice exists so that confusion can be voiced and cleared, not so that
|
|
alternating names can decorate a monologue.
|
|
|
|
> HOST: Twelve percent better recall — is that on something we care about?
|
|
> GUEST: That is the catch. They tested on a million short web snippets. Ours
|
|
> are longer and there are far fewer of them, so their win might not
|
|
> survive the switch.
|
|
|
|
## Hard limits, not style preferences
|
|
|
|
`episode.json` is consumed by the audio pipeline and these bounds are enforced:
|
|
|
|
```json
|
|
{ "title": "<one line, under 80 characters>",
|
|
"highlights": ["<each 10-70 characters>", "..."] }
|
|
```
|
|
|
|
At most **5** highlights, each **10-70 characters**. Outside that range the
|
|
entry is rejected, not trimmed.
|
|
|
|
Target **seven minutes of speech, roughly 1,000 words**.
|
|
|
|
## Cut rather than pad
|
|
|
|
If one paper mattered, write four minutes about one paper. An episode padded to
|
|
length teaches the listener to skip, and once they skip, the pipeline is worth
|
|
nothing.
|