Stage 2 of ACE Phase 7 (Plan B). Reads the narrative plan and the persona
catalog (canned + opp-specific overlays) and emits one walkthrough spec
YAML per persona. Each spec is the input to a canopy:walkthrough run via
the synthetic-walkthrough-run skill.
-
Discover personas.
- Always include
prospective-llo and funder from the plugin's
personas/ directory (canned catalog).
- Additionally, read
ACE/<opp>/personas/ (Drive). Any *.md file
there is treated as an opp-specific persona — if its name
collides with a canned one, the opp-specific overlay wins
entirely (no merge — the opp file is the authoritative version).
- Operator can override the persona set with
--personas <comma-list>
(e.g., --personas funder to skip prospective-llo this run).
-
Read inputs. Load the narrative plan, manifest, data-generate
summary, opp.yaml, and each persona file via drive_read_file /
the local personas/ files (filesystem read for canned).
If synthetic-narrative-plan.yaml is missing, halt with: "Run
/ace:step synthetic-narrative-plan --opp <slug> first — this skill
composes specs from the narrative plan."
If synthetic-data-generate.md is missing, halt with: "Run
/ace:step synthetic-data-generate --opp <slug> first — specs need
the labs URL and fixture folder."
-
Derive scene plan per persona.
For each persona, work through 5–8 scenes that map their priorities
to actual labs URLs the synthetic data populates. The shape varies by
persona; common scene types (atomic-visit archetype):
- Headline panel — the opp's labs page top-of-screen, KPI numbers
visible. Wow: a specific number from the manifest's record_counts
("138 visits in 4 weeks across 50 vendors").
- FLW roster — the per-FLW page. Wow: a named FLW the manifest
features — "Asha M. delivered 38 visits at 92% completeness."
- Single-FLW deep-dive — drill into the rockstar OR the
struggling FLW, depending on persona priority. Wow: archetype
marker visible (e.g., "rockstar" badge or a "needs review" flag).
- Anomaly callout — a labs page that surfaces one of the
manifest's seeded anomalies. Wow: the anomaly is visibly marked
with context, not just a flag color.
- Coaching task drawer (Stage 3) — Skip in Stage 2; Stage 3
synthetic-workflow-seed lights this up.
- Visit map / list (atomic-visit) — geographic coverage. Wow:
density pattern, refusals visible, no mystery clusters.
- Quality verification flow (funder priority) — Layer A/B/C
visible if the opp has them configured. Wow: each layer has a
concrete number (Layer A pass-rate, Layer B AI agreement, Layer C
human spot-check coverage).
- Cost / per-visit panel (funder priority) — the budget line vs
what's been delivered. Wow: a $-per-verified-visit number.
-
Assemble the YAML spec. Use the canopy:walkthrough schema —
see ~/.claude/plugins/marketplaces/canopy/plugins/canopy/skills/walkthrough/SKILL.md
for the canonical contract. Shape:
name: "<opp-slug>-<persona>-walkthrough"
narrative: "<one-line thesis tuned to the persona>"
base_url: "${LABS_BASE_URL}"
auth:
type: command
check: "test -f ~/.ace/labs-session.json && bash ~/.claude/plugins/cache/ace/ace/$(cat ~/.claude/plugins/marketplaces/ace/VERSION)/bin/ace-labs-walkthrough-login"
login: "bash ~/.claude/plugins/cache/ace/ace/$(cat ~/.claude/plugins/marketplaces/ace/VERSION)/bin/ace-labs-walkthrough-login"
personas:
<persona-key>:
name: "<persona display name>"
role: "<persona role line>"
color: "<hex>"
intro: "<one-sentence intro from the persona file>"
scenes:
- persona: <persona-key>
title: "<scene title>"
show: "<one-line description of what to capture; URL hint OK>"
impressive_because: "<the wow moment — name a specific number/name from the manifest>"
ai_quality: "<assertion the canopy walkthrough's AI judge can check, e.g.,
'KPI panel must show ≥3 named FLWs with archetype labels visible'>"
Critical authoring rules:
- Every
impressive_because must reference a concrete element from
the manifest (a named FLW, a specific anomaly, a KPI threshold).
Generic "looks good" entries get rejected by the eval (Stage 4).
- Every
ai_quality must be falsifiable — name what an AI judge
should look for, not just "the page should be nice." Use language
the canopy walkthrough's LLM-as-Judge can apply.
- Map at least one scene to each anomaly the manifest seeded —
otherwise the data work in
synthetic-data-generate is wasted.
- Order scenes by narrative arc, not by URL convenience: open with
the headline, build via FLW roster, climax at the anomaly +
coaching loop, close with cost / verification.
- Workflow-dashboard scenes (LLO Weekly Review / Program Admin
Audit) MUST target the saved-run render deep-link, not the bare
workflow URL. Use the
/labs/workflow/<id>/run/?run_id=<run_id>&opportunity_id=<opp>
links recorded in synthetic-workflow-seed.md (Render deep-links).
The bare /labs/workflow/<id>/?opportunity_id=<opp> renders the run
picker, not the polished per-FLW dashboard — a scene pointed there
captures the picker and the AI judge sees no hero/FLW content. If
synthetic-workflow-seed.md is absent or recorded no saved run, omit
the workflow-dashboard scenes rather than linking the picker. (Recipe
verified live; jjackson/ace#769.)
-
Pick the labs base URL. Default to https://labs.connect.dimagi.com.
Read LABS_BASE_URL from ${CLAUDE_PLUGIN_DATA}/.env if set; that
override is mainly for staging environments.
-
Validate the spec. Before writing each YAML:
- Required keys present:
name, narrative, base_url, auth,
personas, scenes (with at least 4 scenes).
- Every
scenes[].persona matches a key in personas.
- Every URL referenced is under
base_url (no absolute URLs to
other domains).
If validation fails, halt and surface the failure to the operator.
Don't write a malformed spec.
-
Write each spec to
7-synthetic/synthetic-walkthrough-spec_<persona>.yaml via
drive_create_file (find-or-update; re-runs overwrite).
-
Update run_state.yaml via the read-merge-write pattern:
phases:
synthetic-data-and-workflows:
steps:
synthetic-walkthrough-spec:
status: done
personas:
prospective-llo:
status: done
spec_artifact: <Drive ID>
scene_count: <int>
funder:
status: done
spec_artifact: <Drive ID>
scene_count: <int>
