# Midenc Execution Trace

> Use when working on the Miden compiler (`midenc` / `cargo miden`), debugging failing tests or implementing compiler changes, and you need a Miden VM MASM execution trace to understand the stack state after each instruction. Covers `MIDENC_TRACE=executor=trace` (typically with `cargo make test -- --no-capture ...`).

- Skill: `majiayu000/midenc-execution-trace` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/midenc-execution-trace`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/midenc-execution-trace/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/midenc-execution-trace

---


# MIDENC Trace (MASM execution trace)

## Quick start

- Run a single Rust test with MASM execution tracing enabled:
  - `MIDENC_TRACE=executor=trace cargo make test --no-capture <test_name_or_filter>`
- If you only care about traces on failures (and want faster parallel execution), omit `--no-capture`:
  - `MIDENC_TRACE=executor=trace cargo make test <test_name_or_filter>`
- If you want parallel execution but still want output on passing tests, prefer `--success-output`:
  - `MIDENC_TRACE=executor=trace cargo make test --success-output immediate <test_name_or_filter>`

## What `MIDENC_TRACE=executor=trace` gives you

- A step-by-step trace of MASM execution from the VM executor.
- For each executed instruction/op, it prints the current stack state (practically: the quickest way to answer “what was on the stack right after this instruction?”).

## Recommended workflow for debugging compiler changes

1. Reproduce the issue on the smallest possible test (or add a focused test).
2. Run with live output so you can see the trace stream as the test executes:
   - `MIDENC_TRACE=executor=trace cargo make test --no-capture <test_name_or_filter>`
3. Compare the trace against the expected stack discipline for the procedure(s) you’re debugging:
   - When you see a mismatch, jump to the corresponding emitted MASM (pair with the `emit` skill if you also need `MIDENC_EMIT=masm=...`).

## Practical tips

- Prefer a single test when tracing: `executor=trace` is extremely verbose and slows runs down.
- If you’re running via `cargo nextest` directly, the equivalent “live output” flag is `--no-capture`:
  - `MIDENC_TRACE=executor=trace cargo nextest run --no-capture <filter>`