| name | explain |
| description | Parse and interpret Z3 output for human consumption. Handles models, unsat cores, proofs, statistics, and error messages. Translates solver internals into plain-language explanations. |
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 |
