dimagi-internal/ace / skills/training-deck-generate
training-deck-generate
UnverifiedInternal /ace:run step — Write the training deck spec from PDD, apps, screenshots.
Training Deck Generate
Produce a training-deck-spec.yaml — the structured spec that
training-deck-render parses into a real Google Slides deck. Replaces
the legacy training-deck-outline skill, which emitted a markdown
outline; the spec format is machine-parseable and template-driven.
When to run
Phase 6 (qa-and-training), after app-screenshot-capture completes.
Upstream of training-deck-render.
Inputs (read from Drive)
Pipeline-only: derives the deck spec from a run's PDD, app summaries and screenshots. For a live program's materials, run it in a run on that program.
| Source | Artifact | Used for |
|---|---|---|
| Phase 1 | ACE/<opp>/runs/<run-id>/1-design/idea-to-pdd.md | Opportunity description, requirements, targets |
| Phase 3 | ACE/<opp>/runs/<run-id>/3-commcare/pdd-to-learn-app_summary.md | Learn app structure, form names, module names |
| Phase 3 | ACE/<opp>/runs/<run-id>/3-commcare/pdd-to-deliver-app_summary.md | Deliver app structure, form names, module names |
| Common assets | ACE/_common/connect-screenshots/<v>/manifest.yaml | Platform setup screenshots |
Phase 6 Step 1 (app-screenshot-capture) | ACE/<opp>/runs/<run-id>/6-qa-and-training/app-screenshot-capture_manifest.yaml | Per-opp app screenshots |
Phase 3 previews (app-screenshot-capture § Step 4.9) | ACE/<opp>/runs/<run-id>/3-commcare/previews/apps-{learn,deliver}/_previews.yaml | The same frames, indexed per app (output previews contract v1, lib/output-previews.ts) |
Fork source (when run_state.yaml has forked_from) | the two rows above, in ACE/<opp>/runs/<forked_from>/ | Frames a fork inherited but did not copy (ace-web#758) — step 9b reads them |
| Current run | run_state.yaml | Opportunity metadata, payment info, verification rules |
| Plugin repo | templates/training-deck/connect-training-atomic/ | Skeleton + generation prompt |
Output
Single file: ACE/<opp>/runs/<run-id>/6-qa-and-training/training-deck-spec.yaml.
Process
-
Read archetype from PDD. Parse the
Archetype:line from PDD frontmatter. Default toatomic-visitif absent. -
Select template bundle. Map archetype to template directory under
templates/training-deck/:atomic-visit→connect-training-atomicfocus-group→connect-training-fgd(future)multi-stage→connect-training-multistage(future)
If the archetype's template doesn't exist yet, fall back to
connect-training-atomicand emit a WARN in the verdict. -
Read template bundle. Three files from the selected template directory:
template.yaml— template metadata (name, archetype, version)spec.template.yaml— the spec skeleton with{{placeholder}}tokensgenerate.prompt.md— the generation prompt with layout selection rules and content guidance
-
Read all inputs. Drive paths in the table above:
- PDD (
idea-to-pdd.md) - Learn app summary (
pdd-to-learn-app_summary.md) - Deliver app summary (
pdd-to-deliver-app_summary.md) run_state.yaml(forconnect.payment_units,connect.verification_flags, opportunity metadata)
- PDD (
-
Read screenshot manifests (C1 — per-opp wiring). Build a merged manifest map
{ alias -> {file_id, drive_url} }:-
Common-pool aliases from
ACE/_common/connect-screenshots/<v>/manifest.yaml(e.g.,connect-signin-splash,claim-opp-detail,commcare-welcome). These cover the Connect platform onboarding flow and are shared across all opportunities.Preflight the common pool first (ace#3060):
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/doctor-common-screenshot-pool.ts" --format=jsonExit 0 means the pinned APK's pool is usable. Exit 1 means it is missing or incomplete; the JSON
summarynames which. Exit 2 means the check could not run, and that is not a pass. On exit 1 or 2:- add
severity: FAIL[COMMON-POOL-MISSING] <summary>to the verdict'sauto_surfaced, and cap the verdict atwarn(neverpass); - do not read another version's pool. Older screens captioned as the
current app are the false-promise class
lib/screenshot-pool-distinctness.tsexists to stop. Load only the aliases the probe lists aslive, and let every other common alias fall through to the template/placeholder path; - do not halt. The opp-specific content is still worth shipping. The fix is
common-screenshot-capture, which runs outside the run.
- add
-
Per-opp aliases from
ACE/<opp>/runs/<run-id>/6-qa-and-training/app-screenshot-capture_manifest.yaml. Format: each entry hasalias:,journey_id:,step_name:,drive_path:,file_id:. Alias convention:<recipe-base>-<step-name>e.g.journey-learn-mod-1-step-3,journey-deliver-form-photo-step-1. -
Template assets from
templates/training-deck/_common/assets/assets.yamlintomanifest.template(ace#873). These are committed deck artwork, NOT captures — see that file for the per-asset contract and the verified reason each one is uncapturable. An asset still markedstatus: neededhas no PNG yet: emit the step caption-only and surface[TEMPLATE-ASSET-MISSING] <alias>. That is a template-bundle defect, never an opp capture failure, and it does not feed the coverage gate below.
Cross-pool alias collisions:
opp>common>template— most specific wins (resolveManifest,lib/training-deck-spec.ts).If the per-opp manifest is missing or empty: first check the fork source — a forked run's frames live in its
forked_fromrun, and step 9b reads them there. Otherwise the upstreamapp-screenshot-captureskill in Phase 6 step 1 didn't produce screenshots (likely due to a smoke-recipe failure). Step 9b then merges the affected screen slides (it never ships one empty), surface[WARN] no per-opp screenshots —your-opportunitywalkthroughs degraded to content-only slidesin the verdict'sauto_surfacedlist, and then apply the visual-coverage gate in step 5b — which this case will fail.Partial per-app screenshots. The screenshot manifest may contain
journey-learn/screenshots but nojourney-deliver/(or vice versa) when one capture leg failed/was-deferred (seeapp-screenshot-captureper-app legs). Use whichever app's screenshots are present; for the missing app, step 9b merges the screen slides it cannot back, as when the whole bundle is absent. One missing leg is a WARN that carries its coverage number; both legs missing is a gate failure. -
Step 5b: Visual-coverage gate (dimagi-internal/ace#856)
A training deck whose walkthrough spine has no screens IS the placeholder. CLAUDE.md's "fail loud — don't ship placeholders, don't soft-fail" applies at the deliverable level, not just the screenshot step. Text-only prose artifacts (FAQ, quick-reference) degrade honestly; a deck cannot, because showing the screens is the entire reason it exists.
- Compute
expectedOppVisualSlides— the number of opp-specific visual slides this deck should carry. It is the Deliver form count + Learn module count from the app summaries, i.e. the same number step 11's C2 check already derives. Do NOT count emitted image slots. - Call
computeVisualCoverage(spec, { expectedOppVisualSlides })fromlib/training-deck-spec.ts. - Record
visual_coverage: { expected, filled, ratio, pool_filled, template_filled }in the verdict.
| Condition | Outcome |
|---|---|
ratio >= 0.5 | proceed |
ratio < 0.5, one app leg present | [WARN] quoting the ratio; proceed |
ratio < 0.5 with no per-opp captures at all, or both legs missing | verdict: fail, severity: BLOCKER. Do not proceed to render. |
On a BLOCKER the phase writes status: blocked (see agents/qa-and-training.md)
and the run reports the blocker instead of offering the deck as a deliverable.
Why the denominator is not the emitted slot count. This step downgrades an
unbacked walkthrough slide to content layout — and a downgraded slide is
schematically indistinguishable from one that was always meant to be text-only,
so it silently leaves the numerator and the denominator. On
hh-poverty-targeting/20260702-1456 that arithmetic gave 4 images / 4 slots =
100% while true opp coverage was 0 of 6; the deck shipped 39 empty slides
of 43 and the render self-eval scored it 9.5. Pinned by the regression test in
test/lib/training-deck-spec.test.ts ("a hollow deck reads 0, not 100%").
Why only manifest.opp counts. Several pool aliases are permanently
uncapturable — the PersonalID completion half (now template assets, ace#873)
and the three Play-Store install screens, which need a Google-signed-in AVD. A
gate that counted them would fire on 100% of runs, on every opp, forever.
Scoping to manifest.opp excludes them by construction, needs no allowlist,
and measures the right thing: the pool is not this run's work product, and a
screenshot-blocked run cannot lose it.
Note on verdict vocabulary. blocked is a legal phase status
(lib/run-state-validator.ts) but NOT a legal skill verdict
(lib/verdict-schema.ts). At skill level use fail + severity: BLOCKER.
Screenshot-claim consistency (dimagi-internal/ace#866 + #867). Four hard rules when mapping manifest images onto slides:
-
Never place the same image
file_idon two slides/panels whose captions claim different moments. If the manifest offers only duplicates for two claimed moments, use the image ONCE and rewrite the other panel/slide ascontentlayout (no image) or drop it. -
Steps marked
duplicate_of:in the capture manifest are NOT distinct panels. Aduplicate_ofstep is the same moment as its canonical step — never give it its own slide/panel or caption it as a separate moment. -
Never caption a screenshot with an assertion the pixels visibly contradict. The shipped example: "there is no gallery option, on purpose" over a widget showing CHOOSE IMAGE (hh-poverty-targeting/20260702-1456 deck slide 27, dimagi-internal/ace#867). If the app contradicts the PDD, surface it as a defect in the verdict's
auto_surfacedlist instead of asserting the design intent. -
Captions must describe the surface actually shown — a CommCare screen must not be captioned as a Connect screen (or vice versa).
-
A slide that ASSERTS what a screen shows needs a frame someone OPENED. After writing the spec, run
verify_caption_backingagainst it (seeskills/_training-template.md) — it reads the PUBLISHED artifact and fails on any cited frame nobody described, so there is no list to curate. A non-emptyfindingsis a BLOCKER: fix the caption or drop the image.On a deck spec the gate counts what the SLIDES place, not the resolution map (ace#2238).
manifest.oppis an INVENTORY — every alias the deck could place. Keeping the full pool in it is correct and costs nothing: the citations are the slides'@aliasrefs resolved through the map, so a finding always names a frame some slide actually carries. Do NOT trimmanifest.oppto silence findings, and do NOT back-fillshows:onto frames nobody cites — both were the only ways to satisfy this gate before the fix, and onspark-facilitator/20260907-1120it reported 66no-showsover a deck that places 10 images. As a cheap pre-write check you can also callframesCitedWithoutShows(manifest, citedSteps)(lib/capture-manifest.ts): it returns every step this deck cites that carries noshows:— the one-line record of what is actually on the frame, written byapp-screenshot-capture§ Step 5.6. Where a slide body or caption makes a claim, the frame must carry ashows:and the claim must agree with it. Otherwise usecontentlayout and keep the claim in prose.The rules above are about not WRITING a false caption; this one is about not being ABLE to. On turmeric-market-study/20260828-1108 this deck captioned a
walkthroughslide "Your score appears as soon as you submit the quiz" overjourney-learn-posttest-result— which is the lesson menu with a "1 form sent to server!" toast. No score on it, and no frame of the score existed at all, because the recipe submits straight past the pass/fail label. Every structural gate passed: schema valid, 100% of file_ids resolving, zero duplicate citations, visual coverage 1.00. Those all answer "which file is this?"; none answers "what is in the picture?", which is the only thing a caption can contradict. That slide is nowcontentlayout — honestly text-only rather than dishonestly illustrated.If the frame you need does not exist, say so and fix the recipe. Do not promote a nearby frame into the role.
-
Read common modules. Load shared module fragments from
templates/training-deck/_common/:platform-setup.yaml— Connect sign-in, claim, install slidesfacilitation.yaml— ice-breaker pool, group exercise patternsresources.yaml— help contacts, support links template
-
Fill the spec skeleton. Following the generation prompt instructions, produce a complete spec with 6 modules:
-
welcomemodule: cover slide (title, subtitle, date placeholder), agenda slide, ice-breaker slide from facilitation pool -
platform-setupmodule: include_common/platform-setup.yamlverbatim — Connect sign-in, claim opportunity, install app steps with common-pool screenshot refs -
your-opportunitymodule — structured around the 4 Connect lifecycle pillars (Learn / Deliver / Verify / Pay) withsectiondivider slides between them. Order:- Opportunity overview (1-2 content slides)
sectiondivider titled"Learn"- One
contentslide per Learn module (Learn-app preview), titled with the app's module name verbatim — same rule as thepracticemodule below, and for the same reason (ace#1829). A body list of the suite's sections is numbered by the app's own labels, never by list position. Slide 14 ofhh-poverty-targeting/20260828-0702printed4. What makes a visit payabledirectly beside the suite-root screenshot labelling that same item "Module 3" — the contradiction sat on one slide, next to its own evidence. - "Who you will visit" (1 content slide)
sectiondivider titled"Deliver"- C2 REQUIRED: one
walkthroughslide per Deliver form. Title"Form N: <display-name>", body cites 2-3 actual field labels, image is the per-opp@aliasif the manifest has one (do NOT invent screenshot aliases). A 6-form Deliver app produces 6 walkthrough slides; do NOT collapse. Whether a slide ends up with a frame is decided by step 9b, not by eye — see there. sectiondivider titled"Verify"- Quality and verification (1-2 content slides)
sectiondivider titled"Pay"- Payment details (stats slide preferred). Sibling
stats[].bigvalues share their unit. If any column carries a unit prefix or suffix (USD 3,25%,10/day), a numeric sibling carries it too:USD 0, not0. A bare numeral beside unit-carrying siblings reads as a footnote, not a peer, and the stencil cannot know that0meansUSD 0(ace#2205,poverty-graduation/20260905-1345slide 6).lintDeckFormattingreports it as astatsUnitswarning, and step 9b'sbind-deck-frames.tsprints it underformatting warnings. Fix every one before writing. - Safety and ethics (1 content slide, cross-pillar)
-
practicemodule (C2 — REQUIRED per-opp content): emit oneexerciseslide per Learn module (enumerated from the Learn app summary). Title"Complete: <module-label>"where<module-label>is the Learn app's module name verbatim — body names the key concept + assessment threshold. Plus 1 form-practice slide + 1 role-play slide.NEVER synthesise an ordinal (ace#1829). The app's module names already carry their own numbers, so a number you derive from a slide's position in this list can only ever disagree with them. On
hh-poverty-targeting/20260828-0702this section counted the unnumberedPre-Assessmenttile as Module 1 and shifted every real module up by one, while the reference section four modules earlier printed the app's names correctly — two incompatible numberings in one deck:app : Pre-Assessment | Module 1 - Administering… | Module 2 - Consent… | Module 3 - What makes a visit payable | … deck : Module 1: Pre-Assessment | Module 2: Administering… | Module 3: Consent… | Module 4: What Makes a Visit Payable | …These are TIMED hands-on instructions ("Complete Learn Module 4: What Makes a Visit Payable", 20 min). A first-day FLW follows the slide, opens the app, finds no Module 4 by that name — it is Module 3 — and stalls inside a timed block. This is the population
content_substanceexists to protect.The authoritative labels are available two ways on every run and they agree:
3-commcare/pdd-to-learn-app_summary.md, and the capture manifest'slearn-tap-module-after-<name>.pngstep names. Copy from those; do not count. -
evaluationmodule: checklist slide from PDD acceptance criteria, timeline-to-go-live slide, "what happens next" framing -
resourcesmodule: include_common/resources.yaml, replace{{LLO_CONTACT}}with the coordinator's name whenrun_state.yamlalready carries one, otherwise with "named by your implementing organisation at onboarding" (no LLO contact exists before Phase 9 — a value like "your LLO manager" renders as "Your coordinator: your LLO manager", ace#2658), add OCS widget URL fromocs-setup_widget-handoff.mdif available
-
-
Resolve
ref:module references viaresolveModuleRefs()fromlib/training-deck-spec.ts. Any module declared withref: _common/<name>(e.g._common/platform-setup,_common/resources) gets inlined by loadingtemplates/training-deck/_common/<name>.yamland substituting{{KEY}}tokens from the module'soverrides:map (recursively across all string leaves). Pass the sameloadModuleadapter used by the orchestrator (fs-based when running from a repo checkout, Drive-based when running from a deployed skill).Why this step is non-optional. The render skill validates the spec against
TrainingDeckSpecSchema, which requires every module to have inlineslides[]. A spec that still containsref:modules fails parse and the render emits zero slides for those modules. Pre-2026-05-25 specs that shipped withref: _common/platform-setup(the malaria-rdt run) lost their platform-setup slides for exactly this reason — fixed by always inlining refs at generate time. -
Validate the expanded spec — BEFORE writing it to Drive. Run
parseTrainingSpec(yamlStr)(which appliesTrainingDeckSpecSchema) against the serialized spec. This is a hard gate, not a review step: if it throws, fix the spec and re-validate — do NOT write the artifact. Every@aliasimage ref must also resolve against the merged manifest from step 5; flag any unresolvable refs as a hard fail.Validating here rather than at render time is the whole point. An unvalidated spec still writes successfully and the step still marks itself
done, so the shape violation only surfaces later whentraining-deck-rendercallsparseTrainingSpecand hard-fails — at which point Phase 6 has no deck andverify_phase_productsfails the boundary fence, becauseproducts.training.deckis a REQUIRED handoff key the ace-web summary renders.Three shapes that have actually shipped broken (dimagi-internal/ace#1049, spark-facilitator/20260728-1338) — the skeleton's placeholders sit in scalar position, so filling them literally produces the wrong type:
manifest.common/manifest.oppare maps (alias -> URL). Emit{}when a pool resolved to nothing. A scalar fails.- agenda
itemsis a list of{label}objects. A list of bare strings fails. Do not add adurationkey — training decks state no timings (see below), and Zod strips the key, so adding one changes nothing except your token count. voice.estimated_duration_minutesmust be omitted by the two TRAINING variants. It survives as an optional field only forconnect-pitch-partnership, which is a prospect-facing pitch rather than training and whose duration is a video length ACE genuinely controls. Where it IS emitted it is a number; a quoted value fails.
No time durations anywhere in a training deck (operator decision 2026-09-09) — not on the agenda, not on an exercise badge, not in a speaker note, not as a session total. The LLO sets the schedule: they know the room, the group size, the literacy mix, and how long the questions will run. Every duration ACE used to print was invented, and printing it made it look agreed.
This bans training-schedule timings, not program parameters. How long an FGD session must run, how many participants a group holds, that the attestation is due within 24 hours and the session doc within 72 — those come from the PDD, they are what the FLW is paid to comply with, and they stay on the slides. Withholding them would not be deference; it would be withholding the job description. Enforced:
test/lib/training-deck-durations.test.ts.
9b. Bind a real frame to every screen slide — HARD GATE (lib/training-deck-frames.ts). Write the validated spec to a local file, then:
```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/bind-deck-frames.ts" \
--spec <local spec.yaml> --run-folder <Drive id of ACE/<opp>/runs/<run-id>> \
--out <local bound-spec.yaml> --report <local bind-report.json>
```
It is read-only against Drive. It walks the run's `forked_from` chain,
pools every citable frame (capture manifest, `3-commcare/previews/*`,
`manifest.common` / `manifest.template`, and the same in each fork
source), measures each frame's pixels (`lib/frame-pixels.ts`: a loading
screen is near-empty, a soft keyboard covers the screen), and then, per
slide:
- a slide that promises a screen — a Learn-module slide, a `Step N:`
slide, or a body saying the trainee will *see* / *tap* / *open*
something — gets the best frame OF THAT SCREEN, or is no longer a
screen slide. Learn-module slides take only that module's own frames,
never its form list ("finished" landings show where a lesson is, not
what it teaches);
- frameless Learn-module slides merge into ONE "The Other Learn Sections"
slide over the Learn home grid (labels verbatim, each module's text in
the notes); any other frameless screen slide is folded into its
neighbour's speaker notes. **Never write a screen slide with no
screen**;
- a loading-screen frame is replaced; a keyboard frame is replaced only
by one that matches the slide at least as well;
- `mobile_flow` becomes one walkthrough per phone (three phones side by
side render at ~54% of the slide height — unreadable projected).
Exit 0 = the gate (`checkDeckScreenBacking`) passes; 1 = it does not
(the report names each slide). **Write the BOUND spec in step 10**, and
record the report's `actions` in the verdict.
**Then close the `needs_shows` loop.** A frame the binder newly placed
may carry no `shows:`, and `verify_caption_backing` fails a cited opp frame
nobody described. Open each frame `report.needs_shows` names and write
its `shows:` line into the run's shows addendum,
`6-qa-and-training/app-screenshot-capture_shows-addendum.yaml`
(`shows: [{step, file_id, shows}]`). Do not write it into the capture
manifest, which is the producer's artifact. Then pass the addendum to
`verify_caption_backing` as `showsAddendumFileIds` (ace#2902). If the
frame does NOT show what its slide says, re-run with
`--reject <step>` — the slide then merges rather than shipping a wrong
picture.
**Then materialise the crops — no ACE scaffolding on a trainee's screen
(ace#2660).** Phase 4's opportunity is named `"<run_id> · <name>"` by
contract (`connect-opp-setup`; `mcp/connect/opportunity-name.ts`), so every
Connect frame that renders its title shows trainees a run id the partner's
opportunity will not have. The binder (`lib/opp-title-frames.ts`) handles
each slide whose frame shows it, in this order:
1. a clean **sibling of the same screen** — a variant capture of the same
recipe step (`claim-opp-detail` / `claim-opp-detail-scrolled`) that
matches the slide at least as well — replaces it (`opp-title-sibling`);
2. otherwise the slide cites **`@<alias>--below-title`**, a crop of the
same frame starting at the gap under the title block, found from the
frame's pixels (`belowTitleCropTop`). Cropping is the ONLY pixel
change: kept rows are copied byte-for-byte, nothing is painted or
re-lettered, no frame is invented. The script writes each PNG to
`--crops-dir` (default `<dir of --out>/crops/`) and lists it in
`report.crops[]` (`alias`, `from_alias`, `top`, `slides`, `local_file`);
3. a frame where the title appears more than once — an opportunity LIST
(`claim-opp-list*`, `claim-opp-new-tile`, `connect-resume-opp-tile`) or
the landed card + certificate (`connect-resume-opp-landed`) — has no
honest crop. It stays, and the slide is named in
`report.opp_title_visible`: rebind it by hand to a frame without the
title (re-run with `--reject <step>`), or rewrite the slide.
For each `report.crops[]` entry: upload `local_file` with
`drive_upload_binary` (`mimeType: "image/png"`, `shareAnyoneWithLink: true`,
parent = the frame's run `6-qa-and-training/screenshots/`), set
`manifest.opp[<alias>]` in the bound spec to
`https://drive.google.com/uc?export=view&id=<new id>`, and append a capture
manifest row (`step: <alias>`, `file_id`, `cropped_from: <from_alias>`,
`crop_top_px: <top>`) whose `shows:` you write after opening the crop — the
alias is already in `needs_shows`. Until it is uploaded the alias resolves
nowhere, and the renderer halts on it rather than shipping the raw frame.
This row is the ONE manifest write a consumer makes, and it is not the
`needs_shows` rule above bent: a crop is a new Drive file the producer
never saw, and `verify_caption_backing` reads the shows addendum only
against frames the manifest already has, so a crop recorded only in the
addendum comes back `unknown-id` (ace#3240; *enforced:*
`test/lib/caption-backing.test.ts`). `skills/_training-template.md` states
the same carve-out.
*Enforced:* `test/lib/opp-title-frames.test.ts` (sibling preferred, crop
otherwise, lists never cropped, crop is byte-identical below the cut, on
the committed real frame).
*Why it is a script and not an instruction* (spark-facilitator/
20260926-1800, render eval 4.66 / fail): ten slides that walk the trainee
through a screen shipped with none. Five had a frame in the manifest
(`commcare-welcome` for "you see its welcome screen", `deliver-sync-*` for
"Tap Sync with Server"); the rest had no frame of their screen and shipped
empty anyway, because the old fallback — "use `content` layout" — makes a
downgraded slide schematically a text slide, invisible to the coverage
gate and to the render self-eval. *Enforced:* `test/lib/training-deck-frames.test.ts`
over the real spec, manifest, run_states and frame stats.
**A FORK's frames live in its source run.** A fork copies each earlier
phase's artifacts but not their `screenshots/` subtree (ace-web#758), so
the capture manifest it inherited names frames in `<forked_from>/6-qa-
and-training/screenshots/`. They resolve by `file_id`, which survives the
copy; the lineage walk covers a fork whose manifest is missing or lacks a
step, and only `forked_from` (top-level, or `lineage.forked_from`) is
followed — never `supersedes`, which is a different build.
**URLs in a body are written as links: `[label](url)`.** The renderer
shows the label and attaches the URL (a bare URL gets a short label
automatically). `parseTrainingSpec` also refuses a body taller than its
stencil frame (`bodyFit`) — slide 53 of the same deck printed four raw
URLs over its own title.
10. Write the fully-expanded training-deck-spec.yaml to
ACE/<opp>/runs/<run-id>/6-qa-and-training/training-deck-spec.yaml
via drive_create_file. Overwrite if it already exists. The
written spec MUST be schema-clean for TrainingDeckSpecSchema
(no ref modules remain).
**Compose the YAML to a LOCAL FILE first, then pass `localFilePath` — do
not emit the spec inline (ace#1918).** Write it to an absolute scratch
path, then call
`drive_create_file({name, localFilePath, parentFolderId})`; the server
reads the bytes off disk, so the write costs ~zero context regardless of
size. A fully-expanded spec was measured at 55,719 chars in the 2026-09-02
corpus (four runs re-sampled 2026-09-06 came in at 22k–27k, so the size is
deck-dependent, not a constant) — and the local file is worth having
anyway: it is what you re-read when `TrainingDeckSpecSchema` rejects a
leaf, instead of re-emitting the whole spec to fix one line.
11. Self-evaluate. Five criteria — the first four are programmatic checks (run BEFORE the LLM judge), the fifth is the soft slide-count warning:
- **Module coverage:** all 6 modules present (`welcome`,
`platform-setup`, `your-opportunity`, `practice`, `evaluation`,
`resources`). FAIL if any missing.
- **Content concreteness:** strict `/{{[A-Z_]+}}/` regex sweep
across all string leaves of the spec — any match is an unfilled
token leak (the `{{STAT1_LABEL}}` class of bug from the
malaria-rdt deck). FAIL if any found.
- **Image ref validity:** all `@alias` refs in walkthrough and
mobile_flow slides resolve against the merged manifest. FAIL if
any unresolvable.
- **Speaker notes presence:** every slide has a non-empty `notes:`
field. FAIL if any slide is missing notes. The deck must be
facilitatable (talking points, timing cues, transitions,
knowledge-check answers). See generation prompt § Tone and
Language Guidelines for what notes should contain.
- **Per-opp Learn/Deliver mapping (C2):** count Learn modules and
Deliver forms in the app summaries. Verify the spec contains:
- In `your-opportunity` module: ≥ `<deliver-form-count>` slides
with `id` matching `/form-/` or title beginning `"Form "`
- In `practice` module: ≥ `<learn-module-count>` slides with
`id` matching `/guided-learn|module-/` or title beginning
`"Complete Learn Module "`
FAIL if undercounted by more than 1 in either dimension. WARN if
exactly equal to N-1 (acceptable to collapse a single-form case).
Catches the failure mode where the generator emits one
"Module 1" slide regardless of the opp's actual Learn structure.
- **Module-label fidelity (C2 — HARD GATE, ace#1829):** every
module label the deck shows a worker must match the deployed
Learn app. Run it; do not eyeball it:
```ts
import { checkDeckModuleLabels, formatDeckLabelReport }
from '../../lib/deck-module-labels';
const report = checkDeckModuleLabels(allSlides, learnModuleLabels);
```
`learnModuleLabels` is the Learn app's module list, **in app
order, verbatim, including unnumbered entries** like
`Pre-Assessment` — their presence is exactly what caused the
off-by-one, so dropping them from the input hides the defect from
the check. Source it from
`3-commcare/pdd-to-learn-app_summary.md`, cross-checked against
the capture manifest's `learn-tap-module-after-<name>.png` step
names.
**FAIL on any finding**, and fix by lifting the app's label rather
than by renumbering to taste. The three shapes it catches:
`module-number-mismatch` (the deck's number for a module differs
from the app's — including an ordinal list item with no "Module"
keyword, the slide-14 shape), `module-number-not-in-app` (the deck
sends a worker to a module that does not exist), and
`module-name-not-in-app` (the deck names a module the app does not
ship). Record `formatDeckLabelReport(...)` in the verdict either
way.
Note this is the check the SLIDE-COUNT check above cannot be:
counting slides confirms the practice section has one entry per
module, and the shipped deck passed that while every one of those
entries carried the wrong number. A count never reads a label.
- **4-pillar section dividers:** `your-opportunity` module contains
exactly 4 `section`-layout slides with titles `"Learn"`,
`"Deliver"`, `"Verify"`, `"Pay"` (in that order, single-word
titles per v5.5 — was `"Learn — ..."` etc but those wrap on
the section stencil). FAIL if any pillar header is missing
or out of order. Catches the failure mode where the generator
emits a flat sequence of content slides without the lifecycle
structure.
- **Slide count:** total slides in 25-50 range. WARN if outside.
Smoke opps (1 Learn module + 1 Deliver form) naturally land at
the 25-30 floor; do NOT pad. Large opps (5+ modules + 6+ forms)
land 40-50.
Write a verdict YAML to
`ACE/<opp>/runs/<run-id>/6-qa-and-training/training-deck-generate_verdict.yaml`
in the standard shape (see `lib/verdict-schema.ts`). `passed: true`
only if the first four criteria pass (slide count is WARN-only).
12. Hand off. Print the spec's Drive URL + the verdict summary.
Phase 6 orchestrator dispatches training-deck-render next.
Archetypes
atomic-visit(default): Standard 6-module deck. Module 3 (your-opportunity) focuses on the single-visit delivery workflow — one slide per Deliver form section.focus-group: Module 3 restructured around FGD facilitation — session prep, running the FGD, attestation form, gdoc writing. Uses templateconnect-training-fgd(future).multi-stage: Per-stage sub-modules within Module 3. Each stage gets its own slides; follow-up stages treat the FLW as a returning user. Uses templateconnect-training-multistage(future).
MCP Tools Used
ace-gdrive:drive_read_file,drive_create_file,drive_list_folder
No live Slides API or AVD — this skill is pure spec generation. The
Slides side is training-deck-render's job.
Mode Behavior
- Auto: Run end-to-end. Write spec, write verdict.
- Review: Pause after step 8 (validation), present the generated spec, resume on approval.
- Dry-run: Steps 1-8 in memory, skip
drive_create_file. Verdict written withdry_run: true.
Products
ACE/<opp>/runs/<run-id>/6-qa-and-training/training-deck-spec.yamlACE/<opp>/runs/<run-id>/6-qa-and-training/training-deck-generate_verdict.yamlrun_state.yaml.phases.qa-and-training.steps.training-deck-generate— step record withartifact: 6-qa-and-training/training-deck-spec.yaml(+ file_id). Do NOT write aproducts.training.docs.deck_specslot —lib/phase-products-schema.tsenumerates onlyllo_guide/flw_guide/quick_reference/faq/onboarding_emailunderproducts.training.docs, and the only deck product slot isproducts.training.deck, written bytraining-deck-renderafter the Slides render (jjackson/ace#748; drift class jjackson/ace#705). The spec is an intermediate artifact tracked via the step record, not a typed product handoff. Seeagents/qa-and-training.md § Productsfor the full slot table.
Downstream
training-deck-render reads training-deck-spec.yaml to produce
Google Slides. The spec is the single source of truth for the deck
content — render never invents content, it only lays out what the spec
declares.
Why this replaces training-deck-outline
The legacy training-deck-outline emitted a markdown outline with
inline drive:<fileId> refs and ## Slide: markers. That format was
loosely structured: parseDeckOutline was brittle, image refs were
resolved during generation (not validated against a manifest), and the
outline mixed content decisions with layout hints.
The spec format separates concerns:
- Content (what to say, which images) lives in the spec.
- Layout (slide dimensions, font sizes, positioning) lives in the render skill.
- Template (module structure, common modules) lives in the template bundle.
This makes independent iteration on each concern possible without cross-contamination.
Payment figures and payment channel (shared contract)
Follow skills/_training-template.md § Payment figures and payment channel — one contract, all six skills (dimagi-internal/ace#2683, #2684). A rate, fee, budget
or date the PDD marks [PROPOSED] is printed as proposed, with who sets the
final figure — the payment unit's configured amount is named only as what the
app shows for now. The payment channel is described in the template's
canonical wording (Connect accrues the earned total; the organisation sends the
payment and records it in Connect), never as "Connect pays automatically" and
never as "off-platform".
Screenshot citations (shared contract)
Follow skills/_training-template.md § Screenshot citations — canonical frames only (dimagi-internal/ace#1304): select captures via canonicalCaptures from
lib/capture-manifest.ts, and run findDuplicateCitations over the steps this
artifact cites before writing. A duplicate_of capture is byte-identical to
its canonical step — the same moment, never a second one.
Checking that every file_id resolves does not cover this. That is
existence; this is distinctness. Two producers asserted the former, self-scored
image_hygiene near 10, and still captioned alias frames as distinct states.
The self-eval criterion must assert duplicate handling explicitly.
Change Log
- 2026-10-16: Sibling stat values share their unit (ace#2205).
USD 3 / USD 3 / 0rendered the bare0as a footnote. There is now an authoring rule at the payment stats slide, andlintDeckFormattingraises astatsUnitswarning, whichbind-deck-frames.tssurfaces asformatting_warnings. Enforced:test/lib/training-deck-formatting.test.ts. - 2026-10-05: No dogfood run id on a trainee's screen (ace#2660, step 9b). spark-facilitator/20261004-1706's deck showed "20261004-1706 · Spark Facilitator — …" on slides 8 and 9 because Phase 6 captures against the Phase 4 opportunity, whose name carries the run id by contract. The binder now prefers a title-free sibling of the same screen, else binds a below-the-title crop computed from the frame's pixels (crop only), else reports the slide in
opp_title_visible. Run live read-only against 20261004-1706: both slides got crops,opp_title_visibleempty, gate PASS; theclaim-oppcrop matches the hand-made workaround. Enforced:test/lib/opp-title-frames.test.ts. - 2026-10-01: Every screen slide is bound to a real frame, or merged — never shipped empty (step 9b). The render eval failed spark-facilitator/20260926-1800 at 4.66: ten walkthrough / app-screen slides carried no screenshot (five had a frame in the manifest; five had none of their screen and shipped empty anyway), slides 10/17/22/28 showed a loading screen or a one-tile form list, slides 6/32 a keyboard, and slide 53's raw URLs overflowed onto its title. Step 9b runs
scripts/bind-deck-frames.ts(lib/training-deck-frames.ts + lib/frame-pixels.ts): pools frames from the capture manifest, the Phase 3 previews indexes and the fork source alongforked_from; measures each frame's pixels; binds by the slide's own words within its part of the app; merges frameless Learn modules into one slide over the Learn home grid and folds other frameless screen slides into a neighbour's notes; expandsmobile_flow.checkDeckScreenBackingis the gate. URLs in bodies are written[label](url)(resources template updated) and render as link text;parseTrainingSpecrefuses a body taller than its frame. On the real spec the gate goes from 11 findings to 0. Enforced:test/lib/training-deck-frames.test.ts,test/lib/frame-pixels.test.ts,test/lib/training-deck-body-fit.test.ts. - 2026-09-08:
verify_caption_backingcounts the slides' citations, notmanifest.opp's inventory (dimagi-internal/ace#2238). Step 5 builds the resolution map from the whole capture pool and step 5 then makes the caption gate a BLOCKER — and the gate extracted every Drive fileId in the published artifact, which for a deck spec includes the map. Onspark-facilitator/20260907-1120that read 91 citations over a deck that places 10 images and reported 66no-shows+ 12duplicate-cited, every one naming a frame no slide cites. The two instructions were mutually unsatisfiable for any deck that does not place every captured frame, i.e. for every deck. The fix is inlib/caption-backing.ts, not here: for a document that parses as a deck spec, the citations are the slides' image refs resolved throughmanifest.*, and everything else in the spec is still read the way a rendered document is read. Trimming the map is no longer needed (and would break nothing but honesty about what was available). Enforced:test/lib/caption-backing.test.ts § a deck spec cites what its SLIDES place, with negative controls proving an undescribed, aliased or unknown frame a slide really does place still fails. - 2026-09-06: Step 10 composes the spec to a LOCAL FILE and writes it with
localFilePath(dimagi-internal/ace#1918). A fully-expanded spec was measured at 55,719 chars in the 2026-09-02 Drive corpus; emitting it inline costs ~1 output token per 4 characters, and having it on disk is also what makes aTrainingDeckSpecSchemarejection cheap to fix (edit one leaf, re-push the file) instead of a full re-emission. Follows theidea-to-pddsteps 6/6b template (ace#1780). Enforced:test/skills/large-artifact-localfilepath.test.ts. - 2026-09-02: Module labels are lifted from the Learn app, never renumbered (ace#1829). The deck numbered the Learn suite TWO incompatible ways at once: slides 16-19 printed the app's names correctly while slides 34-39 renumbered from list position, counting the unnumbered
Pre-Assessmenttile as Module 1 and shifting every real module up by one. Slide 14 carried the contradiction beside its own evidence — an ordinal list item4. What makes a visit payablenext to the suite-root screenshot labelling it "Module 3". Slides 34-39 are TIMED hands-on blocks, so a first-day FLW follows "Complete Learn Module 4: What Makes a Visit Payable", opens the app, finds Module 3 under that name and stalls. The step-11 slide-COUNT check could never catch it: counting confirms one practice slide per module, and the shipped deck passed that with every one of those slides carrying a wrong number — a count never reads a label. Three changes: the practice title template drops its synthesisedNfor the app's label verbatim; theyour-opportunityLearn-preview rule says the same thing explicitly (it was only accidentally right, having no template at all); and step 11 gains a HARD GATE runninglib/deck-module-labels.ts, whose input must include the UNNUMBERED app entries because their presence is the whole cause. Enforced:test/lib/deck-module-labels.test.ts(negative control: a position-counting detector — the bug's own logic — fails 9 of 13, inverting both controls) +test/skills/training-deck-module-numbering.test.ts(all 6 red against the pre-fix skill text). - v1: Initial skill. Replaces
training-deck-outline. Producestraining-deck-spec.yamlvia template bundle + generation prompt. Archetype-aware withatomic-visitas the only shipped template. - 2026-07-13: Screenshot-claim consistency rules in step 5
(dimagi-internal/ace#866 + #867) — no duplicate
file_idacross slides claiming different moments,duplicate_ofsteps are not distinct panels, captions must not assert what the pixels contradict, captions must describe the surface actually shown.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |