Running your first simulation

A simulation asks a group of digital twins to make one decision, then reports where they landed. Five fields define it, and the quality of the answer depends almost entirely on how carefully you fill them in. This guide walks through each field, a complete worked example, and the checks worth doing before you show the result to anyone.

Start from the decision, not the tool

Before you open a workspace, write down the decision the result will feed and what you would do differently depending on the answer. If every plausible outcome leads to the same action, the simulation is not worth running yet. If one outcome would change your plan, that outcome is what the run needs to be able to detect, and it tells you how to shape the fields below.

The five fields

1. 01PopulationWho is being asked. Pick one you have already built, or describe a new one and let the agent assemble it. Match it to the people whose choice decides the outcome: if parents buy and children choose, you may need both.
2. 02DateThe moment the scenario is set in. This is not the date you run it. Asking about August 2026 and August 2019 are different questions, and twins reason from what was true then: prices, norms, the alternatives on offer.
3. 03ScenarioThe situation each twin is placed in. Concrete beats abstract: 'deciding a tip on DoorDash after ordering' produces sharper reasoning than 'thinking about tipping'. Name the place, the moment and what the person can see.
4. 04QuestionWhat each twin is actually asked, in the second person, as a person would hear it. One decision per question.
5. 05Action spaceEvery option a twin may resolve to. At least two. Twins must end on one of them, so leaving out a real option forces an artificial answer.

A worked example

Here is a complete setup for a question a delivery app might ask before changing its checkout screen.

Writing a scenario and question that do not lead

Twins respond to wording the way people do, so the same habits that spoil a survey spoil a simulation.

• Describe, do not sell'A new drink with 150mg of caffeine, priced at $3.49' gets a fairer read than 'an exciting new energy drink'. Adjectives are your opinion, and twins pick it up.
• Keep your hypothesis outDo not mention the outcome you expect or the option you prefer. If the scenario explains why the new price is fair, you are testing the explanation, not the price.
• Show what the person would seeIf the real decision happens on a shelf next to three rivals, put the rivals in the scenario. A choice made in isolation is a different choice.
• Ask one thing'Would you buy it and recommend it?' is two questions. Split it into two runs, or into a single action space that covers the combinations.

Writing an action space that holds up

The most common way to get a misleading result is an incomplete action space. If the honest answer for part of your population is “I would not order at all”, and that option is missing, those twins are pushed into a choice they would not make and your percentages shift.

• CompleteInclude doing nothing, keeping what they have now, and leaving. These are usually the largest real-world answers and the easiest to forget.
• Mutually exclusiveEach twin should fit exactly one option. Overlapping bands like '10–15%' and '15–20%' blur the result at the boundary.
• Even in detailDo not split your favoured option into five variants while leaving the alternative as one. The finer side collects less per option and looks weaker than it is.
• Worded as actions'Buy the 12-pack' is clearer than 'Positive'. Options that describe what the person does resolve more consistently than options that describe how they feel.

If you are not sure the space is complete, run it once with a catch-all option. If the catch-all takes a meaningful share, you are missing a real branch. Open those twins and read what they would have done instead; that is usually the option to add.

Reading the result

A finished run gives you a distribution across the action space, a confidence level, and the individual twins behind it. Read them in this order.

1. 01ConfidenceDecides how much weight the rest can bear. High supports the ranking and rough size; lower means treat the run as a hypothesis.
2. 02The twinsOpen a handful from each option. The percentages tell you what happened; the transcripts tell you why, and the why is what survives contact with a decision.
3. 03SegmentsSplit by the groups your decision cares about. A flat overall result often hides two segments moving in opposite directions.
4. 04The percentagesLast, and as approximate. Differences of a few points between close options are usually inside the noise of a single run.

Confidence is measured, not asserted. It reflects how closely this population has matched held-out humans on questions it had not seen. Treat a high-confidence run as reliable for direction and ranking, and the exact percentages as approximate.

Changing one field at a time

The comparison view is the point of the tool. Run the same population and question against two dates, or two scenarios, and the difference is attributable. Change several fields at once and it is not. When you test a new price, keep the scenario wording identical apart from the number; when you test new wording, keep the price fixed.

Before you share a result

• The dateIs it the moment the decision happens, not today by default?
• The action spaceDoes it include doing nothing and leaving?
• The wordingWould a neutral colleague read the scenario as fair?
• The confidenceIs it stated next to the headline number?
• The reasonsCan you quote two or three twins who explain the result?