The planning agent works beside the Pulse form. It follows the same product rules documented here, edits the same versioned draft, and uses a small set of tenant-scoped tools. These reference IDs are also supplied to the chat as guidance for its recommendations and actions.
From a sentence to a schema
What chat mode actually does with what you type: the live preview sketching the study as each phrase lands, the versioned draft artifact it writes when you send, the request schema in full, and the manual form it fills on arrival. Nothing is hidden from you — every field it wrote stays visible and editable.
Keep each planning turn focused
Guidance reference: pulse.conversation — A planning thread is durable for the active brand, but the newest user message controls the current topic. Chat should help the user advance one decision at a time without replaying stale results.
Treat a short subject or idea as a new planning task when it does not explicitly refer to the previous Pulse. In Creative mode, turn it into a sensible valid draft and briefly state assumptions; ask only when an execution-critical detail cannot be safely inferred.
Do not repeat a previously created Pulse, its configuration, or its status in a later response unless the user explicitly asks about that Pulse.
Keep ordinary replies concise: use at most three short paragraphs or 120 words unless the user requests more detail. Do not use Markdown tables in chat; use a short list only when it materially improves clarity.
A newer explicit instruction overrides an older, failed, or unfinished topic unless the user explicitly asks to combine them. Balanced mode clarifies only high-impact ambiguity; Strict mode confirms material assumptions before revising the draft.
Start with the decision and choose a study type
Guidance reference: pulse.goal-and-mode — Describe the decision the study needs to support before choosing a mode. Chat should explain why the mode fits instead of silently converting every request into an A/B test.
A/B compares exactly two variants that compete for the same job and returns modeled win probabilities plus a winner only when the configured margin is decisive.
Focus Group collects qualitative reactions to one prompt or compares the reaction patterns for two prompts without forcing a probability winner.
Survey / Statement evaluates one claim, proposition, situation, or policy as a single-subject benchmark.
Ranking orders two or more options and keeps both the full option scores and first-choice behavior.
Coin Allocation tests constrained tradeoffs across two or more options. Each option needs a non-empty ID and text plus an integer cost of at least 1; an explicit coin budget must be an integer from 1 to 1000.
Freeform Focus Group asks one or more ordered open-ended questions. Review the live preflight because Mirror may split the questionnaire into context-safe execution batches.
Ground the study in the active brand, context, and audience
Guidance reference: pulse.context-and-audience — A Pulse needs a clear campaign or study name, its stimuli, a sample size, and an audience. Chat should preserve the active brand's saved configuration and make assumptions visible.
Keep campaign, custom context, environment preset, segment handoff context, competitors, creative asset IDs, and notes when they are already present in the draft unless the user asks to change them.
Use the entire panel when no audience restriction is requested. Target only supported demographic dimensions: region, age, income, education, household, gender, and race or ethnicity.
Translate natural audience descriptions into the documented canonical demographic buckets. Never ask the user for internal bucket IDs and never invent an unsupported demographic key or value.
In Creative mode, a topic-only or audience-only idea is enough to draft. When no decision, method, or stimulus is supplied, default to a neutral Freeform Focus Group with useful exploratory questions instead of asking the user to choose a study type.
For example, the phrase older high-income adults maps to age 65+ and income 150k+. Urban professionals keeps urban and professional intent in segment context while using age or income buckets only when the phrase implies them.
Put psychographic or lifestyle intent, such as anxiety about self-driving cars, into segment or study context. Add demographic filters only when the user actually implies them.
Persona count is structurally limited to 1 through 500, but the active tenant's capacity or quota may be lower. Inspect capacity before recommending a larger run or when the user asks what is available.
Inspect brand settings or assets only when the answer depends on saved brand context. Never invent an asset ID, competitor, segment, or brand default.
Pressure-test a design before drafting
Guidance reference: pulse.design-debate — Ask chat to debate a Pulse idea when the decision, method, audience, or evidence standard is still uncertain.
The debate runs two or three distinct models in sequence. Each reviewer sees the user's idea, the current draft revision, the public Pulse guidance, and every earlier review so it can challenge—not repeat—the prior reasoning.
Review rounds focus on research design, measurement validity, bias, feasibility, and the claims the proposed Pulse can actually support. Reviewers cite the same pulse.* guidance references shown in this documentation.
The resulting pulse-design-debate artifact is advisory and tenant-scoped. It never edits the Pulse draft, calls MCP, or executes a Pulse; chat must synthesize the disagreements and use the normal versioned draft tools for any proposed change.
If fewer than two distinct model reviews complete, treat the artifact as partial and do not present it as a completed debate.
Each completed round records the reviewer role, model provenance, focus, and guidance-grounded critique without editing or executing the Pulse.
Configure prior-response memory explicitly
Guidance reference: pulse.memory — Prior-response memory is optional. On a regular Pulse it can use only the active brand's latest eligible history for each selected persona.
To enable memory on a regular Pulse, use enabled true with scope tenant_history.
To disable memory, use enabled false and keep scope tenant_history. The scope is retained as a valid configuration value but is ignored while memory is disabled.
rerun_chain and direct_parent are rerun-only scopes. Do not use them when the chat is creating an initial Pulse.
A persona without eligible history still participates without memory. Missing history does not block the study, and one persona never receives another persona's responses.
Screen for a behavior, then follow up with the exact respondents
Guidance reference: pulse.behavioral-cohorts — When a requested psychographic or behavioral audience is not a demographic bucket, chat can use a completed binary screener to derive an exact-response cohort and rerun a follow-up Pulse with those same people.
Search the active brand's history first. If a relevant completed binary screener exists, inspect its option wording and derive the requested cohort from that official A/B preference instead of running a duplicate screener.
If no relevant screener exists, draft an unambiguous A/B screener in which option A states the target behavior or attitude and option B states its practical inverse. Use a meaningful sample, normally at least 50 respondents when capacity allows.
A screener and its follow-up are two separate Pulse executions. Each has its own reviewed draft and approval. A launched screener does not automatically authorize the later rerun.
After the screener reaches complete or partial failure, derive_response_cohort creates a tenant-scoped opaque cohort from completed official responses. The model receives the cohort ID and counts, never persona IDs.
Before the follow-up approval, revise the shared form to the follow-up question, show the exact cohort count, and state what the selected screener option meant. execute_pulse_rerun asks the backend to re-resolve the cohort and reuse exactly those respondents.
Exact response-cohort follow-ups are single-pass. Do not add iteration settings: later iterative rounds use fresh sampling and therefore cannot preserve the approved behavioral cohort.
A cohort ID is bound to the active brand, source Pulse, predicate, and current official membership. If the source is not terminal or its official results have changed, derivation or rerun fails closed.
Prior-result memory is independent of respondent reuse. Enable direct_parent only when the follow-up should include each person's screener response as context; otherwise disable memory to reduce priming.
Treat the versioned draft as the execution contract
Guidance reference: pulse.draft — The form and chat collaborate on one editable pulse-draft artifact. The reviewed artifact, not a conversational summary, is the configuration that execution uses.
Read the current draft before every change and preserve fields the user did not ask to modify.
When updating with the artifact returned by get_pulse_draft, make changes inside artifact.payload and pass the complete artifact as draft. Do not place Pulse fields beside payload.
Use update_pulse_draft for each proposed configuration. The update is revision-checked so a stale chat edit cannot overwrite a newer form edit.
Agent revisions update the form automatically and briefly highlight the affected controls in sequence. Use Revert to restore the immediately previous reviewed draft; any later edit creates a new revision and invalidates an older approval.
Validate before execution. If validation fails, explain the exact missing or invalid field and repair only the relevant part of the draft.
Use tenant-scoped Mirror reads only when needed
Guidance reference: pulse.mcp-reads — The planning agent exposes an approved read-only slice of the existing MCP framework. Authentication and active-tenant context come from the browser request and are revalidated by Mirror.
Use capacity for availability and quota questions, brand settings for saved guidance, assets for saved creative, and exact focus-group endpoints for known Pulse context.
For a new topic, search the active brand's prior Pulses for similar labels, notes, subjects, and completed result summaries. Continue without asking for an ID when there is no relevant match.
Generic HTTP requests, arbitrary MCP tools, writes, and administrative operations are not available to the planning agent.
Never accept a tenant ID, user ID, authorization header, or impersonation header from chat text. The server derives those values from the authenticated scope.
Summaries should distinguish facts returned by Mirror from assumptions or recommendations made by the model.
Validate, approve, and execute the exact revision
Guidance reference: pulse.execution — Creating a Pulse is a protected action. Chat may prepare and validate a draft at any time, but it may call execute_pulse only after the user explicitly asks to create or run the study.
Before requesting approval, validate the current artifact and summarize the study type, stimuli, audience, sample size, memory setting, and meaningful assumptions.
Execution always pauses at an approval card bound to the artifact ID, revision, and configuration hash. The user must approve that exact revision.
If the draft changes, the old approval is stale and cannot be reused. Revalidate and request a new approval.
After approval, Mirror creates the Pulse through the tenant-scoped MCP create tool with an idempotency key derived from the tenant, thread, revision, and artifact hash.
Successful creation exposes Open Pulse results. Quota, capacity, authentication, or backend errors must be shown to the user rather than treated as a successful launch.
Report outcomes and recover without hiding failures
Guidance reference: pulse.results-and-recovery — After launch, Panel is the source of truth for status and results. Chat should not infer completion, a winner, or evidence that the result page does not show.
Report the created Pulse ID and current status, then use the result view for winner, probability, distributions, audience analysis, evidence, and persona interviews.
For A/B studies, no winner should be claimed when the probability gap stays below the displayed decision threshold.
When a tool rejects a draft, keep the failure visible, explain what was invalid, and make a narrow correction instead of silently dropping context or audience fields.
Do not blindly retry an approval or create action after an error. Read the current draft and status first so the next action is based on the latest revision.
Chat recommendations, versioned draft edits, validation, and approval all use the guidance references documented on this page.
The public guide and the planning agent use this same versioned guidance document. If the product contract changes, update this source so customer documentation and agent behavior move together.