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:

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:

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