dimagi-internal/ace / skills/training-quick-reference
training-quick-reference
UnverifiedInternal /ace:run step — Write the one-page FLW pocket card.
Training Quick Reference
Produce the FLW pocket card — single page, scannable, every word earns its place. Audience: an FLW mid-visit, glancing at a printed sheet for the right next step or a number they need to remember.
When to run
Phase 6 (qa-and-training), after app-screenshot-capture. Independent
of other training skills.
Inputs (read from Drive)
Pipeline-only: derives the card from a run's PDD. 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 | per-visit step list, daily caps, key safety rules, support contact + escalation triggers |
| Phase 3 | ACE/<opp>/runs/<run-id>/3-commcare/pdd-to-deliver-app_summary.md | exact required-field list (so the ref says what the form actually asks) |
Phase 4 (run_state.yaml) | connect.opportunity + connect.payment_units | max-per-day numbers |
Output
Single file: ACE/<opp>/runs/<run-id>/6-qa-and-training/training-quick-reference.md.
Format
A markdown document built to render to a single 8.5×11" sheet (or A4) when printed. Word budget: ~250 words total. If it's longer, it won't fit on one page; if it's a long checklist of vague guidance, it fails the "card" test.
# Quick Reference — <Opportunity Name>
Laminated pocket card. FLWs carry this in the field.
## Every delivery
1. <step 1, 5-8 words>
2. <step 2>
3. ...
N. **Submit**
## Limits today
- <X> deliveries per FLW
- <Y> deliveries per <unit>
## What good looks like
- <Layer-A signal 1, 5-10 words>
- <Layer-A signal 2>
- <Layer-A signal 3>
## When to stop / escalate
- <safety trigger>: leave, contact LLO
- <verification trigger>: complete partial, flag in notes
## Need help?
Call your LLO coordinator: <name from connect-setup/opportunity.md>
Phone: ______________ (the LLO fills this in at onboarding)
Format rules
- Word budget ~250. If you can't say it in 250 words, it doesn't belong on a pocket card.
- Numbered for delivery steps, bulleted otherwise. Numbers imply sequence; bullets imply "any one applies."
- Real numbers, not paraphrased. The
<X>and<Y>are quoted fromrun_state.yaml's payment-unit max counts, not summarized. - Imperative voice. "Submit." not "You should submit when ready."
- No screenshots. This is a printed card — graphics blow the
budget. Save those for the
flw-training-guide.
Process
-
Read inputs. Drive paths in the table above.
-
Read run_state.yaml for hard numbers.
connect.payment_units→ max-per-day numbers;connect.opportunity.max_visits_per_day→ total cap. -
Determine archetype. For
atomic-visit, "Every delivery" numbered list mirrors the PDD's per-visit flow. Forfocus-group, the section reframes as "Every session" with the session-stage list. Formulti-stage, two parallel lists or a single list with stage markers. Forlongitudinal-visits, one list per visit type with the visit trigger stated up front ("First visit" / "Follow-up, due N days after the last") — the FLW's question is which visit this is, not just what to do. Any archetype not named here falls back to theatomic-visitshape; never leave the card unwritten because the archetype was unrecognised (ace#1691). -
Draft the card. Stay under 250 words. Use imperative voice throughout.
-
Self-check before write. Verify:
- Total word count ≤ 280 (small overage tolerance for the section headers)
- Every PDD-declared per-visit step is in the "Every delivery" list
- Every "Layer-A signal" maps to an Evidence-Model rule in PDD
- Every escalation trigger from PDD § Escalation is referenced
- The "Need help?" block names a real person and a phone fill-in — no
openchatstudio.comhost,public_id, orembed_key, and no in-app control (grievance menu, "Report a problem") unless this run's evidence shows one exists — ace#2106 (see § Support channel below)
-
Write to
ACE/<opp>/runs/<run-id>/6-qa-and-training/training-quick-reference.mdas a NATIVE Google Doc viadrive_create_doc_from_markdown— NOTdrive_create_file, which uploads the body astext/plainso every##,**,|and---stays a literal character on the page. This document is read by a human (a field worker who will PRINT this card), and a partner opening it should see headings, bold and tables, not markdown source. The renderer round-trips: a properly formatted doc exports back to clean markdown viadrive_read_file(exportAs: 'text/markdown'), so nothing machine-readable is lost — whereas atext/plainupload exports ESCAPED (\---,run\_id). Same find-or-create semantics: a same-name file under the parent is overwritten IN PLACE, so the fileId — and any sharing already applied to it — survives. (dimagi-internal/ace#1338; sibling of the PDD fix, ace#1061.)Then persist the source markdown — the same string, written twice. Immediately after the render, write the EXACT bytes you just passed to
drive_create_doc_from_markdowntoACE/<opp>/runs/<run-id>/6-qa-and-training/training-quick-reference.source.mdviadrive_upload_binarywithmimeType: 'text/markdown'— the same atomskills/_training-template.mdprescribes. NOTdrive_create_doc_from_markdown, which renders the source copy into a Doc and destroys the very bytes this step exists to preserve; and NOTdrive_create_file, which does exactly the same thing while LOOKING like the safe choice.drive_create_filealways creates a Google Doc and has nomimeTypeto change that — the key used to be dropped by its schema, so this step produced a second rendered Doc and the DOC-FIDELITY check compared one Doc against another built by the same importer (ace#1991). It now refuses the key and names this call.drive_upload_binaryuses Drive's media-upload path, so the file lands astext/markdownanddrive_read_filereturns it verbatim.Why it is not optional: the renderer CONSUMES its input. Once the Doc exists the markdown you composed exists nowhere, and the
.mdin the published name is display text, not a file —drive_list_folderover a finished run returns every one of these asapplication/vnd.google-apps.documentwith no sibling markdown. That is what leavesrun-surface-audit'sDOC-FIDELITY-UNVERIFIED— the only check that compares what was PUBLISHED against what was WRITTEN, and the only one that could have caught a guide silently losing 44 screenshots and 224 words with every other check green (ace#1418) — permanently unresolvable, because its--doc-sourceremediation has nothing real to point at. One extra call turns a blocking gate from decorative into operable. (ace#1687 half 2; declaredsourcePersistedinlib/artifact-manifest.ts, enforced bytest/lib/source-persisted-artifacts.test.ts.) -
Self-evaluate (LLM-as-Judge). Four criteria:
- Word budget: ≤ 280 words
- Hard-number fidelity: caps + payment numbers match
run_state.yaml - Imperative voice: all delivery-step lines start with a verb
- Coverage: every per-visit step + every escalation trigger present
Verdict to
ACE/<opp>/runs/<run-id>/6-qa-and-training/training-quick-reference_verdict.yaml. -
Hand off. Print Drive URL + verdict summary.
-
Share it anyone-with-link. The pocket card is a deliverable a field worker opens from the run summary — a private Doc opens only for accounts explicitly shared on it, so a recipient following the link hits You need access. Nothing upstream catches this: the doc exists, has the right words, passes every content eval, and returns a 401 that a link checker reasonably reads as "auth-gated" (the correct verdict for a Connect/HQ/OCS login gate, the wrong one here).
drive_set_anyone_with_link(fileId: <docId>, role: 'commenter')role: 'commenter'rather thanreader— a partner reviewing a training deliverable should be able to leave feedback on it. Do this at creation, not as a cleanup step: on hh-poverty-targeting/20260722-1341 all six training links shipped private and were shared by hand afterwards. (ace#902; enforced bytest/lib/recipient-facing-artifacts.test.ts.)
MCP Tools Used
-
ace-gdrive:drive_set_anyone_with_link— share the deliverable (ace#902). -
ace-gdrive:drive_read_file,drive_create_doc_from_markdown(the card — human-facing prose, must render),drive_upload_binarywithmimeType: 'text/yaml'(the verdict YAML — machine-parsed, so it must be stored as REAL BYTES;drive_create_filemakes a Google Doc, whose export turns every\ninto\r\n\r\n\r\n, and it has no mimeType parameter — seeskills/_training-template.md § Machine-parsed artifacts must not be written as Google Docs)
Mode Behavior
- Auto: Run end-to-end.
- Review: Pause after step 5, show drafted card.
- Dry-run: Steps 1-5, skip write. Verdict with
dry_run: true.
Products
ACE/<opp>/runs/<run-id>/6-qa-and-training/training-quick-reference.mdACE/<opp>/runs/<run-id>/6-qa-and-training/training-quick-reference_verdict.yamlrun_state.yaml.phases.qa-and-training.products.training.docs.quick_reference—{file_id, title: "Quick reference card", web_view_link}typed handoff. Multi-writer block: apply via read-modify-write perskills/synthetic-data-generate/SKILL.md § Step 6. Seeagents/qa-and-training.md § Productsfor the full slot table.
Known limitations
- Markdown-rendered PDF is the assumption. v1 emits markdown that
renders cleanly in Google Docs (which the LLO can print). A future
iteration could emit
.pdfdirectly via a markdown-to-PDF helper. - Single-language. v1 produces the source-language card. Localized versions need a separate translate skill.
Why a separate skill
Independent rerun: re-running this skill regenerates only
training-quick-reference.md — re-tightening the word budget after a PDD edit
doesn't re-emit the LLO guide or FAQ.
Fourth of the per-artifact training skills.
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".
Support channel (shared contract)
Follow skills/_training-template.md § Support channel — one contract, all six skills (dimagi-internal/ace#1303): this artifact is worker-facing, so its
support line names a HUMAN (LLO coordinator / Partner Trainer) as a labelled
fill-in — never the openchatstudio.com host, the chatbot public_id, or the
embed_key, and never an in-app control (a grievance menu, a "Report a
problem" option) unless this run's own evidence shows one exists (ace#2106). Those are embed credentials, not a destination a CBF can open
(the embed path is a dead route; Connect has no per-opp widget field, CCC-301).
The one OCS link allowed is the bot's public start URL
(phases.ocs-setup.products.ocs_chatbot.public_url, /a/<team>/chatbots/<public_id>/start/),
which opens a live chat page (ace#3002) — in addition to the coordinator, never
instead; do not quote its greeting (blank topic, ace#2992).
Run checkWorkerFacingSupportChannel from lib/support-channel-guard.ts over
the composed markdown before writing and rewrite any finding.
Change Log
- v1 (0.10.84): Initial skill. Owns
training-quick-reference.mdonly. - 2026-09-06: The
.source.mdcompanion goes throughdrive_upload_binary, notdrive_create_file(ace#1991).drive_create_fileALWAYS creates a Google Doc; it has nomimeTypethat changes that, and the key a caller passed to try was dropped by the MCP schema. So this step produced a SECOND rendered Doc andrun-surface-audit'sDOC-FIDELITY-UNVERIFIEDcompared one Doc against another built by the same importer — passing structurally while unable to detect the content loss it exists to catch. Measured onpoverty-graduation/20260905-0924: 57,178 bytes sent, 58,470 read back, every#/**/>/pipe-table marker gone.skills/_training-template.mdhad prescribeddrive_upload_binarysince 2026-09-01; the six producers had not followed it.drive_create_filenow REFUSES amimeTypeand names thedrive_upload_binarycall in the refusal. Enforced:test/lib/source-persisted-artifacts.test.ts+test/mcp/gdrive/create-file-mimetype.test.ts. - 2026-09-07: Dropped the in-app GRM/grievance escalation route from the worker-facing support line (ace#2106). The shared contract in
skills/_training-template.mdasserted "the app's own in-app grievance route (the GRM menu), which the PDD already designates as the complaint channel" as settled fact. Both halves are false:templates/pdd-template.mdand both shipped example PDDs grep ZERO forgrievance|GRM|complaint(there is no PDD section that would designate one), and the released Deliver CCZ ofhh-poverty-targeting(HQce668763ad6c4b48ac5f4cd4502f3f8c,connect-ace-prod) greps zero acrosssuite.xml,modules-0/forms-0.xmland bothapp_strings.txt— its whole menu is one module and one form. A worker sent to a menu that is not there stops escalating rather than falling back. The support line is now the coordinator name + phone fill-in the LLO completes at onboarding; an in-app route may be named only when this run's own CCZ grep or ui-dump shows one. Enforced:test/skills/in-app-control-existence-claims.test.ts(corpus ratchet,.md+.ts) +unverified-in-app-controlinlib/support-channel-guard.ts.
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 |