| name | pdp-narrative-experiments |
| description | Translate an ad / campaign narrative into a PDP A/B experiment variant on staging. Auto-activates whenever an operator pastes ad copy, a creative brief, a positioning angle, a story / messaging direction, or any "test this narrative on the product page" request — even if they don't explicitly say "experiment" or "A/B". Samples the brand voice from sibling PDPs, decomposes the narrative into beats, maps beats to widget changes, validates against first-fold rules and edit-safety markers, previews the change for operator approval, then writes the variant via admin-mcp. Use this skill (not the simpler experiment-manager) whenever the change is driven by a story / angle / persona rather than a single isolated image or copy swap. Requires admin-mcp. Staging-only — production publish goes through Zeus admin UI.
|
PDP Narrative Experiments
You translate an advertising narrative into a concrete PDP variant on staging. The
operator gives you a story; you produce a variant PDP, a story-map preview, and a
traffic split. Production cutover is not in your scope — middleware will refuse it
anyway when x-mcp-source: admin-mcp.
When to activate
- User pastes a narrative / ad copy / campaign brief and names a product or PDP.
- User asks "test this angle on the X PDP" / "create a PDP variant from this story" /
"build narrative variant" / "run an A/B with this positioning".
- The
experiment-manager agent receives narrative-shaped input and delegates here.
If the user is creating a generic A/B test (e.g. just wants to swap a hero image with
no narrative angle), stay out — the standard experiment-manager flow is simpler.
Reference layout
Heavy logic lives in three references plus a bundled widget spec snapshot. Load only
what you need — do not duplicate content here.
Skill logic (read once per flow stage)
| Reference | Use it for |
|---|
${CLAUDE_PLUGIN_ROOT}/references/admin/narrative-experiment-flow.md | End-to-end orchestration: per-step admin-mcp tool calls, permissions, error recovery, handoff |
${CLAUDE_PLUGIN_ROOT}/references/admin/pdp-narrative-compilation.md | The 7-beat schema, voice sampling, beat→widget mapping, modifications list shape |
${CLAUDE_PLUGIN_ROOT}/references/admin/first-fold-rules.md | Anchor validator (positional rules + algorithm + ✅/❌ examples) |
Bundled widget spec (PRIMARY entry point + drill-down)
widget-index.json is your hot-path lookup. Load it ONCE at layout-planning time
and consult it for every widget decision. Only drill into per-widget markdown when
the index doesn't carry enough detail for a specific field-level decision.
| Spec | Use it for | Load when |
|---|
${CLAUDE_PLUGIN_ROOT}/references/admin/pdp-widget-specs/widget-index.json | PRIMARY — flat lookup of all 58 PDP-relevant widgets: type → narrative role, edit-safety summary, header/layout support, spec path | Once, at the start of layout planning |
${CLAUDE_PLUGIN_ROOT}/references/admin/pdp-widget-specs/narrative-index.md | Widget grouping by the 12 narrative codes — use when designing the below-fold narrative arc | Once, at layout planning if you need narrative-code-first browsing |
${CLAUDE_PLUGIN_ROOT}/references/admin/pdp-widget-specs/widgets/<TYPE>.md | Per-widget field tables, real examples, gotchas, fine-grained edit-safety markers | DRILL-DOWN — only when planning a non-trivial edit on a specific widget |
${CLAUDE_PLUGIN_ROOT}/references/admin/pdp-widget-specs/widgets/_common.md | header / layout / Media / CTA / SliderConfig primitives | When editing fields that use these shared types |
${CLAUDE_PLUGIN_ROOT}/references/admin/pdp-widget-specs/widgets/_conventions.md | The 12 narrative codes + edit-safety classification definitions | If you forget what HERO vs STORY vs PROOF means |
Companion skill: admin-essentials (auto-activates alongside) — brand resolution,
URL→identifier rules, staging guardrail, common gotchas.
The flow (7 stages)
0. AUTH PRE-FLIGHT → resolve_brand to surface caller's permission context
1. DISCOVERY → find the control PDP, fetch its config, sample sibling PDPs for voice
2. DECOMPOSITION → extract the 7 beats from the narrative (LLM)
3. LAYOUT PLANNING → beats → widget modifications, top-fold and below-fold zones
4. VALIDATION → first-fold rules + edit-safety + claim guard
5. PREVIEW & ITERATE → render story map, operator iterates until approved
6. WRITE → acquire lock → create_pdp_experiment → diff sanity → release lock → update_experiment_assignment
7. HANDOFF → preview URLs + QA checklist + reminder that prod publish is via Zeus UI
Full per-step tool calls and permission requirements: see narrative-experiment-flow.md.
Hard rules
These cannot be relaxed without breaking real PDPs. Verify before every write.
First-fold anchors are sacred
The first six widgets (widgets[0..5]) MUST contain, in canonical order:
- A gallery anchor —
type ∈ {CAROUSEL_WITH_THUMBNAIL, EXPANDED_MEDIA} (exactly one)
- (Optional)
type === "TAG_MEDIA" — brand-mark, present only when control authors one
type === "PRODUCT_SUMMARY" (exactly one per PDP)
The skill only edits content on these anchors — never adds, removes, swaps types,
or reorders them. Callouts may interleave between them within widgets[0..5].
Validator algorithm and examples: first-fold-rules.md.
Run the validator BEFORE every call to create_pdp_experiment. Surface specific
failure messages to the operator; refuse to write if validation fails.
Edit-safety per field
Every modification carries an edit-safety class derived from the widget's spec field
table:
- 🟢 AI-safe — copy, alt text, simple text fields. Rewrite freely.
- 🟡 Sensitive — claims, prices, regulatory copy, brand assets. Flag in preview;
operator must explicitly approve.
- 🔴 Structural — ids, slugs, action wiring, SKUs, type strings. Never touch.
If compilation produces a 🔴 modification, drop it and regenerate that piece.
The per-widget edit-safety summary is in widget-index.json under each entry's
edit_safety_summary. Drill into widgets/<TYPE>.md when you need per-field detail.
Compliance / claim guard
Before generating any new copy, sample 2–3 sibling PDPs on the same brand to build an
allowed-claim-verb whitelist. Never introduce a claim verb absent from the samples
(common forbidden verbs on health brands: cure, guarantee, prevent, treat, diagnose,
100%, no side effects). If the operator's narrative requires a forbidden verb, flag
it in the preview — operator must explicitly approve before write.
Staging only — no exceptions
environment: "staging" on every write. The skill does not call publish_experiment
(disabled via MCP anyway). Middleware additionally refuses any
x-mcp-source: admin-mcp + env=prod|production with a 403.
To publish to production, the operator uses the Zeus admin dashboard. Say this in
every handoff.
Operator inputs
Required at the start of the flow:
- Narrative — free-form text (ad copy, brief, positioning angle).
- Brand — display name, alias, or short code.
resolve_brand normalizes.
- Product — URL key, product name, or control filename.
search_products /
list_pdp_pages resolve.
Optional:
variant_count (default 1; max 2 in v1)experiment_name override (default: derived from beats, kebab-case)traffic_split (default 50/50 control vs variant)
Error handling (the common cases)
| Symptom | Skill response |
|---|
Auth returns reason: "no_permissions" | "Your Zeus API key has no admin permissions. Ask a Zeus admin to grant all_pages (view + edit) to your role." Halt. |
Tool denies with missing.brand | "Your role doesn't include ${brand}. Available: ${ctx.brands}. Pick another brand or ask Zeus admin to expand your role." Halt. |
Tool denies with missing.language | "Your role doesn't include ${lang}. Defaulting to en?" — confirm with operator. |
Auth + brand pass but all_pages.edit missing | "Your role can view but not edit all_pages on this brand. The variant write will be denied. Ask Zeus admin to grant edit." Halt before compilation. |
| First-fold validator fails | Surface the specific failure (missing anchor / wrong order / outside window). Offer regeneration; if 2 regenerations fail, ask operator to refine the narrative. |
| 🔴 modification proposed by compiler | Drop silently and regenerate just that piece. |
| 🟡 modification on a new claim | Flag in preview with explicit operator confirmation required. |
| Lock held by someone else | Surface owner + expiry. Offer "retry after expiry" or "cancel". |
| Compare-to-control diff shows unexpected paths | Halt before traffic assignment. Show operator the anomaly. Roll back via update_experiment_assignment to 100% control if needed. |
| Mid-flight cancel | If lock acquired, release it. Never leave staging in inconsistent state. |
Detailed recovery semantics: narrative-experiment-flow.md § Error recovery and rollback.
Audit (automatic — don't fire it yourself)
Every write goes through admin-mcp's safeWrite wrapper. Audit entries land in Zeus
Activity Log automatically:
create_pdp_experiment → entity_type: "experiment", entity_id: <experiment_page_name>update_experiment_assignment → entity_type: "experiment", entity_id: <identifier>
Mention this in the handoff so the operator knows where to verify.
What the skill does NOT do (out of scope for v1)
- Generate >2 variants from one narrative (v2)
- Cross-language variant generation in one run (operator re-runs per language)
- Monitor / measure lift (separate Mixpanel skill family)
- Auto-promote a winner (separate
promote_experiment_to_control flow)
- UTM-scoped splits (supported by
experiment.json but not exposed in v1 inputs)
- Edit the legacy section pipeline — only widgetized PDPs
Handoff template
After a successful write, output to the operator:
✅ Experiment created on staging
Variant: <experiment_page_name>
Control: <control_page_name>
Brand: <brand>
Traffic: control X% · <variant> Y%
Audit: logged in Zeus Activity Log under entity_type=experiment
Staging preview URLs:
- Control: <preview_pdp_url for control with mwexp cookie in control bucket>
- Variant: <preview_pdp_url for variant with mwexp cookie in variant bucket>
QA checklist:
☐ Visual diff: both URLs side-by-side, mobile + desktop
☐ First-fold anchors still in canonical order
☐ All 🟡 flagged claims read as intended
☐ Mixpanel EXPERIMENT_VIEWED firing on the variant
☐ ATC / Buy Now still works on the variant
⚠ Production promotion is NOT available via MCP. To publish, log in to Zeus
admin dashboard and publish the variant + assignment from the All Pages
and Experiment Assignment tools.
