> ## Documentation Index > Fetch the complete documentation index at: https://docs.bitfab.ai/llms.txt > Use this file to discover all available pages before exploring further. # Scenarios > Capture the situation a run was in, label what it got right or wrong, and turn the label into assertions ## Overview A **scenario** is the situation one run of a traced function was in: the trigger that started the run and the data available when it arrived, with a name and a description. It is built from one source trace. A scenario describes the situation only. It never says what the run did or should have done. That separation is what makes it reviewable. A person reads the situation, says what the right outcome was, and Bitfab turns that label into [assertions](https://docs.bitfab.ai/primitives/assertions.md) on the source trace. > [!NOTE] > > Scenarios are in beta. The **Scenarios** page in the sidebar carries a beta badge, and the details on this page may change as the feature settles. Scenarios matter most for agents whose runs depend on more than their input, such as an assistant that reads a user's messages, calendar, and contacts before it acts. The trace shows what the run looked at. The scenario records everything it had, including what it missed, so a reviewer can judge whether the run did the right thing with what was there. ## What a Scenario Holds | Part | What it is | | - | - | | **Trigger** | What started the run, such as an inbound message, with its channel, sender, and time | | **Data** | What was available when the trigger arrived: earlier conversation history and records such as messages, contacts, memories, and calendar events | | **What the run didn't have** | Items the run needed and could not see | | **Where the data came from** | For each kind of data, whether it was **Read in full** as of the run or **Not fully read**. A record missing from a kind that was not read in full is never proof it did not exist | | **What actually happened** | A summary of what the source run did and the actions it took, in order. It is one example of how the run went, not what should have happened, and it is never used as evidence for assertions | | **Categories** | Any number of [categories](https://docs.bitfab.ai/primitives/categories.md) the scenario is filed under | Each record that Bitfab finds in one of the trace's spans cites that span, so an assertion drafted from it can point at the evidence. ## Creating Scenarios A scenario is created in one of these ways: * **Adding a trace to a dataset.** The trace is linked to an empty scenario. When your organization has a [scenario callback](https://docs.bitfab.ai/scenario-callback.md), Bitfab also starts building it. * **Saving an assertion on a trace**, or filing the trace under a category. The trace gets an empty scenario to hold its categories. * **Asking for one.** Your coding agent calls `generate_scenario`, or your code calls `traces.generateScenario`. Either starts the build in the background and returns at once. * **Saving one directly.** Your coding agent calls `save_scenario`, or your code calls `traces.saveScenario`, with the trigger and data. A build needs something that knows your data. The usual way is a [scenario callback](https://docs.bitfab.ai/scenario-callback.md): a URL in your own system that Bitfab calls with the trace, and that answers with the trigger, data, and records your system held when the run happened. Without one, your coding agent can read the trace and save the trigger and data with `save_scenario`. An empty scenario stands in until it is built. Its trace's input and output take the place of its trigger and data, so it can still be labeled. ### Creation status Every scenario shows how far building it has come. | Status | Meaning | | - | - | | **Not generated** | Nothing has started building it | | **Generating** | Bitfab is building it, or waiting for your scenario callback to save it. The page updates on its own when it is ready | | **Created** | Built | | **Generation failed** | Building failed. The reason is shown on the scenario | Asking for a build while one is running starts nothing more. Asking again for one that failed starts it over. To rebuild a scenario that was already created, for example because your callback came back empty the first time, pass `regenerate: true`. That clears and rebuilds its name, description, trigger, data, and actual outcome, and keeps its categories, review status, labels, and assertions. ```typescript TypeScript theme={null} await client.traces.generateScenario(traceId, { regenerate: true }) const scenario = await client.traces.getScenario(traceId) ``` ```python Python theme={null} client.traces.generate_scenario(trace_id, regenerate=True) scenario = client.traces.get_scenario(trace_id) ``` In Ruby pass `regenerate: true`, and in Go `bitfab.WithRegenerate()`. ## Reviewing Scenarios Open **Scenarios** in the sidebar. The page has three tabs, each with a count. | Tab | Holds | | - | - | | **Inbox** | Scenarios waiting on a person: ones to label, drafts to review, and fixes to check | | **Done** | Scenarios that are fully reviewed | | **All** | Every scenario | The **Filter** menu narrows the list by status, by whether the scenario was generated, by dataset, and by category. It shows generated scenarios by default, so switch it to **Not generated** or **All scenarios** to see empty ones. Move between scenarios with `j` and `k`, or the **Next** and **Back** buttons. `⌘ Enter` runs the main button. The page moves on to the next scenario as soon as you act, without waiting for the save. ### Labeling a run **1. Read the situation** Read the trigger, the conversation history, what the run didn't have, and where the data came from. **Open trace** shows the source trace beside it. **2. Write the label** In the **Label** box, answer "What should the run have done here, and what did it do instead?" in plain words. **3. Generate assertions** Press **Generate assertions**. Bitfab drafts up to four assertions from your label, the trigger, the history, and the records the run saw. Records the run never saw are context only. Each draft is checked against the [writing rules](https://docs.bitfab.ai/primitives/assertions.md#guided-rewrite) before it is shown. **4. Review the drafts** Set each draft to **Approve**, **Pending**, **Archive**, or **Edit**, and use **Show why** to read the spans it cites. Press **Save & next**, or **Update with changes** when you marked a draft for editing. A label that gives nothing a replay could be checked against yields **No assertions drafted**. Accept the scenario without assertions, or rewrite the label and draft again. ### When the scenario itself is wrong Sometimes the problem is the scenario, not the run: a missing message, a wrong trigger, or a record that should be there. Press **Needs updating** and write what is wrong instead of labeling the run. The scenario leaves the inbox until it is fixed. Your coding agent finds these with `list_scenarios` and fixes them with `save_scenario`, sending a note on what it changed. The scenario then comes back to the inbox as **Updated**, showing what you asked for and what changed. Press **Looks right** to confirm the fix, or flag it again. ``` Fix every scenario on support-agent that needs updating ``` ### Review status Each scenario has one review status, which the **Status** filter uses. | Status | Meaning | | - | - | | **Needs label** | Nobody has said what the run should have done | | **Drafting** | Bitfab is drafting assertions from the label | | **Drafting failed** | Drafting did not finish. Retry it, or send the label again | | **No assertions** | The label gave nothing a replay could check | | **Needs review** | Drafted assertions are waiting for approval | | **Needs updating** | A person flagged the scenario itself as wrong or incomplete | | **Updated** | The flag was resolved, and the fix is waiting to be checked | | **Done** | Fully reviewed | ## Opening a Trace's Scenario The trace panel on the **Traces** page and in dataset review has a **Scenario** button that opens the scenario built from that trace. While the scenario is being built, the button shows a moving border and becomes clickable once it is ready. It is disabled when no scenario has been built from the trace. ## Tools and Methods | Operation | MCP tool | TypeScript SDK | | - | - | - | | List scenarios by review status | `list_scenarios` | Not available | | Read a scenario | `get_scenario` | `traces.getScenario` | | Start or rebuild a scenario | `generate_scenario` | `traces.generateScenario` | | Create or edit a scenario | `save_scenario` | `traces.saveScenario` | | Draft assertions from a label | `generate_scenario_assertions` | Not available | | File a trace's scenario under categories | `save_trace_categories` | Not available | The SDKs find a scenario by its trace id. Python and Ruby use snake\_case names, and Go uses `GetScenario`, `GenerateScenario`, and `SaveScenario`. See the [Claude Code plugin](https://docs.bitfab.ai/claude-plugin.md#list_scenarios) reference for every tool argument and the [TypeScript reference](https://docs.bitfab.ai/reference/typescript.md#read-and-update-a-scenario) for the SDK shapes. ## Best Practices * **Set up a scenario callback.** It is how Bitfab gets the data your system held at the time of the run, which a trace alone does not show. See [Scenario callback](https://docs.bitfab.ai/scenario-callback.md). * **Label the outcome, not the steps.** "It should have offered the refund the customer asked for, not a store credit" drafts better assertions than a list of tool calls. * **Flag the scenario, not the run, when data is missing.** An assertion drafted from an incomplete scenario checks the wrong thing. * **Add labeled traces to a dataset.** The assertions you approve only protect the trace when an experiment replays it. See [Datasets](https://docs.bitfab.ai/primitives/datasets.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.