Reading a review

Sigma speaks on GitHub in two places: a neutral check per reviewer on the head commit, which tracks the run, and a review with the findings. The check is never a merge gate; its conclusion is always neutral.

This page describes the current GitHub format (public format v2: review render 11, personal render 12, check render 7, incomplete comment render 16 and 17, reply format 3, Rules render 2). Reviews, checks and replies published before it keep the format they were published with; a newer Sigma does not rewrite them. Older ones can still show an executor suffix such as "(logins)", cost lines, a visible run id or a link to the run page.

GitHub shows what a pull-request reader can use: the reviewer, the commit, the findings and what could not be checked. It does not show money, model names, the execution path or Sigma's internal state. Those stay on Sigma's run page.

Check titles

The check is named after the reviewer and version, for example "Sigma Charlie v6", and is tied to one run and one exact pull-request state. Execution and publication are reported separately:

Wide tables: scroll horizontally to see more columns.

GitHub's own "Completed in …" prefix says nothing about whether model work succeeded.

The check's summary is short. In order:

• the title again, then Exact head: <sha> (Exact requested head when the review failed before it started);
• why it waits, stopped or did not complete, when that applies;
• for a finished review: Verified findings: N., the required checks (Required checks: none failed. or Required checks: 2 failed., then one line per check) and Files reviewed: 5 of 6 changed.;
• for a recheck: Finding recheck: open. (or fixed, refuted, inconclusive, or no completed assessment);
• "Why the review did not complete" and "Scope notes", up to five lines each;
• the two legend links (severity and verified);
• "This neutral progress check is not an approval or a merge gate.";
• a hidden marker, <!-- sigma:check:v1 run=… head=… -->.

Notices: why a reviewer has not started

A notice is a check without model work. Its summary reads "Sigma Charlie v6 was not started: …" and names the cause and what lifts it:

Wide tables: scroll horizontally to see more columns.

A paused or waiting review is queued and starts by itself once the cause clears; repeating /sigma review does not help. A refused selection or review is never queued: once the cause is fixed, it needs a new request, a /sigma review comment or a new push. A notice is not a statement about your account or plan. Limits and budget says what the maintainer does next. Notices published before public format v2 can read Review held and name the provider or the subscription.

The review's layout

The review body starts with the reviewer, head and base: "Sigma Charlie v6 reviewed <head> against base <base>." A review from a personal runner opens with one paragraph that says the contributor's device ran it. Then short facts:

• Review evidence: unavailable or inconsistent. only when Sigma cannot read the run's evidence;
• Verified findings: N. (bold when the count is known). When it is unknown the line says so and adds that this does not mean there are no defects;
• the required checks and the files reviewed, as on the check.

Then, only when relevant:

• Additional verified findings: confirmed findings beyond the inline limit, under a ### Additional verified findings heading. They have no thread of their own.
• Unverified suspicions (N): leads no verifier confirmed, not findings, folded. They are not findings.
• Pre-existing observations (N): judged to predate this change, folded.
• Scope notes (N): what could not be read or run, folded; one line per note, prefixed producer:, verifier: or runtime:.

The body ends with the two legend links. Up to five verified findings are posted inline, on the line they point to. Each inline comment ends with the reviewer name and the legend links.

Every finding, wherever it appears, uses one template:

**[P1] Retry counter can exceed max_retries**

The claim, in one paragraph.

**Why it matters** The impact.

**Evidence**
- src/logic.py:7 increments after the comparison.
- tests/test_logic.py has no case at the limit.

**How it was verified** What the verifier checked to confirm it.

**Suggested change** The fix in prose, or prose followed by a fenced code block.

A finding without its own thread (additional, suspicion, pre-existing) has its path:line as the first Evidence bullet. How it was verified appears only when the finding carries a verification note and a verifier confirmed it. Under an unverified suspicion, and under a pre-existing observation no verifier confirmed, the label is What was checked: that note is the producer's own, not a verifier's confirmation. A code block in Suggested change is a plain fenced block that keeps a simple language name such as python. It is never a GitHub suggestion block, so it cannot be applied with one click.

Escaping. Model-written text is Markdown. Sigma escapes only characters that Markdown or GitHub would act on, with a backslash: \, `, *, ~, [, ], <, &, an _ that is not inside a word, and a #, >, +, -, =, | or 1. that would start a block. Anything that GitHub would turn into a mention, an issue or commit link, or a URL (@name, #12, a commit hash, https://…, www.…) is put in a code span, and so is any word with a $, which GitHub would otherwise render as math. Code spans the model wrote stay code, unless a reference is glued to them; then the whole word becomes one code span, so two spans never merge into live text. A review can never page a person, link an issue or inject HTML by accident, and the raw text stays readable.

A run that ends before verification posts a comment instead: "Sigma Charlie v6 could not complete its review of <head>." It gives the reason, the same short facts, and folded Observations from an incomplete review (N): not findings, Model-declared notes and Limitations. Each observation says "Unverified. Proof gap: …" unless an accepted verifier marked it verified, and then it still is not a finding of a completed review.

Severity (P0–P3)

Severity is how much a finding matters, not how confident the model is:

• P0: immediate catastrophic loss, broad compromise, irreversible corruption, or a change that cannot safely ship under normal input.
• P1: a correctness, security, data integrity, authorization, availability or contract defect that should block merge.
• P2: a real, bounded defect worth fixing but not normally merge-blocking.
• P3: an optional improvement; not published inline by default.

For document changes, the prompt applies this scale to what a builder would do: P1 can mean building the wrong or impossible thing, P2 a needed decision, and P3 misleading wording. These are document-specific interpretations, not definitions for every code review. Verified P0 and P1 findings introduced by the change are what a Rules verdict counts as blocking; P2 and P3 remain comments.

Verified vs. unverified

The producer records candidates as suspicions. A fresh verifier confirms, rejects or reclassifies each one; only confirmed candidates are verified findings. For hosted reviews in Comments mode, when the producer proposes nothing, the verifier is skipped with the reason "No candidate findings to verify." Gateway reviews contributing to Rules require verification even without candidates. Unconfirmed suspicions stay labelled as such, including when a run ends before verification. A verification label is agent-produced evidence, not proof that the code is correct.

The aggregate verdict (Approve / Request changes)

Where the repository's verdict setting is exposed, Comments keeps the reviewers' findings without an aggregate; Rules can add one separate, deterministic Approve or Request changes review. Selecting Rules is not itself an approval, and the progress checks stay neutral either way.

On GitHub the Rules review reads:

**Sigma · Rules**

Confirmed P0/P1 blockers: 1. Changes requested.

Reviewed commit: `<head>`. Reviewers: Sigma Charlie v6, Sigma Bravo v6.

An Approve says "Selected reviewers and required checks completed; no confirmed P0/P1 blockers." When some selected reviews or historical rechecks are incomplete, a last paragraph says the decision uses only confirmed blockers. Rules reviews published before public format v2 are titled "Sigma · Rules v1" and list reviewers with their executor.

How Rules decides, in order: unavailable evidence, a superseded or paused run, or unresolved global accounting stop the decision outright. Otherwise verified introduced P0 or P1 findings give Request changes, even if another member is still pending or incomplete. Short of that, a member that is incomplete, whose evidence is inconsistent, or whose required checks are not configured gives Incomplete; a member still running or not yet published gives Pending; a would-be Approve without offline sandbox proof for every stage is withheld; otherwise Approve. Only Approve and Request changes are posted to GitHub.

For maintainers. A stage that ran on a provider subscription login has no offline sandbox proof, so its would-be Approve is withheld. This applies to both owner-login and the two-subscription logins path. Either can establish Request changes for confirmed introduced P0/P1 blockers when the other evidence, accounting and publication gates pass. See Executors.

Whether Rules is enabled on an installation depends on its configured authority and accepted rollout, not on the setting alone. A mode change applies to newly admitted work and never approves old reviews. Sigma never merges.

Cost lines and the run page

Reviews and checks in the current format (public format v2) show no cost on GitHub: no amounts, no token counts and no execution path. Reviews and checks published before public format v2 can still show a Cost section or "API cost estimate" and "Observed subscription usage" lines; they keep that wording.

Sigma's run page shows the cost. API cost estimate records known and held amounts from Sigma's API ledger: known is settled, held is reserved and unsettled. Both are token-derived estimates, not invoices. Observed subscription usage is the provider tool's own report for a subscription stage, valued at API list price for comparison; it is not billed by Sigma, not counted against its API cap and not the provider's subscription price. Each stage and attempt has its own line; a missing line means unknown, not zero. See What each path costs you.

The run page also adds stage details, reading declarations, scope notes, resources and the delivery state. It requires signing in as the account that connected that repository; invited accounts also need current GitHub grants. Pull-request authors can read the GitHub review and check with their GitHub access, without a Sigma sign-in. GitHub surfaces in the current format do not link to the run page. The Requested time shows the queue time in the browser's time zone, with UTC in the no-JavaScript fallback; provider reset times stay in UTC. Historical runs keep their recorded execution and usage, not today's settings.

For coding agents

Read the raw Markdown through the GitHub API, not the rendered page.

1. Find the review. List the pull request's reviews and keep those by the Sigma App whose body ends with <!-- sigma:review:v2 intent=<id> run=<run id> head=<sha> payload=<sha256> --> (v1 on reviews without a named reviewer). Keep every one whose head equals the head you care about, not only the newest: several reviewers can review the same pull-request state, and an explicit request can add another run of the same reviewer. Tell them apart by run; the reviewer name in the body can repeat, because one version on two executors shows one name. An incomplete run has <!-- sigma:incomplete:v1 intent=… run=… head=… payload=… --> instead.
2. Find the check. The check run is named after the reviewer ("Sigma Charlie v6"). Its summary ends with <!-- sigma:check:v1 run=<run id> head=<sha> -->; the run matches the review marker. Checks for an admitted review that is waiting, paused or waiting for a provider window still carry its run and marker. Only admission-refusal notices have no run and no marker. Checks published before public format v2 have no marker either. Its conclusion is always neutral; read the title for the state.
3. Tell verified from unverified. Verified findings are the inline review comments and the findings under ### Additional verified findings. Anything inside <details> whose <summary> starts with Unverified suspicions, Pre-existing observations or Observations from an incomplete review is not a finding of this change. Treat suspicions as leads to check yourself. Verified findings: N. is the count that matters; "unknown" is not zero.
4. Read a finding. After an optional Personal runner · device-reported execution line (reviews from a contributor's own device), the first line is **[P<n>] <title>**. Then the claim, **Why it matters**, **Evidence** (a list; inline comments carry the file and line in the comment's path and line), optionally **How it was verified** (a verifier confirmed it) or **What was checked** (no verifier confirmed it), and **Suggested change**.
5. Severity. Verified P0 and P1 introduced by the change block a Rules verdict; P2 is a bounded defect; P3 is an optional improvement. See Severity.
6. Unescape. Text is Markdown. Remove a backslash before a Markdown-active character (\* is *) and read code spans literally. New renders use no numeric HTML entities; older ones may.
7. Ask for a recheck. Only the connected owner's reply in a finding's thread starts one for supported hosted findings. Imported personal-runner findings have no Sigma thread follow-up today; see Replies and rechecks. Sigma answers in the thread with a reply ending <!-- sigma:reply:v3 id=<reply id> payload=<sha256> -->; the outcome is in Agent-adjudicated outcome: **open** (or fixed, refuted, inconclusive). An assessment outcome is separate from the finding's disposition.
8. Rules. A Rules review is titled **Sigma · Rules** and ends with <!-- sigma:verdict:v1 intent=… target=… head=… payload=… -->; its GitHub state is Approve or Request changes.

The payload field is a digest Sigma uses to recognise its own publication; an agent only needs run and head.