Skip to content

dimagi-internal/ace / skills/training-deck-generate

training-deck-generate

Unverified

Internal /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.

SourceArtifactUsed for
Phase 1ACE/<opp>/runs/<run-id>/1-design/idea-to-pdd.mdOpportunity description, requirements, targets
Phase 3ACE/<opp>/runs/<run-id>/3-commcare/pdd-to-learn-app_summary.mdLearn app structure, form names, module names
Phase 3ACE/<opp>/runs/<run-id>/3-commcare/pdd-to-deliver-app_summary.mdDeliver app structure, form names, module names
Common assetsACE/_common/connect-screenshots/<v>/manifest.yamlPlatform setup screenshots
Phase 6 Step 1 (app-screenshot-capture)ACE/<opp>/runs/<run-id>/6-qa-and-training/app-screenshot-capture_manifest.yamlPer-opp app screenshots
Phase 3 previews (app-screenshot-capture § Step 4.9)ACE/<opp>/runs/<run-id>/3-commcare/previews/apps-{learn,deliver}/_previews.yamlThe 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 runrun_state.yamlOpportunity metadata, payment info, verification rules
Plugin repotemplates/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

  1. Read archetype from PDD. Parse the Archetype: line from PDD frontmatter. Default to atomic-visit if absent.

  2. Select template bundle. Map archetype to template directory under templates/training-deck/:

    • atomic-visit → connect-training-atomic
    • focus-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-atomic and emit a WARN in the verdict.

  3. 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}} tokens
    • generate.prompt.md — the generation prompt with layout selection rules and content guidance
  4. 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 (for connect.payment_units, connect.verification_flags, opportunity metadata)
  5. 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=json
      

      Exit 0 means the pinned APK's pool is usable. Exit 1 means it is missing or incomplete; the JSON summary names 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's auto_surfaced, and cap the verdict at warn (never pass);
      • do not read another version's pool. Older screens captioned as the current app are the false-promise class lib/screenshot-pool-distinctness.ts exists to stop. Load only the aliases the probe lists as live, 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.
    • Per-opp aliases from ACE/<opp>/runs/<run-id>/6-qa-and-training/app-screenshot-capture_manifest.yaml. Format: each entry has alias:, 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.yaml into manifest.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 marked status: needed has 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_from run, and step 9b reads them there. Otherwise the upstream app-screenshot-capture skill 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-opportunity walkthroughs degraded to content-only slides in the verdict's auto_surfaced list, 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 no journey-deliver/ (or vice versa) when one capture leg failed/was-deferred (see app-screenshot-capture per-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.

  1. 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.
  2. Call computeVisualCoverage(spec, { expectedOppVisualSlides }) from lib/training-deck-spec.ts.
  3. Record visual_coverage: { expected, filled, ratio, pool_filled, template_filled } in the verdict.
ConditionOutcome
ratio >= 0.5proceed
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 missingverdict: 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_id on 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 as content layout (no image) or drop it.

  • Steps marked duplicate_of: in the capture manifest are NOT distinct panels. A duplicate_of step 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_surfaced list 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_backing against it (see skills/_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-empty findings is 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.opp is an INVENTORY — every alias the deck could place. Keeping the full pool in it is correct and costs nothing: the citations are the slides' @alias refs resolved through the map, so a finding always names a frame some slide actually carries. Do NOT trim manifest.opp to silence findings, and do NOT back-fill shows: onto frames nobody cites — both were the only ways to satisfy this gate before the fix, and on spark-facilitator/20260907-1120 it reported 66 no-shows over a deck that places 10 images. As a cheap pre-write check you can also call framesCitedWithoutShows(manifest, citedSteps) (lib/capture-manifest.ts): it returns every step this deck cites that carries no shows: — the one-line record of what is actually on the frame, written by app-screenshot-capture § Step 5.6. Where a slide body or caption makes a claim, the frame must carry a shows: and the claim must agree with it. Otherwise use content layout 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 walkthrough slide "Your score appears as soon as you submit the quiz" over journey-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 now content layout — 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.

  1. Read common modules. Load shared module fragments from templates/training-deck/_common/:

    • platform-setup.yaml — Connect sign-in, claim, install slides
    • facilitation.yaml — ice-breaker pool, group exercise patterns
    • resources.yaml — help contacts, support links template
  2. Fill the spec skeleton. Following the generation prompt instructions, produce a complete spec with 6 modules:

    • welcome module: cover slide (title, subtitle, date placeholder), agenda slide, ice-breaker slide from facilitation pool

    • platform-setup module: include _common/platform-setup.yaml verbatim — Connect sign-in, claim opportunity, install app steps with common-pool screenshot refs

    • your-opportunity module — structured around the 4 Connect lifecycle pillars (Learn / Deliver / Verify / Pay) with section divider slides between them. Order:

      1. Opportunity overview (1-2 content slides)
      2. section divider titled "Learn"
      3. One content slide per Learn module (Learn-app preview), titled with the app's module name verbatim — same rule as the practice module 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 of hh-poverty-targeting/20260828-0702 printed 4. What makes a visit payable directly beside the suite-root screenshot labelling that same item "Module 3" — the contradiction sat on one slide, next to its own evidence.
      4. "Who you will visit" (1 content slide)
      5. section divider titled "Deliver"
      6. C2 REQUIRED: one walkthrough slide per Deliver form. Title "Form N: <display-name>", body cites 2-3 actual field labels, image is the per-opp @alias if 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.
      7. section divider titled "Verify"
      8. Quality and verification (1-2 content slides)
      9. section divider titled "Pay"
      10. Payment details (stats slide preferred). Sibling stats[].big values 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, not 0. A bare numeral beside unit-carrying siblings reads as a footnote, not a peer, and the stencil cannot know that 0 means USD 0 (ace#2205, poverty-graduation/20260905-1345 slide 6). lintDeckFormatting reports it as a statsUnits warning, and step 9b's bind-deck-frames.ts prints it under formatting warnings. Fix every one before writing.
      11. Safety and ethics (1 content slide, cross-pillar)
    • practice module (C2 — REQUIRED per-opp content): emit one exercise slide 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-0702 this section counted the unnumbered Pre-Assessment tile 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_substance exists 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's learn-tap-module-after-<name>.png step names. Copy from those; do not count.

    • evaluation module: checklist slide from PDD acceptance criteria, timeline-to-go-live slide, "what happens next" framing

    • resources module: include _common/resources.yaml, replace {{LLO_CONTACT}} with the coordinator's name when run_state.yaml already 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 from ocs-setup_widget-handoff.md if available

  3. Resolve ref: module references via resolveModuleRefs() from lib/training-deck-spec.ts. Any module declared with ref: _common/<name> (e.g. _common/platform-setup, _common/resources) gets inlined by loading templates/training-deck/_common/<name>.yaml and substituting {{KEY}} tokens from the module's overrides: map (recursively across all string leaves). Pass the same loadModule adapter 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 inline slides[]. A spec that still contains ref: modules fails parse and the render emits zero slides for those modules. Pre-2026-05-25 specs that shipped with ref: _common/platform-setup (the malaria-rdt run) lost their platform-setup slides for exactly this reason — fixed by always inlining refs at generate time.

  4. Validate the expanded spec — BEFORE writing it to Drive. Run parseTrainingSpec(yamlStr) (which applies TrainingDeckSpecSchema) 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 @alias image 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 when training-deck-render calls parseTrainingSpec and hard-fails — at which point Phase 6 has no deck and verify_phase_products fails the boundary fence, because products.training.deck is 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.opp are maps (alias -> URL). Emit {} when a pool resolved to nothing. A scalar fails.
    • agenda items is a list of {label} objects. A list of bare strings fails. Do not add a duration key — training decks state no timings (see below), and Zod strips the key, so adding one changes nothing except your token count.
    • voice.estimated_duration_minutes must be omitted by the two TRAINING variants. It survives as an optional field only for connect-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 template connect-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 template connect-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 with dry_run: true.

Products

  • ACE/<opp>/runs/<run-id>/6-qa-and-training/training-deck-spec.yaml
  • ACE/<opp>/runs/<run-id>/6-qa-and-training/training-deck-generate_verdict.yaml
  • run_state.yaml.phases.qa-and-training.steps.training-deck-generate — step record with artifact: 6-qa-and-training/training-deck-spec.yaml (+ file_id). Do NOT write a products.training.docs.deck_spec slot — lib/phase-products-schema.ts enumerates only llo_guide/flw_guide/quick_reference/faq/onboarding_email under products.training.docs, and the only deck product slot is products.training.deck, written by training-deck-render after 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. See agents/qa-and-training.md § Products for 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 / 0 rendered the bare 0 as a footnote. There is now an authoring rule at the payment stats slide, and lintDeckFormatting raises a statsUnits warning, which bind-deck-frames.ts surfaces as formatting_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_visible empty, gate PASS; the claim-opp crop 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 along forked_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; expands mobile_flow. checkDeckScreenBacking is the gate. URLs in bodies are written [label](url) (resources template updated) and render as link text; parseTrainingSpec refuses 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_backing counts the slides' citations, not manifest.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. On spark-facilitator/20260907-1120 that read 91 citations over a deck that places 10 images and reported 66 no-shows + 12 duplicate-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 in lib/caption-backing.ts, not here: for a document that parses as a deck spec, the citations are the slides' image refs resolved through manifest.*, 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 a TrainingDeckSpecSchema rejection cheap to fix (edit one leaf, re-push the file) instead of a full re-emission. Follows the idea-to-pdd steps 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-Assessment tile as Module 1 and shifting every real module up by one. Slide 14 carried the contradiction beside its own evidence — an ordinal list item 4. What makes a visit payable next 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 synthesised N for the app's label verbatim; the your-opportunity Learn-preview rule says the same thing explicitly (it was only accidentally right, having no template at all); and step 11 gains a HARD GATE running lib/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. Produces training-deck-spec.yaml via template bundle + generation prompt. Archetype-aware with atomic-visit as the only shipped template.
  • 2026-07-13: Screenshot-claim consistency rules in step 5 (dimagi-internal/ace#866 + #867) — no duplicate file_id across slides claiming different moments, duplicate_of steps are not distinct panels, captions must not assert what the pixels contradict, captions must describe the surface actually shown.
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: 196kUpdated Claude CodeCodexVerifiedInstall
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: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
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: 192kUpdated Claude CodeCodexVerifiedInstall