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.
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— theWhyBrief<demo-run>/7-synthetic/<demo-slug>.yaml— theUnifiedSpecrun_state.yaml…products.synthetic.narrative—{ why_brief_ref, unified_spec_ref, validated: true }run_state.yaml…steps.demo-narrative.status: done
Process
-
Read the schema, not this doc. Open canopy
scripts/narrative/models.py(or the JSON Schemas) for the exactWhyBrief,UnifiedSpec,Scene,Feature,Persona,SetupBlockfields + required/optional split. Mirror the working referencedocs/walkthroughs/program-admin-report.yamlin a local connect-labs checkout if present (e.g.~/emdash-projects/connect-labsor~/emdash/repositories/connect-labs) — a labs-dashboard walkthrough with asetupblock andurl: ${par_url}scenes, the closest template. Optional: skip it if no checkout exists. -
Author
why_brief.yaml.narrative_slug,problem(the funder's nutrition-program pain in one paragraph),spine[](eachid,claim,rationale,evidence[]),gaps[]. Demo honesty rule: a demo asserts aspirational value, so claims the built dashboard doesn't literally prove getevidence.kind: assumedand a matchingGapof typeDECISIONorCAPABILITY. Every grounded spine item needs ≥1 non-assumedevidence; everyGap.claim_refmust resolve to a spineid.
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 " (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.
-
Author the
UnifiedSpec(<demo-slug>.yaml):-
base_url: https://labs.connect.dimagi.com; noauthblock (labs cookies seeded out-of-band, perhal:synthetic-walkthrough). -
personas[]— first persona is the network manager; eachname, role, color, intro, org. One arc per dashboard insource.dashboards[]— e.g. a program manager onprogram_admin(multi-LLO oversight) and the same or a second persona onchild_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 }. Thecommandmust (re)producerealized.jsonfor the render session. For denovo Plan A this re-invokesdemo-data-setupin ensure mode; confirm idempotency live in the joint test (ifdemo-data-setupregenerates rather than reuses, either add an ensure mode or set the command to emit the already-writtenrealized.json).rerun: per_render, and the command must RESET the interactive run — not merely re-emit the map (ace#2297). This saidrerun: onceuntil 2026-09-08, andonceskips 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 amust_succeedclick aborts the whole render. canopy's ownSetupBlockdocstring names this case ("demos that MUTATE state during recording … film the wrong UI on every re-render"). Re-emittingrealized.jsondoes not fix it either — the data is unchanged; it is the RUN STATE that is dirty. So prefix the command withsource.render_reset.commandverbatim from the handoff (demo-data-setupstep 4b), which clears the run's declaredstate_keys. Wheneversource.render_reset.requiredis true, both halves are mandatory:demo-data-setup-qacheck 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.commandintosetup.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. Onspark-facilitator/ 20260909-2242the copied command pinned 0.13.1413 (pre-ace#2325) and would have re-introducedrun-not-foundon every render; only a hand rewrite caught it. Halt with: "source.render_reset.commandis pinned to<the offending segment>; re-rundemo-data-setupstep 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()inlib/labs-run-state-reset.tsis the exact test check 18 applies. -
Put the effecting actions on the INTERACTIVE dashboard, and only there. Exactly one entry in
source.dashboards[]carriesinteractive: true(role: review-action/review/decision); its run is deliberately leftin_progressso 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 onlywait_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 towait_for/holdand 7 scenes rendered 2 distinct images (dimagi-internal/ace#1162).Unless
source.interactive_live_load.statusisfailed(ace#2430). Anin_progressrun'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 shipscompletedunder an evidenced escape and its control is read-only like every other. Do not author a click against it — it would degrade to aholdand cost the arc exactly what #1162 cost it. Author the finale as the strongest READ beat available and declare check 20's evidencedfinale_is_read, citing that record'scontrol_run_idandupstream_ref. Check the field before you place the payoff; a blank orokrecord means the normal rule above applies unchanged.When
source.payoff_controlis 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 thebelow_programme_scaleescape, 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: onspark-facilitator/20260908-2215the interactive dashboard came fromllo_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 cappeduse_case_soundnessat 3 on it, and the run could not converge.checkEscapedPayoffIsHonoured(lib/ddd-scene-actions.ts) is the gate;demo-data-setup-qacheck 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'sarc_shapecarries 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-qacheck 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, andarc_shapestill 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-1211arc_shapethe finale "inherits that whole table unchanged and adds one line of text and one small chip" 20260909-2242use_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:
- 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.
- 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_soundnesslitmus 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. - 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).
checkArcLadderenforces 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
Paidand 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 onspark-facilitator/20260910-0541neither 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_getthe finale's workflow (id from itspar_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 withscripts/check-render-code-utilities.ts(demo-data-setupstep 3b), then upload withworkflow_update_render_code(orworkflow_patch_render_codefor a small hunk), passing therender_code_versionyou read asexpected_version. Style it withwindow.LabsReportperplaybook/integrations/connect-labs.md§ "Stylerender_codewithwindow.LabsReport". It is the same movecheckEscapedPayoffIsHonoured(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_coherencedefect, not a fix foruse_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 inpersonas),title,show,concept_claim(≥5 words, falsifiable, NO banned marketing phrases),provenance(= a spineid),role: demo, ≥1featurewith non-emptydescriptionANDverify,actions[](from the 17-verb vocabulary), andurl: ${<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 carriesurl— consecutive same-urlscenes reload the page (hal:synthetic-walkthroughanti-pattern); follow-on scenes on the same dashboard omiturland just act/capture. Crossing to a different dashboard = a new scene WITH its${<key>_par_url}. -
The
role: overviewopener — author it HERE, before 3c (ace#2747). canopy'sddd-spec-qarefuses a spec of ≥4 scenes (notstyle: 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'surl, anarrativethat is the goal-setting opening voiceover (the holistic "why"), nofeatures, 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 (bodyScenesinlib/demo-arc-precheck.ts) and tells the text judge it is the title card — a data-less roadmap is not an escalation dead slot. Itsurlstill 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. Atext:selector resolves.first()in DOM order and clicking a non-interactive node succeeds, so the action reports ok while nothing happens. Scene 3'sclick text:Needs a lookmatched three nodes — a card-subtitle DIV, the real LABEL, a reconciliation-sentence DIV — and took the DIV.record_videoreported 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'sparse_targethas no=form, socss=…falls through to the bare-string heuristic — the ambiguity you were trying to escape (ace#1519). -
non-discriminating-gate— await_formust name something only the POST state carries (a count, a status word, the new id).wait_for text:Showingwas 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, failedtarget_not_found, and captured the un-drafted state while the narration described a draft being written. Declare arestore: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
ScrollToActiondeclares onlykind+target, and_ActionBasesetsextra="forbid", sooffset: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_tochasesscroll_into_view_if_neededwith 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— akind: scrollcarrying a raw pixelvaluedecides 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-1345usedkind: scrollfive times ('400','1280','bottom','320','top') against onescroll_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: falseandfive_second_read_correct: falseon 7 of 7 scenes; the run ended at concept 2.0/5. The remedy isscroll_tonaming 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/bottomare 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'sbottomguillotined 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:
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:
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.tscheckArcPrecheck). BLOCKS onsame-surface-component— consecutive scenes on the same resolved surface (the${var}substituted fromrealized.json, query dropped, so two worker-review URLs are one template) settling on the same component (their last heading/tab/landmarkwait_for) — and on a finale whoseconcept_claimstates 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, asddd-arc-evalrequires; 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) mirrorsddd-arc-eval's five dimensions, weights and deduction rules from the installed canopyskills/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:
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: recordedand acuts: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
narrativeopens with "This is a quick overview of how we ." and opens on a live screen (aurl:plus a leadingwait_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 asay:on every action the narration names. - No
role: overviewtitle-card opener is needed (Step 3's opener rule is for the explainer; canopy'sddd-spec-qawaives 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:
(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> …. Afail(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 predatesstyleand adds the music bed back. Recordsteps.demo-narrative.style: recorded(orexplainer) and, for recorded,steps.demo-narrative.recorded_lint: {exit, cuts: [{id, words, est_seconds}]}.
- 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):
(Confirm the exact_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)<kind>tokens fromvalidate()'s dispatch on first use.) Exit0= 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.
-
Write back
narrativerefs +steps.demo-narrative.status: doneviamcp__plugin_ace_ace-gdrive__update_yaml_file(merge: 'deep'). -
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 asdecisions[]rows (live since canopy-web#1516); the old brief lists are retired anddemo_setrefuses them, so never put assumptions, divergences or open questions in the brief.- Write
<path>/board.jsonas a StoryboardIn:slug,title,lede,brief(onlyaudience,purpose,data_disclosure,short_version),decisions[],acts[],capability("comment"or"suggest") andagent_project(the ACE project for the work). - One
decisions[]row per default the set is built on, in plain language. Row fields (canopy-webDecisionIn):id,question,plain_question,options(each at most 8 words),recommended,review_ask,needed_by,evidence_basis,conflict_signals,reasoning. Thereview_ask,evidence_basisandconflict_signalsvocabulary is ACE's shared decision-row vocabulary inlib/decisions-schema.ts(REVIEW_ASKS,evidence_basisstated | inferred | conflicting) - cite it, do not invent values.needed_byhere takes canopy-web's storyboard values (external-share|next-run), not the run-lifecycleNEEDED_BYgates 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 inconflict_signals(at least two) and the resolution inreasoning.
- What a reviewer must answer before the set is shared externally:
- Publish through the pinned wrapper (never a bare canopy call):
(Each Bash call is a fresh shell, so the resolvers are restated here; the form isACE_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)bin/ace-canopy-web --workspace <ws> -- <command>.)demo_setPOSTs 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 theurlit 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.mdfor wording - "Connect", never the retired long form).
- Write
Gotchas
concept_claimis falsifiability-gated byddd-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:
- 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.
- 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. - 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.
provenancemust match a real spineid, and everydemo-role scene needs afeaturewith bothdescriptionandverify— the actionability eval cold-derives a build plan from narration and checks it againstfeatures[].- First-scene-only
urlper surface (see Step 3). - This skill authors + validates only. Rendering, judging, and video are the
DDD loop's job, invoked by
agents/demo.mdafter 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//and send the author back todemo-data-setupstep 4b's self-resolving form;demo-data-setup-qacheck 18 fails the same pin asrender_reset_command_pinned`. |
| 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: 197k | 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 |