dimagi-internal/ace / skills/training-deck-render
training-deck-render
UnverifiedRender a training deck spec into Google Slides using the ACE stencil template and return the Slides URL.
Training Deck Render
Reads training-deck-spec.yaml from Drive, validates it, resolves the
manifest, copies the template, and executes the Slides batchUpdate
pipeline. Single-pass (no speaker notes).
When to run
Phase 6 (qa-and-training), after training-deck-generate. The last
training material step before Phase 7.
Inputs
| Parameter | Used for | Resolver |
|---|---|---|
spec | the deck spec to render | explicit arg (a Drive file id); default: ACE/<opp>/runs/<run-id>/6-qa-and-training/training-deck-spec.yaml (from training-deck-generate) |
out_folder_id | where the deck and its verdict land (step 6's parentFolderId) | explicit arg; default: the run's 6-qa-and-training/ folder |
Outside a run (a refreshed deck for a live program), pass both. Step 10's
run_state.yaml handoff is then skipped; the caller records the deck link
(a program project's context doc).
Inputs (env)
ACE_TRAINING_DECK_TEMPLATE_ID— the 14-stencil Slides template.
Terminology
Every string this skill puts in front of a reader follows
skills/_terminology.md: Connect, never CommCare Connect, and
US spelling, always — program, enrollment, enroll, organization, behavior, center; never
programme, enrolment, organisation (owner, 2026-10-20: "everything should be US spelling",
ace#3232). Identifiers (case properties, slugs, ids, config keys) keep their spelling.
Process
-
Read
training-deck-spec.yamlfrom the run's6-qa-and-training/folder. -
Parse and validate via
parseTrainingSpec(yamlStr)— halt on validation error.
2b. Refuse a screen slide with no screen — HALT on any finding.
checkDeckScreenBacking(spec) (lib/training-deck-frames.ts) with no
pool: it reads the spec alone and fails a slide that promises a screen
(a Learn-module slide, a Step N: slide, "you will see / tap / open")
yet carries no image, and any mobile_flow (three or four phones side by
side render at ~54% of the slide height, which the render eval read as
unreadable). A finding means training-deck-generate step 9b
(scripts/bind-deck-frames.ts) did not run on this spec — run it, then
render the bound spec. Do not "fix" it here by deleting slides: the
binder is what knows which frames exist, including a fork source's.
`parseTrainingSpec` in step 2 already refuses a body taller than its
stencil frame (`bodyFit`); URLs render as link text, attached to the
label on the slide's body frame (the duplicate names it
`<slideId>_body`).
Phone geometry: a walkthrough phone is drawn ~91% of the slide height in
the right column (`WALKTHROUGH_IMAGE`, `lib/training-deck-stencil-geometry.ts`;
floor `MIN_PHONE_HEIGHT_FRAC` = 0.85), up from 82%. Image placement is
computed at render time, so this needs no template re-mint.
3. Resolve manifest via resolveManifest(spec.manifest).
-
Check image aliases. Verify all image aliases used in
walkthrough/mobile_flow/web_screen/mobile_zoom/two_columnslides are resolvable against the manifest. HALT if any are unresolvable — do not render a partial deck. -
Verify env. Confirm
ACE_TRAINING_DECK_TEMPLATE_IDis set. HALT if missing with a clear error. -
Copy template. Call
slides_copy_templatewith:templatePresentationId:ACE_TRAINING_DECK_TEMPLATE_IDtitle:"<opp-name> — Training Deck"parentFolderId:out_folder_id(default: the run's6-qa-and-training/folder ID)
-
Discover stencil objectIds. Call
slides_geton the copied deck. Verify all 14 stencils are present (match against theSTENCILSconstant). HALT if any missing.
7b. Scan the copied stencils for placeholder drift. HALT on any (dimagi-internal/ace#2429).
```bash
ACE_ROOT="${CLAUDE_PLUGIN_ROOT:-$(python3 -c "import json,os; d=json.load(open(os.path.expanduser('~/.claude/plugins/installed_plugins.json'))); print(d['plugins']['ace@ace'][0]['installPath'])")}"
node "$ACE_ROOT/node_modules/tsx/dist/cli.mjs" "$ACE_ROOT/scripts/check-stencil-token-drift.ts" \
--deck <copied presentationId>
```
Exit 0 = no drift. Exit 1 = drift, and the deck must not be
rendered from this template until it is reconciled.
The same run prints a `stencil geometry drift:` block (ace#2204). It
lists builder-owned boxes whose position, size, text colour, font size
or fill differs from `lib/training-deck-stencil-geometry.ts`. That block
is a WARN and never changes the exit code. Record it in the verdict, and
tell the operator that `--repair` (below) makes a merged stencil fix
actually reach decks. Until then every render ships the template's old
geometry with every check green, which is how ace#1305 re-shipped for
three weeks.
**This is the check step 9's `unmatchedReplacements` cannot make,
and the reason is worth knowing.** The template and
`STENCIL_PLACEHOLDERS` are two halves of one contract kept in
different places, and they drift in BOTH directions:
- a token the builder replaces that the stencil lacks — silently
**dropped**. `unmatchedReplacements` catches this (ace#2126).
- a token the stencil carries that the builder no longer replaces
— nothing targets it, so it survives onto the slide and the
reader sees a literal `{{TOKEN}}`. `unmatchedReplacements` is
**structurally blind** to this: it only reports tokens the
builder *tried* to replace.
The second is ace#2429. The duration badge left the exercise
layout's contract on 2026-09-09; the live template, minted
2026-09-07, kept it. `poverty-graduation/20260915-1518` rendered
281 requests, 281 replies, **0 unmatched** — and shipped a partner
a literal `{{DURATION}}` on all 13 of its exercise slides. The
generate-side `/\{\{[A-Z_]+\}\}/` sweep passes too, because it
scans the SPEC and the token lives in the TEMPLATE. This step is
the one place both halves are in hand.
**If it reports drift, repair the TEMPLATE, not the deck.** One
`replaceAllText` over the rendered deck fixes that artifact and
leaves the next render to reproduce it — that is exactly what
happened on the run that filed #2429. The repair is in place, so
the presentationId does not change and
`ACE_TRAINING_DECK_TEMPLATE_ID` needs no rotation:
```bash
node "$ACE_ROOT/node_modules/tsx/dist/cli.mjs" "$ACE_ROOT/scripts/check-stencil-token-drift.ts" \
--repair
```
(No `--template` argument: it defaults to
`ACE_TRAINING_DECK_TEMPLATE_ID` read from `<plugin-data>/.env` by
the script itself. Do **not** interpolate that variable in the
shell — ACE's env is loaded into MCP subprocesses, not the calling
shell, so `$ACE_TRAINING_DECK_TEMPLATE_ID` expands to EMPTY in a
Bash tool call and would send an empty id. ace#1147.)
It deletes every text-bearing shape on each drifted stencil page
and re-layers that stencil's boxes from
`lib/training-deck-stencil-geometry.ts` — the same thing the
bootstrap's step 4 does per page — then re-reads the template and
proves the drift is gone. Chrome (accent bar, right rule, corner
mark) is not text-bearing and is untouched, and the notes page is
not scanned or rewritten, so `{{NOTES}}` survives.
Note that **re-running `bootstrap-training-deck-template.ts` is a
no-op here**, despite being the obvious move: it dedupes on
`TEMPLATE_NAME` in the ACE root folder, so it finds the drifted
template and returns `Template already exists`. Forcing a real
re-mint means a new presentationId, which means a Canopy vault
update plus `/ace:setup --force-env` plus a full Claude restart
(every MCP server reads `.env` at module load). Repair in place
unless the stencil GEOMETRY changed, not just its tokens.
The comparison logic is `lib/stencil-token-drift.ts`
(`scanStencilTokenDrift`), unit-tested in
`test/lib/stencil-token-drift.test.ts` against both drift
directions plus the live template's real pre- and post-repair
content. The script is only the Slides round-trip around it.
8. Build requests. Call
buildSlidesRequestsV2(spec, { stencils, manifest }).
-
Execute. Call
slides_batch_update— single call with all requests.Read
unmatchedReplacementson the result — it is not decoration (ace#2126). The deck's text does not arrive throughslides_copy_template; step 6 copies the template BARE and every token is substituted here, by thereplaceAllTextrequestsbuildSlidesRequestsV2emits. A token no stencil carries is replaced zero times, the API returns 200, and no{{token}}survives in the rendered deck for any check to find — so the slide ships without the content and every checkpoint reads green. That is the same silent-drop that put a contractual Work Order in front of a partner using "the partner" ~30 times with no antecedent while its QA returned 14/14 pass.A non-empty
unmatchedReplacements(plus awarning) means those values were silently dropped from the rendered deck. It is a report, not a rollback — the deck exists and looks fine. Treat any entry as a halt, naming the unmatched tokens.Do not work around it by folding the value into a neighbouring token. That renders correctly once and teaches the next run nothing. A dropped token means the live template gdoc no longer carries the placeholder the builder targets, and the fix is to reconcile the template — step 7b's
--repair, which rebuilds the drifted stencil pages in place and keeps the presentationId. (Step 7b should have caught it first; an entry reaching HERE and not there means the token is on the notes page, which 7b does not scan.){{NOTES}}is the likeliest such hit: the bootstrap injects it into each stencil's notes page, so an unmatched{{NOTES}}means the live template predates that step, and THAT one does needscripts/bootstrap-training-deck-template.ts(after trashing or renaming the existing template — it dedupes onTEMPLATE_NAME). -
Write deck handoff to
run_state.yaml(only when a run is bound):phases: qa-and-training: products: training: deck: file_id: <presentationId> title: "<opp-name> — Training Deck" web_view_link: <url> slide_count: <N> rendered_at: <ISO timestamp>Multi-writer block (sibling slots are the five training doc skills'
docs.<key>entries) — apply via read-modify-write following the canonical pattern inskills/synthetic-data-generate/SKILL.md § Step 6so sibling sub-keys are preserved. Seeagents/qa-and-training.md § Productsfor the full slot table. -
Print deck URL for operator.
Pre-flight checks
Before rendering:
- All Drive fileIds in manifest must be shared
anyone-with-link. Usedrive_set_anyone_with_linkon each. (Slides image import won't work without this.) - Template must exist and be accessible by the SA.
Self-eval
Four criteria:
- Slide count: Rendered deck slide count matches total slides in spec. FAIL if mismatch.
- Image resolution: All images in the spec resolved successfully
(no
createImageerrors). FAIL if any failed. - API success:
slides_batch_updatecompleted without error. FAIL if error. - Visual coverage (dimagi-internal/ace#856): re-read
visual_coveragefrom the generate verdict, or recompute it viacomputeVisualCoverage(lib/training-deck-spec.ts). Record the ratio in this verdict. FAIL ifratio < 0.5with zero per-opp captures.
Criteria 2 and 4 are not the same check, and conflating them is what let
this skill score 9.5 on a hollow deck. Criterion 2 asks "did every image the
spec referenced resolve?" — which is vacuously satisfied when the spec
referenced almost no images, because generate had already downgraded the
unbacked slides to content layout. On
hh-poverty-targeting/20260702-1456 the 4 pool images resolved cleanly, so
criterion 2 passed, while 39 of 43 slides carried no substantive image.
Never record "visually spot-checked" as evidence for a passing score unless the sample was stratified. That verdict's spot-check looked at the cover plus the 4 image-bearing slides and never sampled the 39 empty ones — it sampled exactly the population that could not fail. If you sample, sample by stencil type and mandatorily include slides that should carry screenshots.
Verdict to
ACE/<opp>/runs/<run-id>/6-qa-and-training/training-deck-render_verdict.yaml
in the standard shape (see lib/verdict-schema.ts).
Post-render sweep: leftover decorative ellipse (pre-v6.1 templates)
A template minted before v6.1 carries a 6×6pt decorative ELLIPSE on the
walkthrough stencil (and mobile_zoom — same Dimagi source page),
cloned from the source slide and missed by the bootstrap strips. Fresh
renders from such a template inherit it as a stray blue dot on every
walkthrough-derived slide. If ACE_TRAINING_DECK_TEMPLATE_ID still
points at one, then after rendering: slides_get the deck, filter
pageElements with isDecorativeLeftover
(lib/training-deck-stencil-geometry.ts — ELLIPSE rendered ≤ 12pt in
both dimensions), and issue one slides_batch_update of deleteObject
requests for the matches. The in-place re-render script (below) runs
this sweep automatically when it rebuilds stencils, so re-rendered decks
self-clean.
v6.1 mints clean. The bootstrap now sweeps leftovers as a SECOND
pass over the elements that survive the strip
(decorativeLeftoverIds). Shown the raw element list it did not: the
predicate spares an ellipse whose slide also holds a LINE, and the only
LINE on the walkthrough page is a callout leader for a mockup the same
pass deletes — a doomed element vouching for the dot. The v6.0 mint
shipped mobile_zoom with the dot for exactly that reason.
Output
- Google Slides deck in the run's
6-qa-and-training/folder ACE/<opp>/runs/<run-id>/6-qa-and-training/training-deck-render_verdict.yamlper standard verdict shape- Handoff written to
run_state.yaml
Same-link re-render
Share the rendered deck anyone-with-link. The pre-flight share above is
for the IMAGES the Slides importer fetches — it does not share the deck. The
deck is what the partner actually opens from the run summary, so share it too,
once, right after slides_copy_template returns:
drive_set_anyone_with_link(fileId: <presentationId>, role: 'commenter')
commenter so a reviewer can leave feedback on a slide. (ace#902 — on
hh-poverty-targeting/20260722-1341 the deck shipped private alongside the five
guides and every link check read green.)
For a deck that has already been shared at a stable URL and needs regeneration (e.g. new screenshots after a capture unblock), do NOT copy the template again — that mints a new presentationId and breaks the shared link. Use the in-place re-render script instead (dimagi-internal/ace#864):
ACE_ROOT="${CLAUDE_PLUGIN_ROOT:-$(python3 -c "import json,os; d=json.load(open(os.path.expanduser('~/.claude/plugins/installed_plugins.json'))); print(d['plugins']['ace@ace'][0]['installPath'])")}"
node "$ACE_ROOT/node_modules/tsx/dist/cli.mjs" "$ACE_ROOT/scripts/rerender-training-deck-in-place.ts" \
--deck <presentationId> \
--spec <new-spec.yaml> \
--old-spec <spec.yaml that produced the CURRENT slides> \
[--key <gws-sa-key.json>]
--old-specis required: it must be the spec that rendered the deck's CURRENT slides — stored in the run's6-qa-and-training/folder as the deck-spec doc. The script derives each live slide's layout from it and HALTS if the live slide count differs (the deck was hand-edited; reconcile first).- Safety property: the old slides are deleted ONLY after the new render batch succeeds — a failed render leaves the shared deck intact.
- Stencil text-box geometry comes from
lib/training-deck-stencil-geometry.ts(single source, shared with the bootstrap script), so re-rendered stencils match the template.
Error handling
- If
ACE_TRAINING_DECK_TEMPLATE_IDnot set: emit verdictskippedwith reason. Don't FAIL. - If spec validation fails: emit verdict
failedwith Zod error details. - If
slides_batch_updatefails: emit verdictfailedwith API error.
MCP Tools Used
scripts/check-stencil-token-drift.ts(step 7b gate;--repairfor the operator-side template reconcile)ace-gdrive:drive_read_file(read the spec YAML)drive_set_anyone_with_link(pre-flight image sharing)slides_copy_template(copy the template into the opp folder)slides_get(discover stencil objectIds)slides_batch_update(render all slides in one call)
Mode Behavior
- Auto: Run end-to-end, write the deck, update state, return URL.
- Review: Pause after step 8 (requests built). Show request count + slide count, let operator inspect before executing. Resume on approval.
- Dry-run: Steps 1-8 only, skip the copy/batchUpdate calls. Write
a verdict with
dry_run: trueand a count of slides that would be created.
Products
- The Google Slides deck itself (in Drive)
run_state.yaml.phases.qa-and-training.products.training.deck—{file_id, title, web_view_link, slide_count, rendered_at}typed handoff (multi-writer block; siblingdocs.*slots written by the five training doc skills)ACE/<opp>/runs/<run-id>/6-qa-and-training/training-deck-render_verdict.yaml— standard verdict shape (seelib/verdict-schema.ts);passed:true if parse + batchUpdate succeeded
Change Log
- 2026-10-18:
## Inputsare parameters (spec,out_folder_id); step 10's run_state handoff runs only when a run is bound (#3148 batch 3). - v3 (2026-10-01): Step 2b — refuse a screen slide with no screen and any
mobile_flow(checkDeckScreenBacking); walkthrough phones drawn at ~91% of the slide height (was 82%); body URLs rendered as link text styled onto the slide's named body frame;parseTrainingSpecrefuses a body taller than its frame. From the render eval of spark-facilitator/20260926-1800 (4.66 / fail): ten screen slides with no screenshot, unreadable three-up phones, and slide 53's raw URLs printed over its title. - v2: Step 7b — post-copy stencil placeholder-drift scan, blocking.
Catches builder/template drift in both directions at the one point
where both halves are in hand (dimagi-internal/ace#2429). Logic in
lib/stencil-token-drift.ts;--repairreconciles the template in place, so no template id changes and no.envrotation. - v1: Initial skill. Replaces
training-deck-build. Readstraining-deck-spec.yaml(fromtraining-deck-generate) instead oftraining-deck-outline.md. Single-pass render viabuildSlidesRequestsV2against 14-stencil template. No speaker notes pass.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |