Antithesis Research

Antithesis Research

Skill version: 2026-09-22 da29297

Purpose and Goal

Research a target system and produce scratchbook artifacts that unblock the rest of the workflow. Success means:

• antithesis/scratchbook/sut-analysis.md captures architecture, state, concurrency, and failure-prone areas
• antithesis/scratchbook/property-catalog.md lists concrete, testable properties with priorities
• antithesis/scratchbook/deployment-topology.md describes the minimal useful container topology
• antithesis/scratchbook/properties/{slug}.md captures per-property evidence trails and context
• antithesis/scratchbook/property-relationships.md maps suspected clusters and connections between properties
• antithesis/scratchbook/evaluation/synthesis.md records categorized evaluation findings and actions taken

Prerequisites and Scoping

At the start of every research run, ask the user about external references:

Before I start, are there docs, design notes, related repos, issue trackers, or anything else outside this directory tree that I should also consult? "Just this directory" is fine.

Capture the answer verbatim. Each external reference becomes a path (or URL) plus a brief why note. The orchestrator (this skill) holds the answer for the full duration of the run and threads it as input to every reference workflow that produces a top-level artifact: sut-discovery.md, sut-analysis.md, property-discovery.md, deployment-topology.md, property-evaluation.md. Each of those references' agent-instruction sections accepts the list as input. The list is also recorded in the provenance frontmatter of every top-level artifact (see references/scratchbook-setup.md). Any agent that receives the external references treats each as a lead to validate, not a fact — see references/validating-claims.md.

Beyond the scope question, ask only for blockers or scoping decisions you cannot infer safely:

• The repo or codebase location, if it is not already clear
• Which subsystem or component matters most, if the work is narrower than the whole repo
• Known incidents, closed bugs, or specific failure modes worth targeting

If scratchbook artifacts already exist, treat them as inputs and extend them instead of rewriting them unless the user asks for a fresh pass.

Definitions and Concepts

• SUT: System under test.
• Workload: A synthetic workload designed to exercise the target system
• Safety property (correctness): A bad thing never happens
• Liveness property (progress): A good thing eventually happens
• Reachability property: A code path or behavior is reachable or unreachable
• Test Template: A directory of test commands located at /opt/antithesis/test/v1/{name}/. There may be more than one test template. Each timeline executes commands from a single test template. Files or subdirectories prefixed with helper_ are ignored by Antithesis.
• Test Command: An executable file in a Test Template with a valid prefix. Valid prefixes: parallel_driver_, singleton_driver_, serial_driver_, first_, eventually_, finally_, anytime_
• Timeline: A single linear execution of the target system and workload. Antithesis runs many timelines in parallel and branches them to search for interesting behaviors.

Documentation Grounding

Use the antithesis-documentation skill to ground Antithesis-specific terminology and implementation advice.

• Properties and assertions: https://antithesis.com/docs/concepts/properties_assertions/assertions.md
• Sometimes assertions: https://antithesis.com/docs/concepts/properties_assertions/sometimes_assertions.md
• Define test properties: https://antithesis.com/docs/reference/sdk/define_test_properties.md
• SDK runtime modes and production behavior: https://antithesis.com/docs/reference/sdk.md
• Optimize for testing: https://antithesis.com/docs/best_practices/optimizing.md

Reference Files

Recommended Workflows

Full research pass (new project)

1. Read references/scratchbook-setup.md
2. Read references/sut-discovery.md and references/sut-analysis.md
3. Analyze the system using the ensemble or single-agent workflow from references/sut-discovery.md
4. Scan the codebase for existing Antithesis SDK assertions. Search for imports of the Antithesis SDK and calls to assertion functions (assert_always!, assert_sometimes!, assert_reachable!, assert_unreachable!, or their non-macro equivalents). For each assertion found, record the file path, line number, assertion type, and message string. Write the results to antithesis/scratchbook/existing-assertions.md. Begin the file with provenance frontmatter per references/scratchbook-setup.md. If no assertions are found, write the file with a note confirming the codebase has no existing instrumentation.
5. Read references/property-discovery.md and references/property-catalog.md
6. Discover properties using the ensemble or single-agent workflow from references/property-discovery.md
7. Read references/deployment-topology.md
8. Design the deployment topology and write it to antithesis/scratchbook/deployment-topology.md
9. Read references/property-evaluation.md
10. Evaluate the property catalog using the ensemble or single-agent workflow from references/property-evaluation.md
11. Address evaluation findings: apply refinements, fill gaps, escalate biases to the user
12. Write or update all remaining findings in the scratchbook under antithesis/scratchbook/

Targeted property research

1. Read references/sut-discovery.md and references/sut-analysis.md if the system model is missing or stale
2. Read references/property-discovery.md and references/property-catalog.md
3. Discover properties using the ensemble or single-agent workflow from references/property-discovery.md
4. Turn claimed guarantees into explicit properties. For incidents and bug reports, confirm the reported defect is a real system defect before making it a property (see references/validating-claims.md). Choose the Antithesis assertion type that matches each one
5. Update antithesis/scratchbook/property-catalog.md and record assumptions or open questions
6. Write evidence files for new properties to antithesis/scratchbook/properties/{slug}.md
7. Update antithesis/scratchbook/property-relationships.md with any new clusters or connections
8. Read references/property-evaluation.md
9. Evaluate the updated property catalog using the ensemble or single-agent workflow from references/property-evaluation.md
10. Address evaluation findings: apply refinements, fill gaps, escalate biases to the user

Property expansion (after triage)

1. Read references/property-discovery.md and references/property-catalog.md