antithesis-triage — Claude Code skill: triage Antithesis test runs

---
name: antithesis-triage
description: >
  Triage Antithesis test reports to understand what happened in a run: look
  up runs, check status, investigate failed properties (assertions), view
  metadata, download logs, search events across all timelines, inspect
  findings, and examine environmental details. Load after a run completes or
  when investigating a failure.
compatibility: Requires snouty (https://github.com/antithesishq/snouty), and jq.
metadata:
  version: "2026-10-21 4f8d80b"
---

# Antithesis Run Triage

**Skill version:** `2026-10-21 4f8d80b`

Use this skill to analyze Antithesis test runs.

**Reference files:** This skill's `references/` directory contains detailed guides for specific tasks. Do NOT read them all up front — only read a reference file when you are told to. Each reference file is mentioned by name at the point where it is needed.

## Prerequisites

- DO NOT PROCEED if `snouty` is not installed. See `https://raw.githubusercontent.com/antithesishq/snouty/refs/heads/main/README.md` for installation options.
- DO NOT PROCEED if `snouty` is older than 0.8.0. Use `snouty --version` to find the version. Use `snouty update` to update.
- DO NOT PROCEED if `jq` is not installed. See `https://jqlang.org/download/` for installation options.

### Preflight: confirm triage can work

The triage skill talks to Antithesis through the snouty API (`snouty runs ...`). Before doing any work, confirm the setup is ready:

```bash
snouty doctor --json
```

This validates API connectivity and reports snouty's resolved configuration.

Proceed only when the top-level `ok` is `true` and the `api_key` check's `status` is `ok`. Otherwise relay the failing check's `message`/`notes` and stop; if `api_key` is the failing check, tell the user to set `ANTITHESIS_API_KEY`.

The `settings` array in the same output carries snouty's resolved parameters. For example, you can look up the resolved tenant with:

```bash
snouty doctor --json | jq -r '.settings[] | select(.name == "tenant") | .value'
```

## Gathering user input

Before starting, collect the following from the user:

1. **Tenant Name** (required) — You must know the tenant name. Read snouty's resolved tenant from `snouty doctor --json` (see Preflight); snouty resolves it from the environment or a settings file, so trust that value. Only ask the user if `doctor` shows the tenant is unset.

2. **What they want to know** — Are they interested in all failures in a specific run? Are they investigating a specific failure? Are they getting a general overview? Comparing runs? This determines which workflow to follow.

## How to get information from a run

Your main method to obtain information is to use the `snouty runs <OPTION>` command with the `--json` option. The `--json` option returns line-delimited JSON. The fields in the JSON depend on the option you are using. The same command without `--json` returns fewer fields in a tabular form better suited for human consumption.

You will need to know the RUN_ID. Read `references/run-discovery.md` to learn how to obtain the run_id.

## Workflows

### Summarize recent runs

Read `references/run-discovery.md` to get a list of recent runs. Then summarize them in a report.

### Looking up a specific run

To look up a specific run (report), read `references/run-info.md`. Then continue with other workflows as needed.

### Triage a run

If the run has a status of "incomplete", refer to the `Diagnose incomplete run` section below.

1. Read `references/run-info.md` to load information on a run
2. If `links.triage_report` is null/absent in the run-info output, no triage report was generated for this run (typical for `cancelled` runs and some `unknown`/`starting` states). Report that the run is not triageable — the properties and logs endpoints will return 404 for these runs.
3. Read `references/properties.md` to load properties
4. Review passed/failed counts
5. Check the instrumentation setup signals — the `Software was instrumented` and `Symbols were uploaded` properties. Read `references/instrumentation.md` to interpret them.
6. Build a detailed summary of the run including a review of all failures as well as flagging any new failures. Include the instrumentation status in the summary.

### Investigate failed properties

1. Read `references/properties.md` - use `snouty runs --json properties` to extract properties with their examples and learn how to download logs
2. Read `references/logs.md` to learn how to understand logs
3. For each property to investigate:
   a. Pick the first failing example
   b. Find the moment. If the counterexample has no `moment` field (telemetry / meta properties — see `references/properties.md`), report the counterexample value as the evidence and skip steps c–e.
   c. Download the example's log using the guidance in `references/logs.md`
   d. Analyze the downloaded log locally
   e. If you aren't certain what caused the issue, consider downloading logs from other counterexamples and examples for the same property. Compare each occurrence and try to see if there are any similarities or differences that might explain the failure cause. Logs from passing examples can be useful to compare against to find differences between success and failure cases.

   To find more passing or failing evaluations of the property, use `snouty runs --json search`. Run `snouty runs search --help` first: it documents the query language and has ready-to-paste snippets, including one that selects an assertion's evaluations by id. The id is the "name" field in the property data you are investigating; match the "condition" field against the examples or counterexamples you want more of. Results are a sample capped at `--limit` (default 50), so they show SOME but not necessarily ALL evaluations. The examples and counterexamples you already have will likely be among them; compare each result's moment against the ones you have already downloaded.

4. **Important:** Cross-reference the log against the source code of the system under test (SUT) and the workload if you have access to it.
5. Deeply investigate the failure to develop an understanding of the timeline of events which led up to and potentially caused it.
6. Report your findings.

**Important:** The property status and assertion text alone are not sufficient — the logs provide the actual runtime context needed to understand the failure.

### Search across timelines

A downloaded log covers one history. To answer questions that span every timeline in the run — "did event A always precede failure B?", "does the failure still occur without the preceding fault?", "which container logged this error first?" — use `snouty runs --json search`. Run `snouty runs search --help` to learn the query language before writing a query. It covers filtering by log text, container, assertion, and vtime window, combining event sets, and annotating each event with the nearest earlier or later event from another set on the same timeline. Every result carries a `moment`, so you can download the log leading up to any hit as described in `references/logs.md`.

### Verify instrumentation

To verify that the SUT and the workload are instrumented and that their symbols are registered, read `references/instrumentation.md`.

### Diagnose incomplete run

If the "status" of a specific run is "incomplete", there may be an error log to examine. The steps to triage an "incomplete" status run:

1. Do a `snouty runs --json show ${RUN_ID}`
2. Look at the `failure_moment` structure in the returned JSON. If present, use the input_hash and vtime from `failure_moment` to download a log in accordance with the instructions in `references/logs.md`.
3. Try and obtain the build logs, especially if there is no failure moment, using `snouty runs --json build-logs ${RUN_ID}` and look for errors in the build.

> **Note on `links.triage_report`:** For incomplete runs, the per-property `properties` and `logs` endpoints typically return 404, but `links.triage_report` and `failure_moment` may still be populated in `show`. Report what `show` actually contains — do not claim the triage_report link is absent unless that field is null. The triage workflow for incomplete runs is `failure_moment` + `build-logs`, regardless of whether a report URL exists.

## General guidance

- **Review logs before concluding on failures.** When a failed property has examples with a moment supplied, download + analyze the logs before declaring a root cause. Some properties have no examples or logs — for those, the status alone is the evidence.
- **For property failures, consider the "details" section if provided.** These are curated fields supplied by the property author designed to illuminate the state of the system at the time of failure.
- **Present results clearly.** When reporting property statuses, use a table or list. When reporting log findings, include the virtual timestamp, source, container, and log text.
- **Offer the report in a browser; don't paste the signed URL.** When the user wants to see the full triage report, suggest `snouty runs show <RUN_ID> --web` rather than printing the long `links.triage_report` URL. `--web` works only when a triage report exists. See `references/run-info.md`.

## Suggesting follow-up skills

End your triage summary with a short "next steps" section that names follow-up skills or additional triage workflows when they would help. Treat these as suggestions for the user, not actions to take automatically — let the user (or their orchestration) decide when to invoke them. If the user has explicitly asked to chain skills (e.g. "run triage and then debug any failing property"), follow their instructions and proceed with the chain.

Skills worth suggesting based on what triage uncovers:

- **`antithesis-research`** — map the codebase to surface better testable properties. Useful when failures point to systemic gaps in coverage rather than a discrete bug.
- **`antithesis-workload`** — extend or refine assertions, test commands, and logs. Should be suggested whenever all properties are passing to incrementally improve the workload, or when properties are not reachable due to the workload being underpowered. This skill can also be used to add more logging or fix properties to assist with root cause analysis.
- **`antithesis-debug`** — run shell commands inside the run at the failing moment, or an earlier one, with `snouty runs exec` to inspect container, process, and on-disk state. Useful when log analysis alone hasn't explained the failure. Requires snouty. A finished run needs a debugging session, which uses core hours until it is cancelled.
- **`antithesis-mutation-testing`** — prove the properties can actually fail, by injecting one realistic bug per property and confirming each one fires. Suggest this **only** when the run came back green (no failing properties, so there is no SUT bug to chase first) **and** there is no sign the catalog has already been mutation tested — check for a `## Falsification` section in the scratchbook's property evidence files, or an `antithesis/scratchbook/mutation-testing/` directory. An all-green report is exactly the situation where you cannot tell a well-guarded system from a catalog that would never notice a problem.

Include the data the next skill will need (run_id, property name, moment, etc.) so the user can invoke it without re-discovering context.

## Self-Review

Before declaring this skill complete, review your work against the criteria below. This skill's output is conversational (summaries, tables, analysis), so the review should happen in your current context. Re-read the guidance in this file, then systematically check each item below against the answers and analysis you produced.

Review criteria:

- Every property status reported (passed, failed, unfound) was extracted from the actual properties fetch, not inferred or assumed
- Findings reference specific data from the properties data — property names, assertion text, log lines, timestamps
- Failed properties with available logs include actionable context: the assertion text, relevant log lines, and timeline context. Conclusions about failures are grounded in log evidence when logs exist
- The summary distinguishes between what the report shows and what you interpret or recommend
- If comparing runs, differences are grounded in data from both reports, not just one
- Claims that a binary is not instrumented follow `references/instrumentation.md` and do not rest only on the deduplicated examples of the `Software was instrumented` property