antithesis-triage

What this skill does

# Antithesis Run Triage

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 not at least version 0.5.0. Use `snouty --version` to find the version.
- DO NOT PROCEED if `jq` is not installed. See `https://jqlang.org/download/` for installation options.
- **Note:** `snouty runs` may be hidden from `snouty --help` but is still supported. If you need to confirm availability or see subcommand syntax, `snouty runs --help` still works.

### Preflight: confirm triage can work

This version of the triage skill talks to Antithesis through the snouty API (`snouty runs ...`). Before doing any work, confirm the setup is ready with the following command:

```bash
snouty doctor
```

If this command reports any failure, relay that failure to the user and stop. Do not attempt to interact with the Antithesis API until it passes.

You can skip preflight if you already know (from context or memory) that the user's setup is working.

## Gathering user input

Before starting, collect the following from the user:

1. **Tenant Name** (required) — You must know the tenant name. Check the `$ANTITHESIS_TENANT` environment variable. Ask the user if you do not have evidence for the tenant name.

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. Build a detailed summary of the run including a review of all failures as well as flagging any new failures.

### 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 `snouty runs --json logs $RUN_ID $INPUT_HASH $VTIME`. Make sure vtime does not get rounded. `input_hash` and `vtime` should match exactly what is contained in the example's `moment` structure.
   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.

   When searching for additional logs for property failures, first use:

   ```bash
   snouty runs --json events ${RUN_ID} ${PROPERTY_NAME}
   ```

   This returns SOME but not necessarily ALL cases of the property passing or failing in the run. PROPERTY_NAME should match the "name" field
   in the property data you are investigating. Match the "hit" and "condition" fields against the examples or counterexamples you are trying to find more of. Note that it is likely the examples and counterexamples you already know about will be in the list returned. Check the moment of the property returned from `snouty runs events` against the moment in the examples or counterexamples 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.

### 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.

## 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 discret