Explain
Testing & QualityexplainExplain is an Agent Skill for testing & quality published in the Z3Prover/z3 repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Parse and interpret Z3 output for human consumption. Handles models, unsat cores, proofs, statistics, and error messages. Translates solver internals into plain-language explanations.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/Z3Prover/z3/blob/HEAD/.github/skills/explain/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/explain, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Given raw Z3 output (from the solve, prove, optimize, or benchmark skills), produce a structured explanation. This skill is for cases where the solver output is large, nested, or otherwise difficult to read directly.
Step 1: Identify the output type
Action: Determine the category of Z3 output to explain: model, core, statistics, error, or proof.
Expectation: The output type maps to one of the recognized formats in the table below.
Result:
If the type is ambiguous, use --type auto and let the script detect it.
Proceed to Step 2.
| Output contains | Explanation type |
|---|---|
(define-fun ...) blocks | model explanation |
| unsat core labels | conflict explanation |
:key value statistics | performance breakdown |
(error ...) | error diagnosis |
| proof terms | proof sketch |
Step 2: Run the explainer
Action: Invoke explain.py with the output file or stdin.
Expectation: The script auto-detects the output type and produces a structured plain-language summary.
Result:
A formatted explanation is printed. If detection fails, re-run with
an explicit --type flag.
python3 scripts/explain.py --file output.txt
python3 scripts/explain.py --stdin < output.txt
python3 scripts/explain.py --file output.txt --debug
Step 3: Interpret the explanation
Action: Review the structured explanation for accuracy and completeness.
Expectation: Models list each variable with its value and sort. Cores list conflicting assertions. Statistics show time and memory breakdowns.
Result: Use the explanation to answer the user query or to guide the next skill invocation.
For models:
- Each variable is listed with its value and sort
- Array and function interpretations are expanded
- Bitvector values are shown in decimal and hex
For unsat cores:
- The conflicting named assertions are listed
- A minimal conflict set is highlighted
For statistics:
- Time breakdown by phase (preprocessing, solving, model construction)
- Theory solver load distribution
- Memory high-water mark
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| file | path | no | file containing Z3 output | |
| stdin | flag | no | off | read from stdin |
| type | string | no | auto | force output type: model, core, stats, error |
| debug | flag | no | off | verbose tracing |
| db | path | no | .z3-agent/z3agent.db | logging database |