sbobinatron

name	sbobinatron
description	Use when turning a WhisperX/Whisper automatic transcript (recording-N.txt + recording-N.json) of a recorded lecture into study material or an Italian "sbobina"; when cleaning ASR errors, garbled medical/technical terms, or overlapping-speaker noise out of a lecture transcript; when a student needs a study-ready writeup from a recording.

WhisperX transcript → Italian sbobina

Overview

Turn a noisy WhisperX lecture transcript into a study-ready sbobina (Italian detailed lecture writeup) through a fidelity-first, verification-gated pipeline. Never jump straight to the summary.

Core principles:

• Fidelity before polish. A line-by-line faithful reconstruction comes first and is the source of truth. The sbobina is derived from it, not from the raw transcript.
• Two independent confidence axes. Always separate "did the professor say this?" (transcription confidence) from "is this the correct value?" (factual/guideline concordance). One can be high while the other is low.
• The sbobina is gated. Do NOT write it until the fact-check report AND the corrected reconstruction exist. The sbobina is built from the corrected reconstruction, so verified values flow into the study material instead of ASR errors.

When to use

• Input is Whisper/WhisperX output (recording-N.txt + recording-N.json; maybe srt/vtt/tsv).
• Audio quality is poor: mistranscribed terms, words injected from other speakers, garbled numbers.
• Deliverable is study material (a sbobina), in Italian.

Not for: already-clean transcripts needing only formatting; verbatim/legal transcription where reconstruction is unwanted.

Invocation modes

A lecture may span multiple recordings (e.g. a mid-lecture break splits it into recording-5 and recording-6). Input may also be audio (see step 0) or, for a merge, already-corrected files. Support these modes:

• Single recording (default): run steps 0–9 on the one file → one sbobina (+ docx).
• Multi-recording, single sbobina: user points to several files. Run steps 0–7 independently for each (each gets its own -ricostruzione, -verifica, -ricostruzione-corretto). Then run step 8 once over all the corrected files, merged in lecture order into ONE sbobina covering the whole lecture, and step 9 to export it.
• Stop at corretto (user asks not to write the sbobina yet): run steps 0–7 only, then stop. Use when processing files one at a time to merge later.
• Merge-only: user points to existing -ricostruzione-corretto.txt files → run steps 8–9 only, merging them into one sbobina and exporting it.

Name a merged sbobina for the whole lecture (e.g. recording-5-6-sbobina.md or a topic name), not for a single part.

Output location

Write every derived file (uncertain-spans list, ricostruzione, verifica, ricostruzione-corretto, sbobina, sbobina .docx) into an output/ subdirectory inside the transcript folder (e.g. sbobine/output/) — never loose alongside the WhisperX audio/transcript files, which stay untouched. Create it if it does not exist (mkdir -p sbobine/output). All paths below like recording-N-ricostruzione.txt mean sbobine/output/recording-N-ricostruzione.txt.

Pipeline — do the steps in order, never skip the gate

0. (Optional) Obtain the transcript. If the user points to an audio file (.m4a/.mp3/.wav/…) instead of the expected recording-N.txt + .json, first check that file's directory for those WhisperX outputs. If present, use them. If absent, generate them with WhisperX — the repo's pyproject.toml pins it, so run through uv from the repo root:

   uv run whisperx --model large-v3 --language it /path/to/recording-N.m4a
   

   Adjust --language to the lecture's language. This produces the txt/json (+srt/vtt/ tsv) the pipeline needs. Then continue from step 1.

1. Triage. Skim the txt to identify domain, language, register, and structure (case-based lecture? how many topics?). This drives reconstruction judgment and later subagent partitioning.

2. Faithful reconstruction → recording-N-ricostruzione.txt (Italian).

   • Work segment-by-segment, keeping the original line numbering so it stays verifiable against the raw file.
   • Read BOTH files: the .txt for content, the .json for confidence. Per-word score (and per-segment avg_logprob, when the file has it) tell you WHERE Whisper was guessing. Run uv run flag-uncertain.py sbobine/recording-N.json -o sbobine/output/recording-N-uncertain.txt (the script lives in this skill's directory, the input json in the transcript folder) to rank the shakiest spans and save them to a txt file under output/, then concentrate interpretation there. (Omit -o to print to stdout instead.) [seg N] in its output is line N of the .txt (the txt is one segment per line), so flagged segments map straight onto reconstruction lines.
   • Fix obviously mistranscribed terms from context + domain knowledge (drug names, eponyms, scores, study names).
   • Flag uncertain reconstructions with [?]. Mark noise / other-speaker fragments (counting, interjections, side chatter) as [rumore] and exclude them from meaning.

3. Extract the claim list. Using prior knowledge, list every checkable statement — NOT just numbers: dosages, cut-offs, timings, drug names, study names + years, eponyms, classification criteria, scores. These are the highest-risk ASR items.

4. Dispatch Sonnet subagents to web-verify the claim list. Partition by topic cluster: ~1 agent per 1–2 topics (a 5-topic lecture → 3–4 agents). Focused agents beat one giant agent. Brief each agent to:

   • Prioritize Italian guidelines first, then EU, then international. The sbobina is for an Italian medical school, so values must match Italian practice where it exists. Search preferentially for Italian sources (societies/agencies e.g. SIP, ISS, AIFA; Italian-language reviews) and EU sources (EULAR, ESC, ESPGHAN, etc.). English-only search skews to US/AHA sources — do not let a US value silently become "the" value.
   • Query in BOTH Italian and English and cross-match: an Italian-guideline value confirmed by an EU source is high-confidence. A US-only value (e.g. AHA) must be labelled US-specific, not adopted, when an IT/EU value exists.
   • Return structured findings per claim: transcript value; IT/EU value (with source URL + society/country); US value if it differs; concordance.

5. Reconcile. Sanity-check every returned value against (a) your prior knowledge and (b) the local context (e.g. Italian/European practice, not US). The web often returns region-specific or plain wrong values. Divergence between prof-said / web-says / local-standard is the signal to investigate.

6. Fact-check report → recording-N-verifica.md (Italian). Score every item on the two axes, as percentages in 10% bands (fasce del 10%):

   • T — transcription confidence (did the prof say this?).
   • G — factual/guideline concordance for the local context (is it the right value?). Give the correct value where they diverge; end with a short "correzioni da applicare" list; ⚠️-mark items to fix. Cite sources.

7. Apply corrections → recording-N-ricostruzione-corretto.txt (Italian). Take the faithful reconstruction and substitute the corrected values from the verifica report inline, keeping the original line alignment. Mark each changed line briefly so it stays traceable, e.g. [corretto: "15-18h" → 10-12h]; full provenance lives in the verifica report. Leave genuinely unresolved [?] in place. This corrected reconstruction — NOT the raw one — is the single source the sbobina is built from.

8. GATE — only now write the sbobina → …-sbobina.md (Italian, the MAIN deliverable), built from one or more -ricostruzione-corretto.txt files. When a lecture spans several recordings, merge them in lecture order into ONE coherent document, deduplicating overlaps at the seams — do not concatenate separate sbobine. Dispatch a single subagent to write it (a large generative task — isolating it keeps the orchestrator's context clean). Give the subagent all the corrected reconstruction(s) as its source plus the verifica report(s) (for the margin notes), and the sbobina structure below. The subagent must run on the orchestrator's own model (Opus/Fable) — NOT Sonnet. Sonnet is only for the cheap parallel web-check fan-out (step 4); the main deliverable needs the stronger model. In the Agent tool, set model to match the orchestrator (opus/fable) rather than leaving the default.

9. Export the deliverable to .docx → …-sbobina.docx. The sbobina's final, user-facing form is a Word document. Convert the finished …-sbobina.md with pandoc, pinned in pyproject.toml as pypandoc-binary (it bundles the pandoc binary — no system install needed), run through uv from the repo root:

   uv run python -c "import pypandoc; pypandoc.convert_file('sbobine/output/recording-N-sbobina.md', 'docx', outputfile='sbobine/output/recording-N-sbobina.docx', extra_args=['--standalone','--toc','--toc-depth=2','-f','gfm'])"
   

   -f gfm preserves the markdown tables; --toc adds a navigable Word table of contents. Name the .docx to match its sbobina (e.g. recording-5-6-sbobina.docx for a merged lecture). This is the final step — every run that produces a sbobina ends by producing its .docx. (If the harness sandbox blocks the uv cache/network, re-run this one command outside the sandbox.)

Sbobina structure (the deliverable)

• Indice (TOC).
• TL;DR / "Da sapere assolutamente" — the must-know points.
• Lezione rielaborata: reorganized by topic like a textbook — comprehensive, not terse. Include everything relevant the professor said, as study-ready prose with headings, tables, and lists. Preserve case-based structure if the lecture had one.
• Note a margine wherever a corrected value differs from what the prof said (keep provenance: what he said + the corrected value).
• "Punti da verificare" box for residual [?] items.
• Optional: also render as an HTML Artifact for a polished, shareable version.

Deliverables & naming

All derived files live in the output/ subdirectory of the transcript folder (e.g. sbobine/output/); the WhisperX audio/transcript files stay in the folder itself.

File (under sbobine/output/)	Content	Format
recording-N-uncertain.txt	Ranked shakiest transcript spans (from flag-uncertain.py -o)	txt
recording-N-ricostruzione.txt	Faithful, line-aligned reconstruction	txt
recording-N-verifica.md	Two-axis (T/G) fact-check report	md
recording-N-ricostruzione-corretto.txt	Reconstruction with verified corrections applied inline; the basis for the sbobina	txt
recording-N-sbobina.md	Study-ready sbobina (MAIN deliverable)	md
recording-N-sbobina.docx	Same sbobina exported to Word (final deliverable, step 9)	docx

All artifact content is in Italian; conversation with the user and internal reasoning stay in whatever language the session is using.

Common mistakes

• Writing the sbobina before verifying facts → ASR errors propagate into study material. Respect the gate.
• Building the sbobina from the raw reconstruction instead of -ricostruzione-corretto.txt → corrections silently lost.
• Verifying only numbers → drug names, study names, and eponyms are mistranscribed just as often.
• Trusting the web's first hit → reconcile with local practice + prior knowledge (region-specific values differ).
• Collapsing T and G into one score → you lose "he said it but it's wrong" vs "right value, unsure he said it".
• Ignoring the json → score/avg_logprob are what make [?] principled instead of guesswork.
• Treating noise as content → counting readouts and other-speaker interjections must be excluded, not reconstructed.
• Stopping at the .md → the user-facing deliverable is the .docx; step 9 (pandoc export) is the last step, not an optional extra.