> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chronicle-labs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Write a good brief

> Give Worldsmith the starting evidence, the agent's job, and observable checks for success.

A good brief describes the system you want to simulate: what the agent can
access, its starting state, what the agent must do, and how you will grade the
result. Use the duplicate-invoice workflow as a starting
point: begin engineering triage and notify finance while the customer case stays open.

## Include six details

<div className="chronicle-guide-panel frame-dotted frame-crosses">
  <div className="chronicle-guide-panel-header">
    <p className="chronicle-guide-label">Brief anatomy</p>
    <h3>A triage task with evidence and checks</h3>
  </div>

  <div className="chronicle-brief-fields">
    <div><p className="chronicle-brief-term">System and agent role</p><p>Acme's invoice workflow, with an operations agent handling a duplicate invoice.</p></div>
    <div><p className="chronicle-brief-term">Services</p><p>Slack, Linear, Salesforce, and SAP S/4HANA with shared people and customers.</p></div>
    <div><p className="chronicle-brief-term">Starting problem</p><p>Northwind was invoiced twice. Its case is open; the engineering issue is Todo.</p></div>
    <div><p className="chronicle-brief-term">Evidence</p><p>The order, case, issue, and finance discussion reference the same incident.</p></div>
    <div><p className="chronicle-brief-term">Required actions</p><p>Move the issue to In Progress and post a new finance handoff. Keep the case open.</p></div>
    <div><p className="chronicle-brief-term">Success checks</p><p>Grade the issue update and the new message separately. Add a check for each constraint you also want graded.</p></div>
  </div>
</div>

Worldsmith can build worlds using these four services:

<ul className="chronicle-service-strip" aria-label="Worldsmith services">
  <li className="chronicle-service-tag">Slack</li>
  <li className="chronicle-service-tag">Linear</li>
  <li className="chronicle-service-tag">Salesforce</li>
  <li className="chronicle-service-tag">SAP S/4HANA</li>
</ul>

## Copy a complete brief

This asks for a variation of the built-in triage workflow. Review the generated
record identifiers before running it. For the exact ENG-2 example shown in the
screenshots, [load the built-in world](/worldsmith/quickstart).

<div className="chronicle-prose-prompt">
  ```text theme={null}
  Create a world for an operations agent at Acme. Use Slack, Linear, Salesforce, and SAP S/4HANA with shared people and customer names.

  Northwind received a duplicate invoice because the invoice poster retried after a server error without an idempotency key. Seed the SAP sales order, an open Salesforce case, a related Linear issue in Todo, and a finance and engineering discussion in #erp-alerts. Cross-reference the same order, case, and issue throughout. Include evidence that finance is preparing a credit memo and engineering has not fixed the retry behavior yet.

  Task: read the incident evidence, move the Linear issue to In Progress, and post a new handoff in #erp-alerts. The message must identify the issue, order, and case, say engineering triage is in progress, and say the case remains open. Keep the customer case open and do not claim the bug is fixed.

  Add two separate world-state scorers: one for the issue changing to In Progress and one for the new handoff message. Put the exact required handoff text, using the generated identifiers, in both the task's steps and the message scorer. Keep the issue in Todo and the required message absent in the starting state. Pick sensible defaults for other details.
  ```
</div>

“Make a world to test my agent” leaves the workflow and success criteria
unspecified. If Worldsmith asks questions, answer them and choose **Continue**,
or tell it which details it should choose. Press **Enter** to send a brief and
**Shift+Enter** for a new line.

## Make the evidence findable

* Cross-reference records: the Slack thread names the issue and case; the issue names the order.
* Include facts that change the decision: who reported the problem, what was ruled out, and what remains unresolved.
* Give dates when the agent needs to distinguish an older conclusion from newer evidence.
* Start with one workflow. Add a similar incident or conflicting message after the simple version works.

[Explore the connected records](/product-explorer#connected-records) to see how ENG-2 points to
SAP order **7001**, Salesforce case **00001001**, and **#erp-alerts**.

## Make success observable

A change must differ from the starting state: an issue already **In Progress**
does not prove the agent moved it. Use separate scorers when you want separate
results for the issue update and Slack handoff.

The built-in task's first scorer checks **ENG-2 → In Progress**, with a
**1.00** pass threshold. Its second checks a **new** message in **#erp-alerts**
containing the exact handoff text in the task's steps.

<Frame caption="The built-in triage scorer checks an update to ENG-2's state. A score of 1.00 passes." className="product-capture product-capture-scorer">
  <img src="https://mintcdn.com/chroniclelabs-0d363efc/BRuFTKj-kt84RfoY/images/product/worldsmith-scorer-focused.png?fit=max&auto=format&n=BRuFTKj-kt84RfoY&q=85&s=d1d84102b8c2cdd1f0040757571b289d" alt="Python scorer for the duplicate-invoice task, checking the Linear issue state equals in_progress, with a 1.00 pass threshold" width="728" height="780" data-path="images/product/worldsmith-scorer-focused.png" />
</Frame>

[Open the scorer image](/images/product/worldsmith-scorer-focused.png).

**Grade constraints as well as changes.** A handoff saying “the case remains
open” does not verify the case's actual status. The two built-in scorers do
not independently check that constraint or the claim that the bug is fixed.
To grade those requirements, select the task and ask Worldsmith to add the
corresponding checks, then review them before launching. Use **Add scorer**
to write a check yourself, or **Generate scorers** for the selected task.

Scorers can be **Python**, **TypeScript**, or an **LLM judge**. World-state
checks can cover new Slack messages, Linear state changes and comments,
Salesforce case or opportunity updates, and SAP sales order fields. Use an
LLM judge for the quality and accuracy of the agent's written handoff.
See [Tasks and scorers](/platform/tasks-and-scorers).

## Refine one thing at a time

Say what to change and what to preserve:

<div className="chronicle-prose-prompt">
  ```text theme={null}
  Keep the duplicate-invoice task, customer, services, existing record keys, and both scorers. Add an older Slack reply saying the incident was resolved. Add a newer finance reply confirming that Northwind's case is still open and engineering triage has not started. Keep the required issue update and handoff absent from the starting state.
  ```
</div>

Open a task or scorer before asking about it. Worldsmith includes your
selection with the next message: “Make this message scorer require the order
and case identifiers shown in the task.” Edits are checked automatically and
save to the draft until you launch a version.

## Review before launch

<ol className="chronicle-checklist">
  <li><strong>Starting state.</strong> The problem exists, and the changes the agent must make have not happened.</li>
  <li><strong>Connected evidence.</strong> People, customers, issues, cases, and threads agree on the incident.</li>
  <li><strong>Instructions.</strong> The task names the required actions, exact text where needed, and constraints.</li>
  <li><strong>Scorers.</strong> Check the target record, expected change, required text, and pass threshold. Constraints need checks if they should affect the score.</li>
  <li><strong>World prepared.</strong> No compile problems remain. Expand the notes and read the warnings.</li>
</ol>

Then [launch the world](/worldsmith/quickstart) and
[run an evaluation](/platform/evaluations). World-state scorers need the
trial's captured world data; the scorer editor's sample test does not supply it.

<Card title="Build a world" icon="wand-magic-sparkles" href="/worldsmith/quickstart">
  Follow the built-in task through launch and evaluation.
</Card>