Stage 3.2 of ACE Phase 7 (Plan B). The synthetic-workflow-seed skill
instantiates the SEED templates with opp-agnostic render code; this
skill applies surgical edits to make the dashboards look genuinely
tailored to a specific opp's data. The polish step is what moves a
demo from "competent" to "amazing."
-
Read inputs. Load the narrative plan, workflow seed summary,
opp.yaml, the current run's run_state.yaml, and the PDD via
drive_read_file. Resolve llo_weekly_review_id from
phases.synthetic-data-and-workflows.products.synthetic.workflows.llo_weekly_review_id
in the current run's run_state.yaml. Halt if missing: "run
synthetic-workflow-seed first (in this run)."
Read scaffold_unsuitable from the workflow seed summary. Branch:
false (default) → step 2 (surgical patches)true → step 4 (full rewrite)
-
(Surgical mode) Fetch current render code.
For each workflow in the polish scope (LLO weekly + program admin):
mcp__connect-labs__workflow_get(
workflow_id: <id>,
opportunity_id: <synthetic.labs_opp_id>,
include_render_code: true,
)
Capture render_code, render_code_version. The version is
required by every subsequent workflow_patch_render_code call as
expected_version.
-
(Surgical mode) Compose + apply patches.
Polish surface (atomic-visit archetype):
- Hero panel. The seed's
<header><h1>{definition.name}</h1>
becomes a richer headline showing the opp's signature metric. For
turmeric: "850 vendor visits · 92% photo-quality verified · 5
FLWs across 26 markets". Numbers come from the manifest's
record counts and KPIs.
- Named FLW story cards. Replace the generic
workers.map(...)
row rendering with per-FLW cards that name the FLW (Asha M.,
Dinesh P.) and surface their archetype label + a one-line note
from manifest.flw_personas[].notes.
- Anomaly callouts. For each entry in
manifest.anomalies, add
a "needs attention" badge on the affected FLW's card with the
anomaly's plain-language description (NOT the field path —
"photos missing MTN card" beats form.location_id.photo).
- Coaching arc visualization. For each
manifest.coaching_arcs entry, add a small inline timeline
rendering: detection-week → coaching-task → follow-up-week
improvement number.
⚠️ Do NOT assert a per-period delta the snapshot cannot show
(jjackson/ace#764). The LLO-review flw_kpis rollup is NOT
period-filtered — Week 1 and Week 2 snapshots render identical
numbers (labs-side root cause). Static "by Week 3, +18%" text baked
from manifest.coaching_arcs is then a falsified claim: the snapshot
it renders on shows no such change. Keep any week-referencing /
improvement-delta narrative conditional on a genuinely distinct
per-period figure being present in the rendered state; if the
figures are identical across periods, render the coaching arc as a
forward-looking plan ("coaching assigned; follow-up next cycle")
rather than asserting a realized improvement. (Mirrors the
synthetic-workflow-seed step-8 warning.)
- Domain branding. Pick icons + language matching the PDD's
domain. Turmeric → market/vendor language; KMC → maternal-health
iconography; vaccine focus group → immunization framing.
For each patch, call:
mcp__connect-labs__workflow_patch_render_code(
workflow_id: <id>,
opportunity_id: <synthetic.labs_opp_id>,
search: "<exact substring from current render_code>",
replace: "<new substring>",
expected_version: <fetched in step 2; bumps after each successful patch>,
)
Each patch must be a single exact-match replacement; the labs side
refuses ambiguous patches (count != 1). Bump expected_version
after each successful call.
Patch ordering. Apply outer-shell patches first (hero panel,
header), then inner-loop patches (per-FLW cards), then leaf
adornments (anomaly badges). This minimizes search-string drift —
inner patches don't get invalidated by outer changes.
-
(L2-rewrite mode) Replace render code wholesale.
When scaffold_unsuitable: true, the seed's per-FLW-aggregate
shape doesn't fit the opp's KPI model. Compose a bespoke JSX
render based on the manifest + PDD, then:
mcp__connect-labs__workflow_update_render_code(
workflow_id: <id>,
opportunity_id: <synthetic.labs_opp_id>,
component_code: "<full JSX>",
expected_version: <from step 2 fetch>,
)
The full-rewrite path is rare — most ACE atomic-visit and
focus-group archetypes work with the SEED scaffold's per-worker
shape. Plan B's design § 4.4 calls this "L2 mode."
-
Smoke render.
After applying patches (or wholesale rewrite), verify the workflow
doesn't crash by calling pipeline_preview on its primary
pipeline:
mcp__connect-labs__pipeline_preview(
pipeline_id: <from workflow_get's response>,
opportunity_id: <synthetic.labs_opp_id>,
sample_size: 10,
)
If the preview returns rows, the pipeline is healthy. If it returns
a schema validation error, the patch broke the render's data
contract — surface in the run summary as a [WARN] and recommend
the operator open the workflow in labs UI to inspect.
Also check for silently-zeroed filtered counts (jjackson/ace#595).
The preview returning rows is NOT sufficient. If the schema has count
fields with a filter_path/filter_value that share a field_path
with a bare last/first/list field, the labs SQL generator
collapses the shared-path extraction and the filtered counts read 0
(not null — so no schema error fires). Inspect the preview: any
filter_path count field that is uniformly 0 across rows that have
data is the smoking gun — remove the colliding bare aggregation on that
path (see synthetic-workflow-seed § Step 4 shared-path guardrail) and
re-preview before declaring the pipeline healthy.
We can't yet headlessly screenshot the rendered JSX from this
skill (would require driving the labs UI through Playwright);
visual eval lives in synthetic-workflow-polish-eval (Stage 4).
-
Write the run summary to
7-synthetic/synthetic-workflow-polish.md via drive_create_file
(find-or-update). Body:
- Per-workflow patches applied: one row per patch with the
intent label (e.g., "hero panel", "Dinesh story card", "MTN-card
anomaly badge")
- Final
render_code_version per workflow
- Smoke result:
pipeline_preview row count or error
- L2-rewrite flag if step 4 fired
-
Update run_state.yaml via the read-merge-write pattern:
phases:
synthetic-data-and-workflows:
steps:
synthetic-workflow-polish:
status: done
mode: <surgical | l2-rewrite>
patches_applied:
llo_weekly_review: <int>
program_admin_audit: <int>
render_code_versions:
llo_weekly_review: <int>
program_admin_audit: <int>
artifacts:
summary: <Drive ID>
