How to write a Grok Bot workflow brief (with a full template)

A Grok Bot brief works when it defines a finish line you can check, the sources allowed, and the exact point where the Bot must stop for you. The official getting started guide names five parts — outcome, sources, constraints, deliverable and stopping point — and the template below adds acceptance checks, evidence rules and failure behavior so a run either finishes or fails visibly.

At a glance#

Grounded in docs.x.ai's get started, files and results, and approvals pages, the changelog through 0.75.5, and SpaceXSI's October 20 incident post. The templates are our originals, not vendor configurations, and we have not run them.

Start at the finish line#

"Be my research assistant" never ends. "Compare three scheduling tools against our requirements and return a cited decision table" does. Write the outcome as the decision the output supports, then name the audience and the columns.

Then split rules from taste. "Only evaluate products with a publicly documented export option" is checkable. "I like simple interfaces" needs judgment, so label it as a preference. Tell the Bot to mark anything it couldn't verify — otherwise missing evidence can quietly read as a pass.

Three small specifics save rework:

• Dates: state the time zone and the cutoff.
• Changing data: ask when each fact was checked.
• Existing files: say whether you want the original revised or a new copy.

The five official parts, plus three we add#

The getting started guide's five parts tell the Bot what to do. The files and results guide supplies the reviewing half: request the artifact and acceptance criteria up front, and for consequential work have the Bot report facts from sources, assumptions, actions completed, actions awaiting approval and open questions as separate lists.

We add three fields on top:

1. Acceptance checks — three conditions a reviewer can see, such as "every row has a source link."
2. Evidence — links, timestamps with time zone, and an explicit list of what couldn't be verified.
3. If blocked — what to return when only part of the job is possible.

The full template#

Fill every bracket with concrete names. Delete fields that don't apply, but keep acceptance checks and the blocked behavior.

OUTCOME: [the decision this supports or the job that will be finished]
AUDIENCE: [who reads or uses the result]
SOURCES: [files, URLs, connected apps or accounts]. If sources conflict, treat [source] as authoritative.
SCOPE: include [records, topics, items]; exclude [out-of-scope items].
TIME WINDOW: [start] to [end], [time zone]. Data must be no older than [freshness rule].
DELIVERABLE: [artifact type: table, Page, doc, draft], with these sections or columns: [list].
ALLOWED NOW: [read-only actions, or explicitly authorized edits].
STOP BEFORE: [send / publish / purchase / delete / change permissions]. Draft only. Ask me separately for each.
ACCEPTANCE CHECKS:
1. [observable condition]
2. [observable condition]
3. [observable condition]
EVIDENCE: link every claim to its source, timestamp each check with time zone, and list anything you could not verify.
IF BLOCKED: return the finished portion, name the missing evidence, and propose the smallest next step. Do not invent facts or swap in older inputs.
WHEN DONE: link the artifact in this chat, summarize how you validated it, then list separately: facts found, assumptions, actions completed, actions awaiting my approval, open questions.

For a first run, keep ALLOWED NOW to reads only. You can widen it after you've reviewed a few results.

What SpaceXSI's own support Bots teach#

SpaceXSI's October 20 post (by Chris Bowie and Isaac Hopkinson) is the clearest vendor example of a job-shaped brief, under the theme "Give Bots jobs, not tasks."

• IncidentWatch runs every five minutes, reviews the previous 15 minutes of tickets for a spike around one problem, and — if it isn't a known incident — alerts the on-call support engineer with the issue, the matching ticket count and examples.
• IncidentSweep takes the engineer's include/exclude rules and exact message, sets aside tickets it can't confidently tie to the incident, shows the batch and message for approval, then sends in small batches, records each action, never adds tickets afterwards, and stops and reports on any failure.

SpaceXSI says IncidentSweep cleared 204 tickets in about 10 minutes on September 18 with an engineer approving the batch. That is the vendor's figure about its own team; we haven't verified it.

Batch-approval template for bulk writes#

Use this when the job ends in many similar actions: ticket replies, email labels, record updates. It is our adaptation of the published pattern. Test it on a handful of harmless records first.

JOB: prepare one batch action for my approval.
SCOPE: include [records matching these rules]; exclude [records matching these rules].
SOURCE OF TRUTH: [system or export].
ACTION: [exact action], using exactly this text: "[message]". Do not reword it.
1. Check every candidate against the scope. Set aside any record you cannot confidently match and list it with the reason.
2. Before acting, show me: the batch with record IDs, the set-aside list, the exact text, and counts for each.
3. Wait for my approval of that exact batch.
4. After approval, act only on approved records, in batches of [size]. Do not add records; list new matches separately for a later decision.
5. Log each action: record ID, time, result.
6. On the first failure, stop and report what completed, what failed, and what was not attempted. Wait for me.

Make the app enforce what the brief says#

A brief is a request; settings are enforcement. Check that each STOP BEFORE line has a control behind it. Our permissions guide covers every control in detail.

Two 0.75.5 details help you. Auto-review no longer approves an action your request said to stop before, and after you deny an approval card the Bot stops and won't retry until your next message. Sends from routines and other turns you didn't start still wait as drafts.

Keep the final result in the chat. Bots can read files other Bots save in /workspace, but the docs treat it as scratch space. When you want revisions, ask for the existing artifact to be updated, not a new copy — a Page is ideal for this.

Common mistakes#

• No finish line. "Research X" instead of "return a cited table answering Y."
• Fuzzy scope. "The relevant tickets" instead of include/exclude rules.
• Silent gaps. No instruction for missing data, so the Bot fills it.
• Implied boundaries. Assuming "draft" when you typed "reply to."
• Secrets in the brief. Never put passwords or keys in a brief or a skill you might share.
• Rewriting everything after run one. Change one instruction at a time and keep the failed example next to the fix.

Pressure-test before you send it#

Imagine the Bot returns exactly what you asked. Would it be enough to decide? If a key comparison is missing, add it now. Longer isn't better; the useful detail is whatever prevents a costly misunderstanding.

• A reviewer can tell when the task is complete.
• Source conflicts have a rule, or stay visible.
• The Bot knows what to return with partial results.
• Evidence is reported separately from recommendations.

Once a method holds up across varied inputs, ask the Bot to save it as a skill, then decide on a schedule — our skills vs routines guide explains the order, and evaluating a workflow shows how to score results. Give each Bot one focus; the docs say focused Bots build more useful context than a catch-all. For twelve ready-made starting briefs, see Grok Bot use cases.

Our take#

Write the stopping point first, then the outcome, then everything else. Since 0.75.5 your exact wording decides whether a message is drafted or sent, so "draft only" and an Ask first rule on sending belong in every brief that touches email or Slack. For anything bulk, copy the frozen-batch pattern: one approval, no additions, stop on first failure.

Frequently asked questions#

What should a Grok Bot brief include?#

The official getting started guide lists five parts: the outcome you want finished, the sources that matter, constraints on what to avoid or ask about, the deliverable, and where the Bot should stop for you. The files and results guide adds acceptance criteria and asks the Bot to separate facts, assumptions, completed actions, pending approvals and open questions.

How do I stop Grok Bot from sending an email I only wanted drafted?#

Say draft only or stop before sending in your request. Since 0.75.5 on October 23, an email or Slack message you ask for in chat goes out once Auto-review allows it, but Auto-review no longer waves through an action your request said to stop before. Also add an Ask first rule for sending, which always stops a matching action.

What is the IncidentSweep pattern?#

SpaceXSI's October 20 post describes a support Bot that reviews tickets against include and exclude rules, sets aside anything it cannot confidently match, shows the proposed batch and the exact message for approval, then sends in small batches, records each action and stops on failure. It never adds tickets after approval. SpaceXSI says it cleared 204 tickets in about 10 minutes on September 18.

When should I turn a brief into a skill?#

Once the method works on more than one input without extra explanation. The getting started guide suggests asking the Bot to save a finished task as a skill covering when to use it, inputs and access, steps, how to check the result, what to return and what needs approval. Private skills are shared by all your Bots.

Where should a Bot put the final deliverable?#

In the conversation, or a link to it there. Bots can read files other Bots save in /workspace, which helps handoffs, but the docs treat that folder as a place for intermediate material. When you want changes, ask the Bot to update the existing artifact rather than producing a new copy.