Operator

Give Operator a failed task, recurring pattern, or quality goal. It investigates behavior and reliability problems using project evidence, works with domain experts when judgment is needed, and identifies what should improve. When the evidence supports a change and you ask it to proceed, Operator can modify the version-controlled Recipe behind the selected runtime, test the candidate with development tasks, an evaluation, or deterministic checks, and open a draft pull request for your team to review.

Each Operator conversation belongs to one project and keeps one selected runtime as its default until you change it. The conversation keeps the investigation, evidence, and proposed work together so you can review it or continue later. Introspection runs Operator as a managed agent, so you don’t create or deploy an Operator Recipe.

Start an investigation

Open your project in the dashboard and select Operator. Give it a question with a concrete starting point, such as a task ID, a runtime name, or a period to investigate. For example, replace the task ID in this prompt with one from your project:

Investigate task <task-id> from refund-exception-agent.
Find the first step that led to the incorrect refund decision.
Explain the cause and show the supporting conversation evidence.

Operator finds the runtime you name in the project’s runtime list. It asks which runtime you mean if your request doesn’t identify one clearly. The selected runtime remains the default for later turns in that conversation until you change it.

Read the result and continue in the same conversation when you want to narrow the question or act on the finding. Open a conversation from Recent to return to earlier work, or select New chat to start another investigation. Each conversation keeps its own runtime selection and task record.

An investigation should distinguish a behavioral problem from a failed tool, missing binding, or incorrect runtime version. Ask for the first failing step and its evidence before asking for a recipe change. The Learn from production guide explains how to compare failures with successful cases and test a proposed cause.

Give Operator repository access

Operator can work with repositories registered to the current project through your organization’s GitHub integration. The repository access control above the message composer lists the available repositories. Select New repository there to register another repository that the GitHub integration can access.

For a recipe improvement, Operator starts from the exact recipe commit used by the selected runtime and creates a fresh checkout for the attempt. It can clone, create branches, commit, push, and open pull requests in registered repositories. Tell it which change you want and whether the result should be an investigation, a proposal, or a pull request.

Operator can access every repository registered to the project. When you select repositories for an automation to clone, you choose which ones are available in its workspace at the start. Operator can still access the other registered repositories.

Coordinate expert review

Operator can label specific spans in a conversation, assign reviewers by email, and add comments explaining what needs a human answer. For example:

Find up to five different refund failures from the last seven days.
Label the relevant spans needs-review and assign them to expert@example.com.
Add a short question explaining the policy decision each review should settle.
Keep existing labels and reviewers.

Replace the example email with a reviewer in your organization. Be explicit about whether existing labels and assignments should remain, because changing them replaces their saved selection. Operator reads the existing state when it needs to retain those values.

Operator’s annotations identify it as the author. An agent comment or assignment does not mark a span as reviewed by a person. Human review remains the evidence that a domain expert checked the behavior.

Prepare and review a recipe change

Once you understand the cause, ask Operator for a focused change. It can run development tasks against a snapshot of its uncommitted recipe changes and inspect their recorded conversations. Behavioral changes need a focused evaluation; a deterministic code or configuration bug can use a reproduction, tests, recipe checks, or type checking appropriate to that bug.

For example, you can continue the investigation with:

Prepare a proposal that checks final-sale exclusions before the general
refund rule. Test the reported failure and ordinary eligible refunds.
Save the proposed change and explain the test results for review.

Operator tracks a Recipe change on its existing Issue. Each candidate commit adds or updates .introspection/operator/issue-<issue-id>.md beside the Recipe change. That file records the intended behavior and validation plan without replacing the Issue: the Issue remains the human-facing brief, evidence, and review history.

When the change is ready for repository review, ask Operator to open a pull request. Review the diff, the checks that ran, and any remaining limitations. Your normal merge and deployment process releases the change. Creating a proposal or a pull request does not itself change the production runtime.

Keep the work within your request

Operator can read project evidence, annotate conversations for review, test Recipe changes, and publish branches and pull requests in registered repositories. Ask explicitly for the changes or external messages you want it to make.

Use your team’s review and deployment process to merge and release a proposed change. Operator’s workflow stops before merge or deployment. Manage project label definitions and resource deletion in the dashboard or through the appropriate API with your own authorized account.

Operator follows the workflow you give it. An investigation asks for evidence; a review assignment asks it to change annotations; a pull request asks it to publish a branch for review. State the runtime, evidence period, allowed changes, and stopping point when those limits matter.

Use Operator in Slack

Connect your organization’s Slack workspace when you want people to start Operator tasks from a channel or receive an Operator update in Slack. A channel binding assigns one Slack channel to one Introspection project, so Operator can open the task in the right project and keep the Slack thread with it.

Connect Slack to Operator

Before you start, choose the Introspection organization and project that should receive requests from the Slack channel. You need permission to manage the organization’s integrations and channel bindings, plus permission to install the app in Slack.

1. Open Organization → Integrations and select Connect next to Slack. Authorize the Introspection app in the intended workspace.
2. Add the app to the Slack channel where people will work with Operator.
3. In Channel bindings, select Add channel binding. Choose the project and Slack channel, then save the binding.
4. Mention the app in that channel with a request. Operator should answer in a thread under the message.

Add a binding for every channel where a message should start Operator work. A Slack channel can be assigned to one project at a time. The channel picker shows channels the app can access and leaves out channels already assigned elsewhere.

Start and continue work in Slack

Mention the app to start an Operator task in a bound channel or thread. When the mention is outside a thread, Operator starts one under the message. Later replies in that thread continue the same task without another mention.

Operator answers in the Slack conversation where the request arrived. A mention in another bound channel or thread starts a separate task. A message outside a thread already linked to Operator needs a mention to start a task. Bot messages and edited messages do not start tasks.

Operator can also send a result to a named channel or thread. For example, ask it to “post this investigation’s findings to #refund-review.” Include the full channel name and make sure the app has access to that destination. A destination needs a channel binding only when messages from it should start Operator tasks.

Responses in the web chat stay there unless you ask Operator to send a message to a Slack destination.

Change or troubleshoot the connection

Use the project selector on a channel binding to move the channel to another project. Select Remove to stop new messages in the channel from starting Operator tasks. Existing tasks remain available in Introspection, and you can bind the channel again later.

If the Slack app is removed or its authorization is revoked, reconnect the same workspace from Organization → Integrations to restore its bindings. Selecting Disconnect Workspace in Introspection removes the connection and its channel bindings, so reconnecting after that requires new bindings.

When a message gets no reply, check that Slack is connected, the app belongs to the channel, and the channel is bound to the intended project. Mention the app to start a task, then open the task in Introspection to check for a runtime or delivery error.

The Control Plane API schema includes the channel binding routes for programmatic setup.

Schedule recurring work

Use Automations for a daily briefing, review queue, or follow-up on existing work. Each scheduled run creates an Operator task with the saved instructions. Include enough detail for Operator to work without asking you follow-up questions.

Related

• Learn from production explains how to establish a cause before changing an agent.
• GitHub explains organization installation and project repository access.
• Automations explains schedules, run history, and quiet runs.