Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/modiqo/skillspec/llms.txt

Use this file to discover all available pages before exploring further.

The trace subcommands operate on the run directories created by decide, act, and run-loop when --trace-dir is supplied. Each run directory holds the append-only decision event files from a single routing decision, plus the execution evidence accumulated by progress subcommands. trace align is the primary verification step: it replays the decision trace against the current spec and checks structured execution evidence for every active obligation. trace compact rebuilds the summarized JSONL files from raw event files, which is useful after a run completes or when the run directory was written by multiple incremental commands.
Always use --quiet when running trace align during normal agent execution. Without --quiet, the command emits a full transcript of every check result, which is expensive in context tokens and not needed for routine proof. Quiet mode still writes alignment.json and the proof digest to the run directory and still exits non-zero on failures.

​
Run Directory Structure

Every trace run directory has the following layout: 
.skillspec/traces/run-<timestamp>-<pid>/
├── events/                  # Append-only individual decision event files
│   ├── 000001.input_received.json
│   ├── 000002.route_selected.json
│   └── ...
├── trace.jsonl              # Compacted event stream (rebuilt by trace compact)
├── summary.json             # Compacted summary with event counts and fingerprints
├── execution.jsonl          # Execution evidence ledger (written by progress subcommands)
├── alignment.json           # Alignment report (written by trace align)
└── proof-digest.json        # Proof digest (written by trace align --proof-digest)
The events/ directory is the source of truth. trace.jsonl and summary.json are derived artifacts rebuilt by trace compact. execution.jsonl is separate from the decision trace — it records what the agent actually did during execution.

​
trace align

Replays the decision trace against the current spec and checks the structured execution evidence in execution.jsonl for all active obligations. Produces alignment.json in the run directory and optionally a proof-digest.json that lists missing proof rows grouped by obligation kind. 
skillspec trace align <path> \
  --decision-trace <run-dir> \
  [--execution-trace <jsonl>]... \
  [--quiet] \
  [--summary] \
  [--proof-digest <path>] \
  [--json]

​
Options

FlagTypeDefaultDescription
<path>path(required)Path to the skill.spec.yml file.
--decision-tracedirectory path(required)Run directory containing the decision trace events.
--execution-tracepath(repeatable)Path to an execution evidence JSONL file, typically <run-dir>/execution.jsonl. Repeat to supply multiple ledgers. Omit to run decision-only alignment.
--quietflagoffWrite alignment.json and the proof digest without producing transcript output. Preserves exit status. Use during normal agent execution.
--summaryflagoffPrint a compact alignment summary instead of the full check transcript. Use for debugging or explicit proof inspection only.
--proof-digestpath(none)Path where the proof digest JSON should be written. The digest groups missing proof rows by obligation kind with recommended event names and required fields.
--jsonflagoffEmit the alignment report as JSON and print paths to written files.

​
How alignment works

trace align runs two layers of checks:
  1. Decision replay — Re-runs the current spec on the captured input hash and compares the result (route selection, matched rules, forbids, elicitations, after-success) against what the trace recorded. A mismatch means spec drift or a trace/spec mismatch.
  2. Execution proof — Derives active obligations from the selected route and matched rules (route fulfillment, route checks, forbid non-violations, elicitation answers, after-success completions), then checks execution.jsonl for structured evidence that each obligation was met.
The overall status is one of:
  • pass — decision replay passed and all execution obligations have structured proof.
  • unproven — decision replay passed or had no failures, but one or more obligations lack proof.
  • fail — a deterministic decision check failed (spec drift) or execution evidence actively contradicts an obligation.

​
Examples

Quiet alignment during normal execution (recommended): 
skillspec trace align ./skill.spec.yml \
  --decision-trace .skillspec/traces/run-1712345678-12345 \
  --execution-trace .skillspec/traces/run-1712345678-12345/execution.jsonl \
  --proof-digest .skillspec/traces/run-1712345678-12345/proof-digest.json \
  --quiet
Full JSON alignment report for scripting or CI: 
skillspec trace align ./skill.spec.yml \
  --decision-trace .skillspec/traces/run-1712345678-12345 \
  --execution-trace .skillspec/traces/run-1712345678-12345/execution.jsonl \
  --json
Compact summary for manual debugging: 
skillspec trace align ./skill.spec.yml \
  --decision-trace .skillspec/traces/run-1712345678-12345 \
  --execution-trace .skillspec/traces/run-1712345678-12345/execution.jsonl \
  --summary

​
Output (--json)

{
  "schema": "skillspec.align/v0",
  "ok": true,
  "status": "pass",
  "summary": {
    "scope": "decision_and_execution_trace",
    "decision_alignment": "pass",
    "execution_alignment": "pass",
    "conclusion": "decision alignment passed and supplied execution evidence proves every active obligation",
    "selected_route": "port_skill",
    "matched_rules": ["porting_tasks_use_port_route"],
    "decision_checks": { "total": 8, "pass": 8, "fail": 0, "unproven": 0 },
    "execution_obligations": { "total": 3, "pass": 3, "fail": 0, "unproven": 0 },
    "evidence_gaps": [],
    "phase_requirement_gaps": [],
    "completion": {
      "decision_replay": "pass",
      "phase_order": "pass",
      "requirements": "2/2 proven",
      "missing_proof": ["none"],
      "forbidden_actions": "no violations recorded",
      "alignment": "pass"
    },
    "tokens": { ... }
  },
  "spec": "./skill.spec.yml",
  "decision_trace": ".skillspec/traces/run-1712345678-12345",
  "execution_traces": [".skillspec/traces/run-1712345678-12345/execution.jsonl"],
  "checks": [...],
  "obligations": [...],
  "proof_rows": [...]
}
FieldDescription
statusOverall result: pass, unproven, or fail.
summary.decision_alignmentResult of the decision replay layer.
summary.execution_alignmentResult of the execution proof layer, or not_evaluated if no execution trace was supplied.
summary.evidence_gapsList of unproven obligations with the needed evidence type and recommended event.
summary.phase_requirement_gapsPhase requirements with missing or failed proof rows.
checksIndividual decision replay check results.
obligationsIndividual execution obligation results.
proof_rowsPer-obligation table of expected vs. observed evidence and status.

​
trace compact

Rebuilds trace.jsonl and summary.json from the append-only event files in <run-dir>/events/. Run this after a sequence of incremental trace writes, or when the compacted files are stale or missing. 
skillspec trace compact <run-dir>

​
Options

FlagTypeDefaultDescription
<run-dir>directory path(required)Trace run directory containing an events/ subdirectory.
trace compact always emits JSON reporting the run id, file paths, and event count.

​
Example

Compact a run directory after a multi-step guided run: 
skillspec trace compact .skillspec/traces/run-1712345678-12345
Example output: 
{
  "run_id": "run-1712345678-12345",
  "run_dir": ".skillspec/traces/run-1712345678-12345",
  "event_count": 7,
  "trace_jsonl": ".skillspec/traces/run-1712345678-12345/trace.jsonl",
  "summary_json": ".skillspec/traces/run-1712345678-12345/summary.json"
}
trace align automatically compacts the run directory before reading envelopes, so a manual trace compact call is not strictly required before alignment. It is useful for inspecting the run directory, sharing traces, or rebuilding after the events/ directory was populated by external tooling.

Build docs developers (and LLMs) love

Get started for freeTalk to us