talksmith:polish-ascii

talksmith:polish-ascii — Mechanical ASCII extraction + final.md rewrite

The diagram-illustrator picks templates and dispatches talksmith:ascii-to-svg per block; the editor owns the surrounding rewrite of final.md and the sidecar files. This skill is the editor's deterministic helper for that work — Python where Python belongs, no LLM reasoning needed.

Always operates on final.md. Step 6 begins with the editor copying draft.md → final.md; every subsequent Step-6 read/write — including every invocation of this skill — targets final.md. draft.md is read-only from Step 6 onward. The --final <path> flag (and the final_path positional for scan) is deliberately named so a final draft.md mix-up surfaces immediately as a mismatched argument rather than silently mutating the working file.

Canonical Step 6 sequence (matches the editor + diagram-illustrator role specs):

1. scan — read final.md once, emit JSON inventory of every ASCII block + trailing ascii-note with line ranges, plus the per-block context bundle (slide_title, slide_content_prose, speaker_notes, section_title, section_goal, talk_thesis, optional presentation_language when --language is passed). After scan, no consumer should need to re-parse final.md for slide context.
2. inspect-intents (optional) — eyeball the scan as a 3-column table (slide_id | slide_title | intent) before authoring slugs. Pure read; no mutation.
3. Diagram-Illustrator authors a renders map (judgement-only) — {slide_id: {svg_basename, alt}} JSON keyed by slide_id, with the slug per the Output filename convention in ${CLAUDE_PLUGIN_ROOT}/agents/diagram-illustrator.md (derived from ascii-note → intent, slide title, etc.). Skip documentation-only blocks — annotate-renders zeros them out automatically.
4. annotate-renders — merge the renders map into the scan plan, emitting an annotated plan with render: {svg_basename, alt} set per block (and render: null for documentation-only / unmapped blocks). Reports missing slide_ids on stderr.
5. extract — write .ascii sidecars per the annotated plan. final.md is not modified at this stage. After this step every diagram lives on disk as a self-describing .ascii file (source + note).
6. prepare-render-args (parallel fan-out) — emit one <slide_id>.json args file per renderable block under --out-dir, each containing the full context bundle expected by talksmith:ascii-to-svg Mode B (ascii_file, output_path, slide/section/thesis context, presentation_language, optional repo_root). Subagents read their args file and dispatch one render each.
7. Per-sidecar render — invoke talksmith:ascii-to-svg once per .ascii file in Mode B (ascii_file: <path>). The skill reads ASCII source + note from the sidecar; the caller passes the rest of the context bundle straight from the args file. Easily parallelizable across subagents.
8. stamp-renders (mandatory — never skip) — stamp each rendered SVG with the SHA-256 digest of the ASCII it was drawn from. This is what makes step 6 (prepare-render-args) able to skip unchanged blocks on the next pass: it is the one and only signal consulted, so an unstamped SVG re-renders every time, forever. Run once after all renders complete, before cleanup. Blocks whose render failed have no SVG on disk and are skipped + reported on stderr — they correctly re-render next pass.
9. cleanup — rewrite final.md fences to image references, leaving the post-fence ascii-note HTML comments in place. Sidecars are not touched.

A single-pass apply subcommand exists for quick passes (does steps 5 + 9 together, skipping the per-sidecar render — useful when you've already rendered SVGs separately and just want to finish the cleanup). apply does not stamp — if you use it after rendering SVGs by hand, run stamp-renders yourself or the next pass re-renders everything.