Use when reviewing a paper by listening — reads LaTeX paragraphs aloud via macOS TTS, pauses after each to flag confusion/gaps as a naive reader, proposes fix options, applies edits inline, then advances. Invoke with /paper-read-aloud or /paper-read-aloud <section-number>
Interactive paragraph-by-paragraph paper review using text-to-speech. Reads each paragraph aloud, then analyzes it as a naive first-time reader. Issues are reported with 2-3 fix options; the user picks one (or skips), the edit is applied, and the skill advances to the next paragraph.
The core insight: hearing prose aloud exposes awkward phrasing, overloaded sentences, and logical gaps that silent reading misses. The forced stop after each paragraph prevents skimming.
Preferred: edge-tts — Microsoft neural voices, natural-sounding, free.
At session start, check if edge-tts is available by running which edge-tts. If not found, tell the user:
edge-ttsis not installed. Install it withpip install edge-tts, then re-run this skill.
Do NOT install it automatically. Wait for the user to confirm installation.
If edge-tts is available, use it as the TTS engine with the voice (warm, confident male). The command pattern is:
en-US-AndrewNeuraledge-tts --voice en-US-AndrewNeural --file /tmp/paragraph.txt --write-media /tmp/para.mp3 2>/dev/null && afplay /tmp/para.mp3
Fallback: macOS say — only if the user explicitly requests it or declines to install edge-tts.
/paper-read-aloud or /paper-read-aloud N/paper-read-aloud # start at Section 1
/paper-read-aloud 3 # start at Section 3
digraph read_aloud {
rankdir=TB;
"Read paper.tex" -> "Parse sections & display index";
"Parse sections & display index" -> "Jump to target section";
"Jump to target section" -> "Split into paragraphs (blank-line delimited)";
"Split into paragraphs (blank-line delimited)" -> "For each paragraph";
"For each paragraph" -> "Display raw LaTeX + line range";
"Display raw LaTeX + line range" -> "Strip LaTeX → plain text";
"Strip LaTeX → plain text" -> "Run: say -f /tmp/paragraph.txt";
"Run: say -f /tmp/paragraph.txt" -> "Wait for say to finish";
"Wait for say to finish" -> "Naive reader analysis";
"Naive reader analysis" -> "Issues found?" [label="analyze"];
"Issues found?" -> "Next paragraph" [label="no issues"];
"Issues found?" -> "Fix menu (A/B/C per issue)" [label="yes"];
"Fix menu (A/B/C per issue)" -> "User picks or skips";
"User picks or skips" -> "Apply edits via Edit tool";
"Apply edits via Edit tool" -> "Re-read paper.tex for updated lines";
"Re-read paper.tex for updated lines" -> "Next paragraph";
"Next paragraph" -> "For each paragraph" [label="more"];
"Next paragraph" -> "Session summary" [label="section done"];
"Session summary" -> "Continue to next section?" [label="ask"];
}
Read the full paper.tex file. Default path: paper.tex in the current directory.
Extract all \section{...} and \subsection{...} headers with their line ranges. Display a numbered index:
Sections in paper.tex:
1. Introduction (lines 45-120)
2. Library Architecture (lines 121-210)
3. Harness Design (lines 211-340)
...
If the user provided a section number, start there. Otherwise start at Section 1.
Split the target section's content by blank lines. Each blank-line-delimited block is one paragraph. Track the line number range for each paragraph.
Display: "Reading Section N: <title> — X paragraphs. Starting..."
Before passing text to say, strip LaTeX to natural speech:
| LaTeX construct | Speech treatment |
|---|---|
\cite{...} | Remove entirely |
\label{...} | Remove entirely |
\ref{...} | Say "figure reference" or "section reference" |
\eqref{...} | Say "equation reference" |
\textbf{...}, \textit{...}, \emph{...} | Keep inner text |
\texttt{...} | Keep inner text |
$...$ inline math | Best-effort pronunciation (e.g., $O(n^2)$ → "O of n squared") |
\begin{figure}...\end{figure} | Skip block entirely |
\begin{table}...\end{table} | Skip block entirely |
\begin{lstlisting}...\end{lstlisting} | Skip, say "code listing skipped" |
\begin{equation}...\end{equation} | Say "equation block" |
\begin{itemize} / \begin{enumerate} items | Keep as plain text, strip \item |
\\, \newline | Remove |
~ (non-breaking space) | Replace with space |
\%, \&, \_ | Replace with the literal character |
Write the stripped text to /tmp/paragraph.txt and run say -f /tmp/paragraph.txt to avoid shell quoting issues.
For each paragraph:
lines 142-155)./tmp/paragraph.txt.say -f /tmp/paragraph.txt via Bash. Wait for it to finish.Analyze the paragraph as if hearing it for the first time. Only consider text seen so far in this session. Check for:
If no issues found: print "No issues." and wait for the user before advancing. The user may type next or n to continue, or offer their own observations. Never auto-advance — always pause after every paragraph.
For each issue found, use AskUserQuestion:
After the user picks, apply the edit with the Edit tool.
After all issues in the paragraph are resolved, advance to the next paragraph.
The user can type these at any prompt during the loop:
| Command | Effect |
|---|---|
next or n | Skip this paragraph, no analysis |
stop | End session immediately, show summary |
replay | Re-read current paragraph aloud (before edits) |
re-read | Re-read current paragraph aloud (after edits applied) |
When the user types a navigation command instead of picking a fix option, honor the command.
\begin{figure} or \begin{table} block is encountered as a paragraph, skip it but announce: "[Figure: <caption text>] — skipped.""[Code listing] — skipped.""equation block" for the math content itself.paper.tex to get updated line numbers before processing the next paragraph. This ensures the Edit tool always targets correct text.say finish naturally. No splitting. The user can type stop to end the session.When stop is typed or all paragraphs in the section are done:
Session complete.
- Paragraphs read: 12
- Issues found: 5
- Fixes applied: 3
- Skipped: 2
"Continue to next section?"This skill does NOT do:
paper-revision for that)say "text with quotes" directly — use say -f /tmp/paragraph.txt to avoid shell quoting issuesAskUserQuestion