dimagi-internal/ace / skills/demo-narrative
demo-narrative
VerifiedWrite a funder-tuned DDD narrative (why-brief + spec) whose scenes render a live labs dashboard. Needs a demo dashboard URL. Also run by /ace:demo.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 66.4 KB |
SKILL.md
View on GitHub---
name: demo-narrative
description: >
Write a funder-tuned DDD narrative (why-brief + spec) whose scenes render a live labs dashboard.
Needs a demo dashboard URL. Also run by /ace:demo.
disable-model-invocation: false
---
# Demo Narrative
The **story** half of the ACE demo workflow. Given a demo brief and the
`realized.json` map from `demo-data-setup`, it authors the two canopy DDD
artifacts — a `WhyBrief` and a `UnifiedSpec` — whose scenes render the live labs
dashboard (`${par_url}`) and whose `setup` block reproduces the dataset. The
canopy DDD loop then renders / judges / (optionally) videos / uploads.
ACE does **not** own the narrative schema, the renderer, the judges, or the
video path — canopy does. This skill authors against canopy's published models
(`scripts/narrative/models.py`, JSON Schemas under
`scripts/narrative/schema/json/`) and gates on canopy's validator. Do not
paraphrase the schema here — read the model / schema and validate.
## Inputs
| Source | Artifact | Used for |
|---|---|---|
| Operator | `--brief <text or drive-path>` | the demo story (same brief `demo-data-setup` used) |
| Operator | `style` — `explainer` (**default**) or `recorded` | the video shape. **Explainer is the default and stays the default.** Author `recorded` ONLY when it was explicitly requested: `/ace:demo --style recorded`, a `style: recorded` line in the dispatch, or a brief that asks in so many words for a recorded walkthrough / several short separate cuts with no music. Anything less explicit is explainer (operator decision, 2026-10-16, ace#2789). See Step 3r |
| `demo-data-setup` | `<demo-run>/7-synthetic/realized.json` | the flat `${var}` map — `primary_par_url`, one `<key>_par_url` per dashboard, `<name>_url` drills — the scenes render |
| `demo-data-setup` | `run_state…products.synthetic.source` | provider, labs opp id, deliver units, and `dashboards[]` (key/template/role/`interactive`) — one narrative arc per dashboard; `interactive: true` marks the only dashboard whose controls are live |
| `demo-data-setup` | `run_state…products.synthetic.source.record_counts` + `.data_shape` | **the dataset's cardinality** — `record_counts` verbatim from the generator, and the three axes a demonstration can need (`rows` / `periods` / `groups`). Step 2b checks each demonstration against it BEFORE scenes are written (ace#1670). Absent on a pre-2026-08-26 run — then read `record_counts` from `<demo-run>/7-synthetic/demo-data-setup.md` and the week span from `demo-data-setup_manifest.yaml`, and say in the summary that you re-derived them |
| Discovery | canopy runtime (resolved from the installed canopy plugin via its `scripts/canopy-runtime.sh` — see Step 4) | `uv run python -m scripts.ddd.validate` (see `docs/superpowers/plans/2026-07-20-plan-a-task1-findings.md`) |
## Products
- `<demo-run>/7-synthetic/why_brief.yaml` — the `WhyBrief`
- `<demo-run>/7-synthetic/<demo-slug>.yaml` — the `UnifiedSpec`
- `run_state.yaml…products.synthetic.narrative` — `{ why_brief_ref, unified_spec_ref, validated: true }`
- `run_state.yaml…steps.demo-narrative.status: done`
## Process
1. **Read the schema, not this doc.** Open canopy `scripts/narrative/models.py`
(or the JSON Schemas) for the exact `WhyBrief`, `UnifiedSpec`, `Scene`,
`Feature`, `Persona`, `SetupBlock` fields + required/optional split. Mirror
the working reference `docs/walkthroughs/program-admin-report.yaml` in a
local connect-labs checkout if present (e.g. `~/emdash-projects/connect-labs`
or `~/emdash/repositories/connect-labs`) — a labs-dashboard walkthrough with
a `setup` block and `url: ${par_url}` scenes, the closest template. Optional:
skip it if no checkout exists.
2. **Author `why_brief.yaml`.** `narrative_slug`, `problem` (the funder's
nutrition-program pain in one paragraph), `spine[]` (each `id`, `claim`,
`rationale`, `evidence[]`), `gaps[]`. Demo honesty rule: a demo asserts
aspirational value, so claims the built dashboard doesn't literally prove get
`evidence.kind: assumed` and a matching `Gap` of type `DECISION` or
`CAPABILITY`. Every grounded spine item needs ≥1 non-`assumed` evidence;
every `Gap.claim_ref` must resolve to a spine `id`.
2b. **Check the DATA'S SHAPE before you pick a demonstration (ace#1670).**
A demonstration is only observable if the data has enough of the thing it
acts on, and the axis it needs is not always the axis the dataset is big on.
Read `source.data_shape` (and `source.record_counts` behind it), then hold
every demonstration you are considering against these minimums — from
`MIN_CARDINALITY` + `DETECTION_MIN_ROWS` in `lib/ddd-scene-actions.ts`, where
each is derived with its reasoning:
| Demonstration | Axis it needs | Minimum | Why |
|---|---|---|---|
| filter / search / sort | `rows` | **12** | the after-state must still read as a list (≥3 rows) AND the drop must register at a glance (~8 rows) |
| trend | `periods` | **4** | a baseline, the turn the narration names, and a period after it — below that the claim is asserted over the plot, not read off it |
| comparison | `groups` | **3** | with two groups one is always above the other, so the ordering carries no information about whether being behind is unusual |
| detection / flagging | `rows` | **24** | a detection claims *unaided scanning is not viable*; a cohort that fits in one screenful (12 rows, the filter floor's own anchor) is scannable by definition, so the comparison has to span two — ace#1841 |
Filter and detection share the `rows` axis and do **not** share a floor — a
12-row cohort is enough to filter and not enough to detect. The check reads
each scene's `title`, action targets, `show`, `concept_claim` and
`features[]`, so it sees a demonstration you name only in prose (ace#1841);
it also names the axis that DOES have room, which is usually the fix.
**When the data cannot carry the demonstration there are exactly two
branches, and both are taken HERE, not after a render:** pick a different
demonstration for that dashboard (one the shape supports — a single-value
callout instead of a trend, a drill-in instead of a filter), or go back to
`demo-data-setup` and regenerate with a larger cohort. A third answer is
legitimate only if it is written down: if the surface actually enumerates a
different population than `data_shape.rows` names (a visit table has
`user_visits` rows, not `user_data` rows), say which and use that count.
`bednet-check-2-visit/20260825-1310` is why this step exists. It authored a
filter demonstration over a **five-worker** cohort — filtering 5 rows removes
at most 4, so the before-frame and after-frame are the same screenshot minus
a line. `checkSceneActions` passed it, `scripts.ddd.validate` passed it, and
the concept judge caught it after a full render; the loop ended
`stopped_not_converged` at concept 3.0 four iterations later, on a defect
decidable from two numbers before the first frame was recorded.
2c. **ace-run provider: author the cascade scene ladder (ace#2510).** When
`realized.json` carries `programme_par_url` the run built the semantic-layer
cascade (`demo-data-setup` § Process (ace-run) C0–C7), and the story is the
DRILL, told from two seats. Read `7-synthetic/cascade-story.yaml` — its four
signals are what the scenes find, and its `visible_as` sentences are the
narration's raw material (never claim a figure the saved run does not show;
`demo-data-setup-qa` check 21 printed the observed values). **The saved run is
necessary, not sufficient: the figure must also be on the scene's END FRAME,
not only in a hover tooltip** — step 3b's on-screen rule (ace#2727). Name
workers and communities by the story plan's display roster
(`workers[].display_name`, `entities[].name`; `realized.json`
`*_worker_name`), never by username or hashed id — and only where the page
renders that name.
| # | persona | url / action | what the viewer sees |
|---|---|---|---|
| 1 | programme manager | `${programme_par_url}` | headline tiles against the PDD's targets; which one is off target |
| 2 | programme manager | click `inLabsReportFrame('css:tr:has-text("${lagging_partner_label}")')` | the lagging partner's tiles and its facilitators ranked |
| 3 | programme manager | `${worker_review_url}` for a lagging-partner facilitator | one worker against same-month / similar-caseload peers |
| 4 | programme manager | click the community row | that case's visit history — the not-held weeks as gaps |
| 5 | programme manager | the data-quality worker's review (`${data_quality_worker}`) | the PDD's review flag concentrated on one worker — the record to check, not a verdict |
| 6 | network manager of the lagging partner | `${<partner>_opp_report_par_url}` → click `Benchmarks` | the same figures handed down ("From the programme report"), then the partner ranked against peers it cannot name |
Rules: scene 1 names the programme's own targets, not generic "KPIs"; the
partner, worker and case are the story's carriers, never a random row; the
standout worker may replace scene 5 when the PDD's evidence model has no
review flag. The finale's `Benchmarks` click is the closing action (a
`click` counts for `checkArcLadder`). The reports are otherwise read-only —
do not invent a state change they do not offer; if the payoff you choose is a
pure read, declare `finale_is_read: {reason}` per step 3's ladder rule.
Opportunities render as "Opportunity <id>" (labs residual) — narrate the
partner, not the opportunity id.
**A report target enters the sandbox frame only when that report HAS one
(ace#2885).** Labs can draw a report's body in an iframe at
`/labs/sandbox/render/` (dimagi-internal/connect-labs#2449 / #2466 / #2470),
leaving the top page only the breadcrumb and "Opportunities: N selected".
canopy's recorder resolves a target on the TOP page, so on a framed report
`css:tr:has-text(…)` and `role:tab:Benchmarks` miss (on
`smallholder-seasonal/20261012-1549` scene 1's `wait_for` failed the first
render). But labs does not frame every report. On 2026-10-16
(`smallholder-seasonal/20261015-1402`) the indicator programme report, the
worker review and the opp reports drew on the top page with no iframe, so a
framed target misses there instead. The URL cannot tell the two apart, and no
one selector covers both: Playwright refuses a frame locator inside
`locator.or()`. **So observe first:** run `scripts/capture-scene-text.ts`
(step 3b) over the draft spec. Its `scene_<N>_page_text.json` records every
child frame. Then, per surface: if the capture saw the sandbox frame, pass
each target through `inLabsReportFrame` (`lib/labs-report-frame.ts`), which
prefixes `iframe[src*="/labs/sandbox/render/"] >> internal:control=enter-frame >> `
and turns `role:` / `text:` / `testid:` / `aria:` into the engine canopy's
`get_by_*` would use (`role:tab:Benchmarks` becomes
`css:<frame> >> internal:role=tab[name="Benchmarks"s]`). If it logged "labs
surface with NO sandbox frame", write the target plainly, or undo a framed
one with `outOfLabsReportFrame`. Do not write the prefix by hand: the helper
holds it in one place. Step 3b's `narration-claims.ts --screen-text` checks
every report target against the shape the capture saw, in both directions
(`labs-report-target-outside-frame` / `labs-report-target-in-absent-frame`),
with the rewritten target in the finding. `checkSceneActions` runs the same
check when you pass it `{ framing: framingFromCaptures(captures) }`; without
an observation it stays silent rather than guess.
3. **Author the `UnifiedSpec`** (`<demo-slug>.yaml`):
- `base_url: https://labs.connect.dimagi.com`; no `auth` block (labs cookies
seeded out-of-band, per `hal:synthetic-walkthrough`).
- `personas[]` — first persona is the network manager; each `name, role,
color, intro, org`. **One arc per dashboard in `source.dashboards[]`** — e.g.
a program manager on `program_admin` (multi-LLO oversight) and the same or a
second persona on `child_recovery` (a named child's MUAC recovering
red→yellow→green). The narrative moves from the overview dashboard to the
recovery dashboard, not one screen.
- `why_brief` — embed / reference the Step 2 brief.
- `setup: { command: <the per-render reset> && <regenerate-realized.json command>,
outputs: "realized.json", rerun: per_render }`.
The `command` must (re)produce `realized.json` for the render session. For
denovo Plan A this re-invokes `demo-data-setup` in ensure mode; **confirm
idempotency live in the joint test** (if `demo-data-setup` regenerates
rather than reuses, either add an ensure mode or set the command to emit the
already-written `realized.json`).
**`rerun: per_render`, and the command must RESET the interactive run —
not merely re-emit the map (ace#2297).** This said `rerun: once` until
2026-09-08, and `once` skips the command whenever the outputs file already
exists — which is every render after the first. Recording a demo MUTATES
the world: the coaching task the payoff scene creates is still on the labs
run for the next take, the button is gone, and a `must_succeed` click
aborts the whole render. canopy's own `SetupBlock` docstring names this
case ("demos that MUTATE state during recording … film the wrong UI on
every re-render"). Re-emitting `realized.json` does not fix it either —
the data is unchanged; it is the RUN STATE that is dirty. So prefix the
command with `source.render_reset.command` verbatim from the handoff
(`demo-data-setup` step 4b), which clears the run's declared
`state_keys`. Whenever `source.render_reset.required` is true, both halves
are mandatory: `demo-data-setup-qa` check 18 fails a spec that carries one
without the other.
**Refuse a PINNED reset command — halt, do not copy (ace#2351).** Before
copying `source.render_reset.command` into `setup.command`, check it for
`/plugins/cache/ace/ace/` or a `/Users/<name>/` (`/home/<name>/`) segment.
Either means the handoff snapshotted ONE machine's versioned plugin cache:
the cache keeps every prior version, so the path keeps resolving — to
STALE code — after every `/ace:update`, and from another account it names
a home that is not that account's install. On `spark-facilitator/
20260909-2242` the copied command pinned 0.13.1413 (pre-ace#2325) and
would have re-introduced `run-not-found` on every render; only a hand
rewrite caught it. Halt with: *"`source.render_reset.command` is pinned to
`<the offending segment>`; re-run `demo-data-setup` step 4b to register
the self-resolving form (`bash "$(python3 -c "…installed_plugins.json…")
/bin/ace-reset-labs-run" …`)"* — never silently re-resolve it here, because
the handoff is the record other consumers (forks, `demo-data-setup-qa`)
read. `classifyPinnedResetCommand()` in `lib/labs-run-state-reset.ts` is
the exact test check 18 applies.
- **Put the effecting actions on the INTERACTIVE dashboard, and only there.**
Exactly one entry in `source.dashboards[]` carries `interactive: true`
(`role: review-action` / `review` / `decision`); its run is deliberately
left `in_progress` so the control is live (`demo-data-setup § The
interactive run stays live`). Every OTHER dashboard's run is completed and
therefore **read-only** — its page prints "This run is completed…
Decisions are read-only" and disables the status control, so a scene there
can only `wait_for` / `hold` / capture. Author the payoff scene — the one
where a stakeholder *takes* a decision — against the interactive
dashboard's `${<key>_par_url}`. Writing a click into a completed
dashboard's scene is what produced the 1.0/5 arc on
hh-poverty-targeting/20260730-2210: 10 of 10 actions degraded to
`wait_for`/`hold` and 7 scenes rendered 2 distinct images
(dimagi-internal/ace#1162).
**Unless `source.interactive_live_load.status` is `failed` (ace#2430).**
An `in_progress` run's page has no snapshot, so it re-runs the live
pipeline stream on every load; when the producer's step-4c probe caught
that failing against a control run that DOES render, the interactive run
ships `completed` under an evidenced escape and its control is read-only
like every other. Do not author a click against it — it would degrade to
a `hold` and cost the arc exactly what #1162 cost it. Author the finale as
the strongest READ beat available and declare check 20's evidenced
`finale_is_read`, citing that record's `control_run_id` and
`upstream_ref`. Check the field before you place the payoff; a blank or
`ok` record means the normal rule above applies unchanged.
**When `source.payoff_control` is set, the payoff scene MUST act on that
control — it is not a hint (ace#2316).** The producer sets it when the
opp's cohort sits below the detection floor and it took the
`below_programme_scale` escape, which is granted only on the promise that
the payoff rests somewhere that scale supports. You are the half that keeps
the promise. Do NOT author the payoff against whichever control the
template happened to ship: on `spark-facilitator/20260908-2215` the
interactive dashboard came from `llo_weekly_review`, whose affordances are
an underperforming-only filter and a coaching-task button, and the payoff
became the filter — hiding 10 rows of 12 on a table that already fitted one
screen. Four independent judges capped `use_case_soundness` at 3 on it, and
the run could not converge. `checkEscapedPayoffIsHonoured`
(`lib/ddd-scene-actions.ts`) is the gate; `demo-data-setup-qa` check 19
runs it. **If the declared control is not on the page, that is a producer
defect — send it back rather than re-aiming the scene**, because re-aiming
is what ships the same demo with a green check.
**Order the scenes as a LADDER that ends on the action (ace#2339).** The
arc judge's `arc_shape` carries a **hard cap at 3** when the final scene is
not the run's strongest moment. It is weighted .30, every judge's overall is
the MINIMUM across its dimensions, and the convergence bar is 4.0 — so a
deck that ends on a recap **cannot converge**, however good every frame is.
The ladder, each rung a genuinely different surface and granularity:
| Rung | What it shows | Why it earns its place |
|---|---|---|
| **Programme** | one row per opportunity / site | only when the programme has genuinely DISTINCT sites — see the warning below |
| **Opportunity** | the window and the funnel — totals, the rule, the aggregate | orients a stranger in one frame |
| **Worker** | one row per worker, sorted by the measure that matters | the rung most often skipped, and the one that makes the next drill feel earned |
| **Record** | the single item, and the rule that decided it | the peak: the thing no aggregate can show |
| **Action** | the operator DOES something, and the outcome is on screen | **must be last** |
**The programme rung is usually NOT available, and forcing it is worse than
omitting it.** ACE mints a fresh Connect opportunity per run, so a program's
opportunity list is mostly per-run duplicates of one pilot rather than
distinct sites. Measured 2026-09-09: Connect program 210 carried EIGHT
opportunities, all run-stamped copies of the same Spark pilot
(`20260907-1120 · …`, `20260828-0703 · …`). A rollup over those shows one
pilot eight times, which is the repetition the arc judge penalises directly.
Check the opportunity NAMES before you plan a programme rung; if they are
run-stamped, start the ladder at Opportunity.
**Whatever the trailing commentary is — caveats, open parameters, what the
pilot has not set — it goes in the FRAMING, not the finale.** It is honest
and it belongs in the deck; it just cannot be the last thing. Measured on
`spark-facilitator/20260909-1211`: the peak was scene 4 of 6, the one
state-changing beat was scene 5, and scene 6 was the open-parameters recap.
The judge: *"the run's strongest moment is scene 4 of 6, and both remaining
scenes decline from it … scene 6 is prose-only with no data, delivering the
payoff sentence over the run's emptiest screen. The finale-strength
deduction is a hard cap at 3."* Every ingredient of a strong finale was
already in that deck. **It was a reordering, not missing material.**
`checkArcLadder` (`lib/demo-arc-ladder.ts`, `demo-data-setup-qa` check 20)
enforces the floor of this — that the last scene performs a state change —
and **it is deliberately weaker than the rule above.** It would have PASSED
the run that motivated it, because that deck's recap scene technically
clicked a disclosure control. Distinguishing "a click that reveals prose"
from "a click that changes what the product knows" needs rendered frames and
is the arc judge's job; a static heuristic for it would be the fourth
retracted rule in this family. So the check catches a genuinely inert
finale; the ladder above is what stops a recap finale, and that part is on
you.
**Putting the action LAST is necessary and NOT sufficient — the finale has to
be strong in ABSOLUTE terms (ace#2347).** Measured: ordering the ladder
correctly moved `spark-facilitator` +1.0 across all three judges (2.0 → 3.0,
fail → warn) and unblocked the loop, and `arc_shape` **still capped at 3**.
The judge validated the order and applied the cap anyway — *"The ladder is
real and load-bearing … No two scenes could be swapped without breaking a
dependency … That is 5-anchor structure. But the deduction rule 'the final
scene is not the strongest moment' FIRES."* The cap measures how much the
last frame DELIVERS, not where the peak sits.
Two consecutive runs died on the same defect one dimension apart, and both
redesign findings describe one shape: **a finale that performs a single
instance of a rated activity, with no aggregate and no consequence.**
| Run | Dimension | The judge's words |
|---|---|---|
| `20260909-1211` | `arc_shape` | the finale *"inherits that whole table unchanged and adds one line of text and one small chip"* |
| `20260909-2242` | `use_case_soundness` | *"the page states the programme 'reviews at least one meeting in five in person' — roughly 35 of 173 records — and the walkthrough demonstrates exactly one review, producing an anonymous, undated chip, with no coverage measure against the 1-in-5 target anywhere on screen and no visible downstream consequence … A skeptical buyer watching the run's closing beat asks 'is that all it does?'"* |
So author the finale against three rules, all three read off that text:
1. **The action must produce something the previous frame did not already
contain.** A reviewer *confirming* a decision the page already displays
adds a chip and no information. A reviewer *contradicting* it — recording
"needs a site visit" on a row the machine marked **Paid** — adds
information, and it is usually the truer demonstration too: a two-layer
verification design has a human layer precisely to catch what the
automatic layer cannot, so a finale where the human agrees is a finale
that never exercises the design.
2. **If the page states a RATE for the activity, show the RATE, not one
instance.** One review against a stated 1-in-5 target is the
`use_case_soundness` litmus firing verbatim. Put the coverage beside the
single act — "8 of the 35 reviews this window are done" — so the closing
frame answers *"is that all it does?"* instead of inviting it.
3. **The action must have a visible downstream consequence.** *"the record
still earns nothing, and nothing connects the finding to any effect"* — a
state change no one can see the effect of is a chip, not a payoff. Show
what the finding changes: a payment released, a record queued for a visit,
a counter moving.
**This is authoring guidance, not a check, and deliberately so.** Whether an
outcome is *new information* or a restatement is semantic and needs rendered
frames; a static proxy for it would be the fourth retracted rule in this
family (ace#1660 retracted, ace#1841 pruned). `checkArcLadder` enforces only
the floor — that the last scene acts at all. Everything above is on the
author, and the evidence that authoring guidance works here is the +1.0 the
ladder itself produced.
**Rules 2 and 3 are PAGE requirements — meet them on the page, not in the
narration (ace#2347).** Rule 1 is satisfiable by authoring alone (pick the
record the machine marked `Paid` and act on the control that exists). Rules 2
and 3 are not: a coverage measure ("8 of the 35 reviews this window are
done") and a visible downstream consequence (a payment released, a record
queued) must be ON the dashboard, and on `spark-facilitator/20260910-0541`
neither was — the page had no coverage figure and the review chip changed
nothing. This skill does not render, but it MAY patch the page it narrates
over. When the finale's page lacks the rate or the consequence:
- **Patch the dashboard first.** `workflow_get` the finale's workflow (id from
its `par_url`, `/labs/workflow/<workflow_id>/run/`), add the coverage
figure beside the act and the consequence the act produces (computed from
the run's own state — never a hard-coded number), lint the whole source
with `scripts/check-render-code-utilities.ts` (`demo-data-setup` step 3b),
then upload with `workflow_update_render_code` (or
`workflow_patch_render_code` for a small hunk), passing the
`render_code_version` you read as `expected_version`. Style it with
`window.LabsReport` per `playbook/integrations/connect-labs.md` § "Style
`render_code` with `window.LabsReport`". It is the same move
`checkEscapedPayoffIsHonoured` (`lib/ddd-scene-actions.ts`) already
demands of a missing payoff control: the control "has to be authored onto
the page rather than borrowed from the template".
- **Then narrate what the page now shows**, and nothing beyond it. Re-run
3d's gap-copy check, since the patch added copy.
- **Never narrate a rate or a consequence the page does not show.** That is
a `claim_reality_coherence` defect, not a fix for `use_case_soundness`: it
trades a capped gating dimension for a dishonest finale, on the dimension
that was already this opp's weakest. If the page cannot be made to show
it, cut the claim and let the finale be judged on what is there.
- `scenes[]` — each scene: `persona` (must exist in `personas`), `title`,
`show`, `concept_claim` (≥5 words, falsifiable, NO banned marketing
phrases), `provenance` (= a spine `id`), `role: demo`, ≥1 `feature` with
non-empty `description` AND `verify`, `actions[]` (from the 17-verb
vocabulary), and `url: ${<key>_par_url}` — the realized var for **that
scene's dashboard** (`${program_admin_par_url}`, `${child_recovery_par_url}`,
or a drill var). **Only the first scene on a given surface carries `url`** —
consecutive same-`url` scenes reload the page (`hal:synthetic-walkthrough`
anti-pattern); follow-on scenes on the same dashboard omit `url` and just
act/capture. Crossing to a different dashboard = a new scene WITH its
`${<key>_par_url}`.
- **The `role: overview` opener — author it HERE, before 3c (ace#2747).**
canopy's `ddd-spec-qa` refuses a spec of ≥4 scenes (not `style: recorded`)
without one, so if you leave it out the DDD loop adds it later and 3c will
have judged a different spec from the one canopy renders. Make it scene 1:
`role: overview`, the first dashboard's `url`, a `narrative` that is the
goal-setting opening voiceover (the holistic "why"), no `features`, no
data-demonstrating actions. canopy's renderer absorbs it into the narrated
intro title card rather than playing it as a body scene, so 3c drops it
from the sequence it judges (`bodyScenes` in `lib/demo-arc-precheck.ts`)
and tells the text judge it is the title card — a data-less roadmap is
not an escalation dead slot. Its `url` still carries forward, so the
first body scene on that dashboard omits its own.
3b. **Check every scene's ACTIONS before validating (ace#1379, #1380, #1660, #2219).**
Run `checkSceneActions` from `lib/ddd-scene-actions.ts` over `scenes[]`,
**and `checkSceneCardinality(scenes, shape)` from the same module** — the
executable form of Step 2b, which re-reads the authored scenes rather than
your intent. It emits two kinds, and it FLAGS rather than rejects, because it
reads the data's shape but not the dashboard's rendering and so cannot be
certain which population a surface enumerates — refusing a legal spec on that
would be the ace#1238 guard-predicts-a-rejection failure. **A flag is
therefore never carried past silently: resolve every one** by taking a Step-2b
branch or by recording which population the surface actually lists.
- **`insufficient-cardinality`** — the demonstration needs more than the data
has. Take one of the two Step-2b branches.
- **`unknown-cardinality`** — the axis is not in the handoff at all. That is
the ace#1670 starting state; go get the number (§ Inputs names where), do
not author past it.
Three more ways a scene reports `ok: true` while demonstrating nothing — all
found on ONE run, spark-facilitator/20260813-2126:
- **`ambiguous-text-target`** — target the CONTROL, never the words. A
`text:` selector resolves `.first()` in DOM order and **clicking a
non-interactive node succeeds**, so the action reports ok while nothing
happens. Scene 3's `click text:Needs a look` matched three nodes — a
card-subtitle DIV, the real LABEL, a reconciliation-sentence DIV — and
took the DIV. `record_video` reported *39 actions: all ok* on a frame
showing the checkbox unchecked and "showing 20 of 20 facilitators". Use a
recorder prefix — `css:` / `testid:` / `aria:` / `role:` (`role:` also
takes a name: `role:button:Save`). The separator is `:`; canopy's
`parse_target` has no `=` form, so `css=…` falls through to the
bare-string heuristic — the ambiguity you were trying to escape
(ace#1519).
- **`non-discriminating-gate`** — a `wait_for` must name something only the
POST state carries (a count, a status word, the new id). `wait_for
text:Showing` was true before and after, so it could not fail.
- **`mutation-without-restore`** — a click that creates or destroys a
persistent object makes the scene non-idempotent. Scene 5's first render
created coaching draft #5139; the next render found "Open draft #5139"
instead, failed `target_not_found`, and captured the un-drafted state
while the narration described a draft being written. Declare a
`restore:` block — and note it must run before **every** render **and
before every frame-fit pass**, because the verifier replays these same
actions and so consumes the precondition for the render after it.
- **`labs-report-target-outside-frame`** — the capture saw this labs report
drawn in the `/labs/sandbox/render/` iframe, and the target does not enter
it, so the recorder looks for it on the top page and misses (ace#2885).
Replace it with the rewritten target the finding prints
(`inLabsReportFrame`, step 2c). Leave it only if it names the outer page
(the breadcrumb, the scope picker).
- **`labs-report-target-in-absent-frame`** — the capture saw this labs
report drawn on the top page with no sandbox frame, and the target enters
one, so it misses. Replace it with the printed rewrite
(`outOfLabsReportFrame`). Both checks need a frame-recording capture
(`frame_texts`); with none they report nothing.
The gate check is a WORD COUNT, so it only runs on `text:`/bare targets.
A control-selector gate (`testid:` / `css:` / `aria:` / `role:`) is left
alone — you have already named one element, and counting the words in its
id cannot say whether it is post-state-only (ace#1660).
**Retracted (ace#1660): there is no `scroll-under-fixed-header` check, and
`scroll_to` needs no offset.** A fourth check used to flag every `scroll_to`
without `offset: 96`. Both halves were wrong against canopy 0.2.423 and it
is deleted — **do not re-add it, and never write `offset:` on an action**:
- canopy's `ScrollToAction` declares only `kind` + `target`, and
`_ActionBase` sets `extra="forbid"`, so `offset:` makes the spec FAIL
validation (`Extra inputs are not permitted`). Following the old
remediation turned a passing spec into one canopy refuses.
- The premise was stale anyway. `recorder.py::scroll_to` chases
`scroll_into_view_if_needed` with an explicit centring scroll
(`window.scrollTo({top: y + scrollY - innerHeight / 2})`), so the element
lands at the vertical CENTRE — no fixed bar reaches it. That was #1365's
own fix, closed 2026-08-14.
If a scene genuinely needs different framing, the levers canopy accepts are
`scroll_to` (which names an element and lets the recorder centre it — the
right answer nearly always), `scroll` (whose `value` takes `top` / `bottom` /
a pixel offset), and a per-scene `viewport`. Which of those you reach for is
the fourth defect class, below.
**The fourth defect class**, on a different axis from the three above — the
scene is well-formed and demonstrates the right thing, and **the frame
nobody can read it in** (ace#2219):
- **`pixel-scroll-framing`** — a `kind: scroll` carrying a raw pixel `value`
decides how a judged still is framed, and a pixel offset is a guess about
how a page this spec does not own renders. It is right for one viewport,
one row count and one font stack, and reports nothing when it stops being
right. `poverty-graduation/20260905-1345` used `kind: scroll` five times
(`'400'`, `'1280'`, `'bottom'`, `'320'`, `'top'`) against one `scroll_to`;
scene 5's landed a twelve-row table one row short, and row twelve — Umar
Bello — rendered *"sliced through its middle at the bottom edge with its
badge truncated mid-word"*, which the judge said *"spoils scene 6 without
being readable"*, while the same scroll put the title, the simulated-data
disclosure and all four KPI cards off the top. `projector_test: false` and
`five_second_read_correct: false` on **7 of 7** scenes; the run ended at
concept 2.0/5. **The remedy is `scroll_to` naming the element the frame is
about** — canopy resolves and centres it live, so it holds at any page
length. If the header block and the whole table cannot co-exist in one
frame, split the beat into two scenes rather than compromising both. Park
the cursor outside the content column before a hold, too: on the same run
it occluded the chart subtitle in scene 2 and the header in scene 5.
- `top` / `bottom` are **reported, not rejected**. They name a landmark the
page defines and survive a layout change, but they decide only one edge of
the frame — scene 4's `bottom` guillotined two histogram bars at the top
edge, dropping their value labels and rendering bars differing by 140
households at identical heights, while the panel the scene was about sat
fully framed below. Right whenever the frame's subject IS the page's first
or last content; confirm that it is.
**This is NOT the retracted ace#1660 check, and it adds no `offset:`.** That
check flagged `scroll_to` for LACKING an offset — the exact inverse. Here
`scroll_to` is the remedy, written as canopy declares it: `kind` + `target`
and nothing else. Worth saying because the judge's own remedy on this run
reads *"offset so no partial histogram sits above it"*, which is the
retracted syntax verbatim and makes the spec fail validation if followed.
Run `checkScrollFraming` from `lib/demo-frame-legibility.ts` over the spec —
`demo-data-setup-qa` check 14 is the backstop that runs it again.
**Then judge the deck as a SEQUENCE, not scene by scene.** Run
`checkSceneVariety` from `lib/demo-scene-variety.ts` over the same spec. The
arc judge is the only lens in the DDD loop that can see repetition, and two
of its five dimensions are capped by rules that are decidable from the scene
table before anything is rendered:
- **`visual_variety`** — *"more than half the scenes are the same surface at
different scroll offsets"*.
- **`escalation`** — *"two scenes showing the same surface with only a scroll
between them"*.
On `spark-facilitator/20260907-1120` both fired: 4 of 7 scenes were the
payment ledger at four offsets, and scenes 2, 3 and 4 each followed the
previous one with nothing but a scroll. The judge's verdict was that the run
*"contains exactly two shapes across seven frames"*, and of scene 2 that *"the
panel it narrates is already fully readable in scene 1's frame, so it adds
voiceover, not a new thing to look at"*. Arc scored 2 of 5, `fail`.
**The loop cannot recover from this and will stop rather than fix it** —
collapsing or reordering scenes is a narrative change behind the
`concept_change` gate, so an unattended run reports it and terminates
`stopped_not_converged`. Catching it here costs one edit. Catching it after
the render costs the phase.
A scene that shows the viewer something the previous frame already contained
is voiceover with a picture attached: fold it into the scene before it, or
give it an action that changes what the page shows — a filter, a selection, a
drill-in. `demo-data-setup-qa` check 17 is the backstop that runs this again.
**Every narrated figure must be on the scene's END FRAME — never hover-only
(ace#2727).** Run `checkNarratedFiguresOnScreen` from
`lib/narration-on-screen.ts` over `scenes[]` (or
`scripts/narration-claims.ts --spec <spec> --check`). A figure — a
percentage, an "N of M", a money amount, a date — that the scene's
narration says must be ANCHORED: written into a `features[].verify` that
names where on the end frame it is ("the SF_P1 column reads 62%"), or the
target of a `wait_for` that proves the page rendered it. An anchor that is a
hover/tooltip, a `hover` action's target, or narration that itself says
"hover" is **`hover-only-figure`**; no anchor at all is
**`unanchored-figure`**. Both flag rather than reject (the check reads the
spec, not the rendered page) and, as with cardinality, **every flag is
resolved**: say a figure the frame prints, make the page print it, or cut
it.
**Then check the figures against what the page PRINTS, frame included
(ace#2885).** The spec check above reads the spec, not the page. canopy's
recorder saves the top page's `document.body.innerText`, and on a labs
report that is the breadcrumb alone (270 characters on programme report
8529), so canopy's narrated-numbers check cannot see a single report figure.
Fetching the render URL does not help: the shell is data-free, and the
report arrives over a message bridge. Capture each scene's end-frame text
with a browser that enters the frame, then run the check against it:
```bash
node "$ACE_ROOT/node_modules/tsx/dist/cli.mjs" "$ACE_ROOT/scripts/capture-scene-text.ts" \
--spec <demo-run>/7-synthetic/<demo-slug>.yaml --realized <demo-run>/7-synthetic/realized.json \
--out <scratch>/scene-text
node "$ACE_ROOT/node_modules/tsx/dist/cli.mjs" "$ACE_ROOT/scripts/narration-claims.ts" \
--spec <demo-run>/7-synthetic/<demo-slug>.yaml --check --screen-text <scratch>/scene-text
```
The capture is read-only. It replays each scene's `wait_for` and `click`
actions, but never a click on a scene with `restore:` or a click that names
a mutating verb. **`figure-not-on-screen`**: the end frame does not print a
narrated figure, so resolve it like `unanchored-figure`.
**`screen-text-outer-page-only`**: you passed a top-page-only capture
(canopy's own `scene_<N>_page_text.json`), so the check could not read the
report. Re-capture; never read it as "the figures are fine".
*Why the existing rule did not catch it.* Step 2c's only figure rule —
"never claim a figure the saved run does not show" — checks the DATA. On
`spark-facilitator/20261004-1706` the narration said *"100% as of 12 Jul"*, a
value labs shows only in a tooltip: it IS in the saved run, so 2c passed it,
while the judged still and the video's end frame have no cursor over the
cell. Nothing checked the FRAME. Measured before this rule: zero occurrences
of `hover`, `tooltip` or `end frame` in this skill or the Phase 7 agent.
These are the halves decidable from the SPEC. The runtime halves —
resolving an ambiguous target to the interactive node, comparing a gate
against the captured before-frame, replaying restores — belong in
canopy's walkthrough runner and are tracked upstream.
3c. **Pre-render arc check — the sequence, from the TEXT, before anything renders
(ace#2735).** `checkSceneVariety` and `checkArcLadder` each answer one
question; canopy's `ddd-arc-eval` judges five, and only after a render. On
`spark-facilitator/20261004-1706` (DDD run 2026-10-06-002) both of ours passed
while the arc judge found three things the spec already said: *"Scenes 4 and 5
both end on the same community visit-list component"*, *"The finale (scene 6)
restates scene 1/2's headline fact (Kuunika 66.0% ...)"*, and *"Scene 5 ... is a
side-branch ... its slot is not load-bearing"*. Run:
```bash
node "$ACE_ROOT/node_modules/tsx/dist/cli.mjs" "$ACE_ROOT/scripts/demo-arc-precheck.ts" \
--spec <demo-run>/7-synthetic/<demo-slug>.yaml --realized <demo-run>/7-synthetic/realized.json \
--prompt-out <scratch>/arc-precheck-prompt.md
```
- **Deterministic half** (`lib/demo-arc-precheck.ts` `checkArcPrecheck`). BLOCKS
on `same-surface-component` — consecutive scenes on the same resolved surface
(the `${var}` substituted from `realized.json`, query dropped, so two
worker-review URLs are one template) settling on the same component (their
last heading/tab/landmark `wait_for`) — and on a finale whose
`concept_claim` states only facts scene 1's claim already stated. REPORTS a
finale narration restating an opening fact anchored to the same name, and a
middle scene on a new surface that names nothing its neighbours name while
the next scene resumes the earlier thread (a side-branch).
- **One cheap text-only judge pass** for what needs judgment: dispatch a fresh
`Agent(general-purpose)` (independent of the author, as `ddd-arc-eval`
requires; a small model is enough) with the prompt file and nothing else,
save its YAML answer, and gate it:
`scripts/demo-arc-precheck.ts --spec … --realized … --verdict <answer.yaml>`
(`gateArcPrecheckVerdict`: any dimension ≤ 2 blocks; a 3 is carried into the
hand-off as a reported risk; a missing dimension fails — never write the
answer yourself). The rubric (`ARC_PRECHECK_RUBRIC`) mirrors `ddd-arc-eval`'s
five dimensions, weights and deduction rules from the installed canopy
`skills/ddd-arc-eval/rubric.yaml`, restricted to what text can show.
- **It never replaces canopy's `ddd-arc-eval`.** That judge sees frames, page
text and composition; this pass sees only the spec. A clean pre-check is a
prediction that the cheap-to-fix sequence defects are gone, not a verdict.
Fix a blocker by reframing, merging or reordering what the deck already has,
re-run 3c, then validate (step 4).
3d. **Gap-copy check — dashboard copy AND the narrative against the brief's own
gaps (ace#1750, ace#1759, ace#2244).** This is where the check runs, because
this is the first point at which its input exists: `why_brief.yaml` is
authored here in Step 2, while `demo-data-setup` uploaded its dashboards one
step earlier, before any gap list existed — which is why its old position
(`demo-data-setup` § 3c) could never run and the dashboard-copy half of
ace#1750 was dead from the day it shipped (`spark-facilitator/20260907-1120`
recorded it `NOT RUN`). Read each dashboard's render_code AS UPLOADED — one
`mcp__connect-labs__workflow_get({workflow_id, opportunity_id | program_id})`
per entry in `source.dashboards[]` (the `workflow_id` is the path segment of
its `par_url`, `/labs/workflow/<workflow_id>/run/`; the scope is
`labs_synthetic_opp_id`, or `program_id` for a program-owned workflow), saved
to a local file — then:
```bash
node "$ACE_ROOT/node_modules/tsx/dist/cli.mjs" "$ACE_ROOT/scripts/check-gap-copy.ts" \
--why-brief <demo-run>/7-synthetic/why_brief.yaml --spec <demo-run>/7-synthetic/<demo-slug>.yaml \
--render <key>=<scratch>/<key>.render.jsx ... # one --render per dashboard
```
It runs `checkGapCopy(whyBrief.gaps, [...dashboardSources, ...narrativeSources(whyBrief, unifiedSpec)])`
from `lib/gap-copy-check.ts` (rules, scope and known limits: `demo-data-setup`
§ 3c). **It FLAGS, never rejects** — resolve every finding before the DDD
hand-off: a narrative finding by rewording the brief/spec, a dashboard
finding with `workflow_patch_render_code` (`workflow_get` → patch locally →
lint the whole source with `check-render-code-utilities.ts` → upload; still
cheap, nothing has rendered yet; style any added copy with `window.LabsReport`
per `playbook/integrations/connect-labs.md` § "Style `render_code` with
`window.LabsReport`"), or by recording why the line is
legitimate. Record the outcome as
`steps.demo-narrative.gap_copy_check: {ok, findings, resolved}` — never as
`NOT RUN`, and never scan only the narrative because the renders were
inconvenient to read.
3r. **The recorded-walkthrough variant: opt-in only (ace#2789).** Skip this step
unless `style: recorded` was explicitly requested (§ Inputs). **The default is the
produced explainer**, everything above, unchanged. When it was requested, the
shape is canopy's, so read canopy's contract and do not paraphrase it here:
`skills/ddd-recorded-walkthrough/SKILL.md` in the installed canopy plugin
(`python3 -c "import json,os;print(json.load(open(os.path.expanduser('~/.claude/plugins/installed_plugins.json')))['plugins']['canopy@canopy'][0]['installPath'])"`).
In outline, and the canopy skill wins on any difference:
- Put `style: recorded` and a `cuts:` list (`{id, title, scenes: [<scene id>, …]}`,
every scene in at most one cut) in the **recipe**, never in the narration
posted to canopy-web. They are render decisions, not story.
- Each cut's first scene's `narrative` opens with **"This is a quick overview of
how we <do X>."** and opens on a live screen (a `url:` plus a leading `wait_for`).
Each cut runs about 65–80 words (30 s target, 40 s hard ceiling), first person,
one sentence per visible thing, with no welcome, summary or sign-off. Put a
`say:` on every action the narration names.
- No `role: overview` title-card opener is needed (Step 3's opener rule is for the
explainer; canopy's `ddd-spec-qa` waives it for a recorded spec), and no music,
title or end card, zoom, callout or lower-third. canopy's schema refuses them.
- **Lint before handing off**, from canopy's runtime (as in Step 4), and loop
until it exits 0:
```bash
(cd "$CANOPY_RT" && uv run python -m scripts.ddd.recorded lint <demo-run>/7-synthetic/<demo-slug>.yaml)
```
- After render (one mp4 per cut, canopy's `ddd-recorded-walkthrough` § 3), the
set must pass canopy's cut-length **gate**, `scripts.ddd.recorded gate --spec …
--cut <id>=<mp4> …`. A `fail` (a cut over 40 s) is fixed by trimming words or
splitting the cut, never by speeding the footage. Never render a recorded cut
through `/ace:video-render-local`: that vendored engine predates `style` and adds
the music bed back.
Record `steps.demo-narrative.style: recorded` (or `explainer`) and, for recorded,
`steps.demo-narrative.recorded_lint: {exit, cuts: [{id, words, est_seconds}]}`.
4. **Validate — the gate.** Resolve canopy's runtime from its installed
plugin, then run the validator from there (pass the artifact paths as
absolute paths — the subshell's cwd is the runtime, not yours):
```bash
_CANOPY_PLUGIN="$(python3 -c "import json,os; d=json.load(open(os.path.expanduser('~/.claude/plugins/installed_plugins.json'))); print(d['plugins']['canopy@canopy'][0]['installPath'])")"
CANOPY_RT="$(bash "$_CANOPY_PLUGIN/scripts/canopy-runtime.sh")" || { echo "ERROR: canopy runtime not found — run /canopy:update"; exit 1; }
(cd "$CANOPY_RT" && uv run python -m scripts.ddd.validate why_brief <demo-run>/7-synthetic/why_brief.yaml)
(cd "$CANOPY_RT" && uv run python -m scripts.ddd.validate unified_spec <demo-run>/7-synthetic/<demo-slug>.yaml)
```
(Confirm the exact `<kind>` tokens from `validate()`'s dispatch on first use.)
Exit `0` = valid. Loop: fix reported problems, re-validate, until BOTH pass.
Do not hand off an unvalidated narrative.
4b. **A re-author after the DDD loop has run must `post`, never `pull`
(ace#2254).** The loop's corrections live in its own spec/why-brief copies;
Phase 7 Step 3.5 carries them to Drive and canopy-web. If you are re-invoked
to revise a narrative the loop already touched, start from the loop's final
`docs/walkthroughs/<slug>.yaml` (or Drive, once 3.5 has written it), and
publish with `scripts.ddd.narrative post <spec> <run_id>`. `narrative pull`
copies canopy-web → local and would silently restore the pre-loop text.
5. **Write back** `narrative` refs + `steps.demo-narrative.status: done` via
`mcp__plugin_ace_ace-gdrive__update_yaml_file` (`merge: 'deep'`).
6. **Publishing a set of demos (decision rows, not brief lists).** When the
demos are shared as one storyboard set on canopy-web, publish the board with
canopy's `scripts.ddd.demo_set publish`. canopy-web takes the set's open
questions as **`decisions[]` rows** (live since canopy-web#1516); the old
brief lists are retired and `demo_set` refuses them, so never put assumptions,
divergences or open questions in the brief.
- Write `<path>/board.json` as a StoryboardIn: `slug`, `title`, `lede`,
`brief` (only `audience`, `purpose`, `data_disclosure`, `short_version`),
`decisions[]`, `acts[]`, `capability` (`"comment"` or `"suggest"`) and
`agent_project` (the ACE project for the work).
- One `decisions[]` row per default the set is built on, in plain language.
Row fields (canopy-web `DecisionIn`): `id`, `question`, `plain_question`,
`options` (each at most 8 words), `recommended`, `review_ask`, `needed_by`,
`evidence_basis`, `conflict_signals`, `reasoning`. The `review_ask`,
`evidence_basis` and `conflict_signals` vocabulary is ACE's shared
decision-row vocabulary in `lib/decisions-schema.ts` (`REVIEW_ASKS`,
`evidence_basis` stated | inferred | conflicting) - cite it, do not invent
values. `needed_by` here takes canopy-web's storyboard values
(`external-share` | `next-run`), not the run-lifecycle `NEEDED_BY` gates in
that file.
- What a reviewer must answer before the set is shared externally:
`review_ask: required-before`, `needed_by: external-share`.
- What a reviewer should confirm: `review_ask: recommended-confirmation`.
- Where the script and the data disagree: `evidence_basis: conflicting`,
with both readings in `conflict_signals` (at least two) and the
resolution in `reasoning`.
- Publish through the pinned wrapper (never a bare canopy call):
```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'])")}"
_CANOPY_PLUGIN="$(python3 -c "import json,os; d=json.load(open(os.path.expanduser('~/.claude/plugins/installed_plugins.json'))); print(d['plugins']['canopy@canopy'][0]['installPath'])")"
CANOPY_RT="$(bash "$_CANOPY_PLUGIN/scripts/canopy-runtime.sh")" || { echo "ERROR: canopy runtime not found - run /canopy:update"; exit 1; }
(cd "$CANOPY_RT" && "$ACE_ROOT/bin/ace-canopy-web" --workspace <ws> -- uv run python -m scripts.ddd.demo_set publish <path>/board.json)
```
(Each Bash call is a fresh shell, so the resolvers are restated here; the
form is `bin/ace-canopy-web --workspace <ws> -- <command>`.)
`demo_set` POSTs the board and PATCHes on a 409, so re-running updates it.
- **Verify before citing the link:**
`bin/ace-canopy-web --workspace <ws> verify storyboard <slug>` - exit 0 only
when the board is readable in `<ws>`; cite the `url` it prints
(`https://canopy.dimagi.com/w/<ws>/storyboard/<slug>`), never a flat link.
- Publishing or sharing the board is an outbound act: it follows the turn
mode's approval rule like any other publish or share (see
`skills/_terminology.md` for wording - "Connect", never the retired long
form).
## Gotchas
- **`concept_claim` is falsifiability-gated** by `ddd-spec-qa`: ≥5 words, no
marketing filler ("seamless", "powerful", …). Write claims a skeptic could
check against the on-screen dashboard.
- **Three overreach shapes that PASS the falsifiability gate and are still
wrong** (ace#1395 — all three shipped in the same walkthrough, so the gate
above is necessary and not sufficient). Each is checkable while writing:
1. **Renaming the quantity.** The scene was titled *"What a verified
community meeting costs"* and narrated *"what a funder buys here"*, over a
panel headed **FACILITATOR EARNINGS**. A piece rate paid to facilitators
is not the programme's cost: by the frame's own footnote every payment
also passes a human reviewer, and the 56 recorded-but-unpayable records
still consumed facilitator time. **Use the label the panel actually
shows.** If you want the derived figure, render it as its own labelled row
naming what it excludes — don't rename it in narration.
2. **Causality from n=1.** The coaching-arc panel plotted eight weekly
medians for ONE facilitator, no n per bar, no cohort baseline, and a
bolded before/after conclusion. A reader is led to "the coaching caused
this" from an uncontrolled single-subject pre/post. Either plot the cohort
median behind it as a reference band (making the causal read testable) or
lead with the claim the frame CAN carry — here, that the tolerance
withheld no payment, evidenced by all four above-tolerance records reading
`Paid · USD 3`.
3. **A summary adjective that doesn't match the plotted series.** Narration
said the weekly median *"sat in the low fifties across the three weeks
before"*; the visible bars are **52.5 / 57.6 / 53.3**, and the page's own
caption ("between 52.5 m and 57.6 m") was correct. This survived an
explicit narration-correction pass that was supposed to read off the
plotted series — so **read the rendered numbers, don't summarise from
memory of the design**.
- **No build notes in funder-facing copy.** The integrity dashboard's
methodology footnote shipped *"Every colour on this page is an inline style
so that no compiled-CSS purge can silently blank a bar."* That is a note to
ourselves about a rendering workaround, in a block a funder reads. Keep the
practice; delete the sentence.
- **`provenance` must match a real spine `id`**, and every `demo`-role scene
needs a `feature` with both `description` and `verify` — the actionability
eval cold-derives a build plan from narration and checks it against
`features[]`.
- **First-scene-only `url`** per surface (see Step 3).
- **This skill authors + validates only.** Rendering, judging, and video are the
DDD loop's job, invoked by `agents/demo.md` after this skill returns.
## Change Log
| Date | Change | Author |
|------|--------|--------|
| 2026-10-16 | **Opt-in recorded-walkthrough variant: Step 3r (ace#2789).** The skill could only author the produced explainer, so the chlorine-dispenser demo's short recorded cuts were hand-written outside ACE and could not be regenerated. Operator decision: explainer stays the default; `style: recorded` + `cuts:` is authored only on an explicit request (`/ace:demo --style recorded`, a dispatch `style: recorded`, or a brief that asks for it outright), per canopy's `ddd-recorded-walkthrough` contract, linted with `scripts.ddd.recorded lint` and gated with `scripts.ddd.recorded gate`. *Enforced:* `test/skills/demo-narrative-recorded-style.test.ts`. | ACE team |
| 2026-10-16 | **Finale rules 2 and 3 are met on the page; a re-author posts, never pulls (ace#2347, ace#2254).** Rules 2 (show the rate) and 3 (a visible consequence) are page requirements a narrative-only scope could only meet by narrating what the page does not show (`spark-facilitator/20260910-0541`). Step 3 now says to patch the finale's dashboard (lint first, `workflow_update_render_code`), the same move `checkEscapedPayoffIsHonoured` already demands, and names an unshown rate as a `claim_reality_coherence` defect. New step 4b: after the DDD loop has run, publish with `narrative post`; `pull` would restore the pre-loop text. The loop's own write-back is Phase 7 Step 3.5. *Enforced:* `test/skills/phase7-narrative-writeback.test.ts`. | ACE team |
| 2026-10-16 | **Step 3d: the gap-copy check runs HERE, after `why_brief.yaml` exists (ace#2244).** It was placed in `demo-data-setup` § 3c, one step before the brief that declares the gaps is authored, so it could never run — `spark-facilitator/20260907-1120` recorded it `NOT RUN`, and the dashboard-copy half of ace#1750 had been dead since it shipped. Now 3d reads each dashboard's uploaded render_code back with `workflow_get` and runs `scripts/check-gap-copy.ts` over it plus `narrativeSources(whyBrief, unifiedSpec)`; `demo-data-setup` § 3c only records the render sources and authors to the rules. *Enforced:* `test/skills/gap-copy-check-placement.test.ts`. | ACE team |
| 2026-10-16 | **The labs sandbox frame is conditional, observed per scene, never read off the URL (ace#2885 reopened).** On `smallholder-seasonal/20261015-1402` the indicator programme report (workflow 10049), the worker review (10051) and the opp reports drew on the top page with no `/labs/sandbox/render/` iframe, and the URL-only check flagged all 14 targets of the spec. Following its rewrite would have made every one miss. `checkLabsReportFrameTargets` now takes the framing a capture observed (`framingFromCaptures` over `capture-scene-text.ts` output), flags in both directions (`labs-report-target-outside-frame` / the new `labs-report-target-in-absent-frame`, fixed with `outOfLabsReportFrame`), and says nothing for an unobserved scene. `narration-claims.ts --screen-text` runs it against its captures. `screen-text-outer-page-only` now fires only when a top-page-only capture is MISSING figures, because the capture of an unframed report holds them. | ACE team |
| 2026-10-13 | **Labs report targets enter the sandbox iframe, and figures are checked against the frame's text (ace#2885).** Labs now draws report bodies in `/labs/sandbox/render/` (dimagi-internal/connect-labs#2449, #2466, #2470). The recorder resolves targets on the top page, so `smallholder-seasonal/20261012-1549` scene 1's `wait_for` missed. Its captured text was the breadcrumb only, so every narrated figure had to be checked by hand. Step 2c now passes every report target through `inLabsReportFrame` (`lib/labs-report-frame.ts`, the one place the frame prefix lives), and `checkSceneActions` flags `labs-report-target-outside-frame`. Step 3b adds `scripts/capture-scene-text.ts`, a read-only capture that enters the frame, and `narration-claims.ts --screen-text`, which flags `figure-not-on-screen` and refuses a top-page-only capture (`screen-text-outer-page-only`). The Spark worked example (`test/fixtures/demo-arc/spark-facilitator-20261004-1706-spec.json`) carries the framed targets. | ACE team |
| 2026-10-06 | **Step 3c — a pre-render arc check over the spec's text (ace#2735).** `scripts/demo-arc-precheck.ts` / `lib/demo-arc-precheck.ts`: blocks consecutive scenes on the same surface + component and a finale claim that only restates scene 1's; reports a restated opening fact and a side-branch scene; then ONE text-only judge pass with a rubric mirroring `ddd-arc-eval`, gated by `gateArcPrecheckVerdict`. Never replaces the post-render arc judge. On `spark-facilitator/20261004-1706` it finds all three things that run's arc judge found after render, while `checkSceneVariety` and `checkArcLadder` both pass it (`test/lib/demo-arc-precheck.test.ts`). | ACE team |
| 2026-10-06 | **Narrated figures must be on the end frame, never hover-only (ace#2727).** Step 3b runs `checkNarratedFiguresOnScreen` (`lib/narration-on-screen.ts`; CLI `scripts/narration-claims.ts --check`): every narrated percentage / "N of M" / money / date is anchored by a `features[].verify` or a `wait_for`, and a hover/tooltip anchor flags `hover-only-figure`. Step 2c's "never claim a figure the saved run does not show" checked the data, not the frame, so `spark-facilitator/20261004-1706` narrated *"100% as of 12 Jul"* from a tooltip. Step 2c also names workers/communities by the story plan's display roster, not codes. | ACE team |
| 2026-09-10 | **This skill is now the DECLARED producer of `products.synthetic.narrative` (ace#2354).** `PRODUCT_PRODUCERS` in `lib/phase-products-schema.ts` attributes each `products.*` key to its writer and ace-web's skill fork trims by it, so a fork AT this skill drops the stale `narrative` (and the Phase 7 agent's `ddd_*`) while keeping `demo-data-setup`'s `source` / `workflows` / `labs_opp_id`. Nothing changes in what this skill writes. | ACE team |
| 2026-09-10 | **Step 3 refuses to copy a PINNED `render_reset.command` into `setup.command` (ace#2351).** The verbatim copy is the right contract — the handoff is the record — but it also means a command written as `/Users/<name>/.claude/plugins/cache/ace/ace/<version>/scripts/…` reaches canopy's per-render `subprocess.run(shell=True)` as a snapshot of one machine: the cache keeps old versions, so the path resolves to STALE code after every `/ace:update`, and another account cannot use it at all. On `spark-facilitator/20260909-2242` the copied string pinned 0.13.1413 (pre-ace#2325) and only a hand rewrite kept every render from failing `run-not-found`. Now: halt on `/plugins/cache/ace/ace/` or `/Users|/home/<name>/` and send the author back to `demo-data-setup` step 4b's self-resolving form; `demo-data-setup-qa` check 18 fails the same pin as `render_reset_command_pinned`. | ACE team |
| 2026-09-08 | **The spec's `setup` block is `rerun: per_render` and must RESET the interactive run, not just re-emit `realized.json` (ace#2297).** Step 3 said `rerun: once`, which skips the setup command whenever the outputs file exists — i.e. from the second render on. But recording MUTATES the world: the coaching task the payoff scene creates persists on the labs run, so the next take finds the button gone and its `must_succeed` click aborts. On `spark-facilitator/20260908-2215` iterations 0-2 passed only because a human had reset labs run 5508 by hand. The command now prefixes `source.render_reset.command` (`demo-data-setup` step 4b); both halves are enforced by `demo-data-setup-qa` check 18. | ACE team |
| 2026-09-06 | **Narrow the detection vocabulary: `marker` / `markers` are OUT (ace#1893).** They were the only NOUN forms in it, and a noun names a thing on the screen rather than an act the platform performs — so on `hh-poverty-targeting/20260901-1932` the payoff scene, a pure DECISION beat (*"A collection window ends in a disposition stored per worker"*), was flagged as an insufficient-cardinality detection demo on nothing but the word `marker`, used twice for a "recorded on this run" badge. The author renamed the noun to `badge` to get past the flag, which is exactly the cost the module warns about (*"inventing a demonstration costs the author's trust in every flag after it"*). Measured over all 10 unified specs in Drive (4 opps, 10 runs, 59 scenes): 26 scenes match the detection vocabulary, **24 carry a verb form**, and only 2 match on `marker` alone — the same scene in two revisions of one narrative. **Spec-level recall is unchanged, 8 specs flagged before and after**, because every spec with a noun-only scene also has a verb-form one. The two narrower repairs the issue proposed were measured and rejected: requiring a corroborating second vocabulary word is bit-identical to deletion (24/26), and exempting `features[].verify` is strictly worse (23/26) — it does not clear the false positive, whose other hit is in `show`. The ace#1841 widening to `show` / `concept_claim` / `features[]` STAYS: ablating it took the same spec from 6 findings to 0. | ACE team |
| 2026-08-29 | Add a FOURTH demonstration verb — **detection / flagging**, on the `rows` axis with its own higher floor of **24** (`DETECTION_MIN_ROWS`, two screenfuls of the 12-row anchor the filter floor already uses): a filter claims narrowing is meaningful, a detection claims unaided scanning is not viable, and the second is false the moment the cohort fits in one look. `checkSceneCardinality` also now reads a scene's `show`, `concept_claim` and `features[]` alongside its title and action targets — measured on the failing spec, the detection vocabulary appears 20+ times and in not one title, so the verb alone would have matched nothing. The finding names the axis with room, because that is the action. `hh-poverty-targeting/20260828-0702` authored a detection demo over a seven-worker cohort; the gate returned ok with zero findings and the concept judge said post-render that a manager could find the outlier by eye, ending the loop `stopped_not_converged` at concept 2.0 after four iterations. ace#1841. | ACE team |
| 2026-08-26 | Add the dataset's cardinality as an INPUT (`source.record_counts` + `source.data_shape`) and a pre-authoring shape check (Step 2b) with a per-verb minimum — `rows` 12 for filter/search/sort, `periods` 4 for a trend, `groups` 3 for a comparison — enforced by `checkSceneCardinality` in `lib/ddd-scene-actions.ts` at Step 3b. Flags rather than rejects (the rule reads the data's shape but not the dashboard's rendering, so it cannot be certain which population a surface enumerates — ace#1238), but every flag must be resolved. `bednet-check-2-visit/20260825-1310` authored a filter demonstration over a five-worker cohort; every existing gate reported green and the concept judge caught it four render iterations later, ending the loop `stopped_not_converged` at concept 3.0. ace#1670. | ACE team |
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: 198k | 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: 194k | 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: 194k | 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: 194k | Updated | Claude CodeCodex | Verified | Install |