Skip to content

dimagi-internal/ace / skills/demo-narrative

demo-narrative

Verified

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.

FileKindSize
SKILL.mdskill md66.4 KB
---
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 |
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: 198kUpdated 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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated 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: 194kUpdated Claude CodeCodexVerifiedInstall