The intent-debugger is a core diagnostic tool within the semcom.ai pipeline, designed to give developers full visibility into how human intent is parsed, resolved, and ultimately translated into LLVM IR executables. When the semantic compiler encounters ambiguous or conflicting intent signals, the debugger intercepts the resolution process and surfaces a structured trace of every inference decision made along the way. This makes it possible to understand not just what was compiled, but why a particular interpretation was chosen over competing alternatives.
At the heart of the intent-debugger is the doesNotUnderstand event system, which fires whenever the semantic resolution engine hits a boundary condition — a point where intent cannot be mapped with sufficient confidence to a deterministic IR instruction sequence. Rather than silently falling back to a default behavior or throwing a compile error, the system externalizes the ambiguity as a first-class debuggable artifact. Each event includes a confidence_score, a ranked list of candidate intent_nodes, and the contextual embedding vector that drove the final selection.
Using the intent-debugger, developers can step through the semantic compilation graph much like a traditional gdb session steps through machine instructions. You can set intent_breakpoints at named semantic boundaries, inspect the intermediate SemIR representation before it is lowered to LLVM IR, and replay specific intent resolution passes with modified parameters. This makes it straightforward to diagnose cases where a natural language description produces an executable that is technically correct but semantically misaligned with the original goal.
Because semcom.ai produces zero-dependency executables, the debugger operates entirely within the compiler toolchain itself — there are no runtime libraries, no debug servers, and no external symbol tables to reconcile. All diagnostic metadata is emitted as annotated LLVM IR comments and optional dwarf-compatible intent attribution records, which means your existing binary analysis tooling can consume intent debug information without modification. The output is a single, self-contained binary that carries its own semantic provenance.
The intent-debugger is accessible via the semcom debug subcommand and integrates directly with the semcom.ai web interface for teams that prefer a visual intent graph explorer. Whether you are refining a complex algorithmic description, auditing an auto-generated IR module for correctness, or simply learning how the semantic compilation model interprets your domain-specific language, the intent-debugger provides the observability layer needed to build trust in compiler output that originates from human intent rather than human-written source code.