Skip to main content
Ask your assistant to validate a change and it should answer one question truthfully: what did each check prove about this revision? This page is the workflow it follows. Give it the page along with Use ReasonOS with your AI assistant.

​
Start with a request like this

Validate the change on my branch before I ask for review. Find the targets it affects, run their tests with coverage on the exact commit, and tell me what passed, what failed, what was replayed from cache and what could not run. Ask before starting anything that uses a QA agent or a model.

​
Choose where the checks run

Two connections can run checks. Use whichever your assistant has; they are not interchangeable. Local RBS MCP (rbs mcp serve) checks your local workspace, with files as they are now:
  • rbs_affected — the targets and tests a set of changed files affects
  • rbs_build, rbs_test, rbs_coverage — build, test and coverage; each answers when it finishes
Managed ReasonOS MCP checks a clean checkout of an exact commit on the branch’s running server:
  • start_branch_execution — build, test or coverage (mode) of exact targets
  • branch_execution_status — follow it (wait_seconds to wait); it shows only the log’s tail
  • get_branch_execution_log — a finished run’s whole log, one page at a time, for the person who started it
  • start_ci_run, ci_status, get_ci_run, get_ci_run_log — CI
  • issue_evidence — the evidence linked to an issue
Know which connection you have explains what each one can reach. A managed run needs the branch server already open; it never starts one, and it never uses or touches unsaved work in the shared workspace.

​
The workflow

  1. Pin what is being checked.
    • Managed: name the branch and the full commit hash. The run checks exactly that commit.
    • Local: the tools check the working files, not a commit. Record HEAD and whether the working tree is clean before and after the run. Call a result evidence for that commit only if the tree was clean and unchanged throughout; otherwise call it evidence for the workspace with its uncommitted changes. Never stash, revert, stage or commit someone’s work just to get a clean tree.
  2. Choose bounded checks. Locally, give rbs_affected the files the change touched: it returns what to rebuild and which tests to run, and lists any file no target owns separately, so you know the graph did not cover it. Run those tests, not the whole workspace.
  3. Run them.
    • Locally: rbs_test or rbs_coverage with those targets. Coverage uses the same floors as rbs coverage; an unmet floor fails the check. rbs_test takes a filter to re-run one case; a filtered run is never cached. Both tools take runner_args, a list of arguments for the test runner (for Go, ["-count=2", "-v"]). A run with runner arguments requires exactly one test in its resolved dependency closure and is never cached. Runner arguments can start other programs, so the local server offers them only when started with --allow-write or --tools full; get the person’s authorization to run commands if it is not already in scope.
    • Managed: start_branch_execution with the full commit hash, the targets and a request_key you make up, such as issue-12-test-1. Then follow it with branch_execution_status.
  4. Read the outcome per check, then report each one as exactly one of:
    • Passed — the test process ran on this revision and succeeded.
    • Replayed from cache — reported as cached pass from <time>; test process not run. It is a pass recorded for identical inputs, not a new run; say so.
    • Failed — include the failing test’s log, or for coverage the unmet floor.
    • Skipped — a CI job or test that did not run by design, such as a job the change did not affect. It is not a pass.
    • Not run — the server was not open, a service was unavailable, the target did not build, or you were not allowed to run it. Say which.
    • Unknown — the run’s outcome could not be confirmed (see below).
  5. Link the evidence. On a managed project, issue_evidence shows each CI run and execution judged against the issue’s linked change: current (at its head) or stale (at an older commit).

​
Approval points

Builds, tests and coverage on the person’s own branch use their existing permissions. Ask first before:
  • starting a QA run, which uses QA workers and a model;
  • re-running CI for someone else’s change;
  • anything that merges, deploys or changes settings — validation never does.

​
When things go wrong

  • A new commit lands. Every earlier result is now stale for the change. Re-run the affected checks on the new commit, or report them as stale; a pass on an older commit does not verify a later one.
  • The answer to a start is lost (a timeout or dropped connection). Ask branch_execution_status, or resend the same request with the same request_key: the first attempt is answered and nothing new runs. Never retry with a new key; that can run the work twice.
  • You cancel a run. One that had not started is cancelled. One already running is asked to stop and often ends unknown, because a stopped command cannot confirm what it did. Report it as unknown, not passed or failed.
  • A log is long. branch_execution_status shows only the tail. Before saying you read a whole execution log, follow get_branch_execution_log’s next_from until there is none. get_ci_run_log starts at the last page, where failures usually are; source_truncated means the stored log lost its beginning.

​
Limits today

  • This page describes the current tools. A hosted deployment may run an earlier build: use the tools your connection actually offers, and report a missing one rather than working around it.
  • Runner arguments need a local server started with --allow-write or --tools full, and a build of rbs that includes them. A default connection does not show runner_args at all. The command-line equivalent, rbs coverage //t -- -count=2, needs the same authorization to run commands.
  • Affected-target discovery is a local tool; the managed connection has no equivalent yet.
  • A green check is evidence about source, not about what is deployed: a passing run, a merge or a tag does not show which version is running.