version: "1.0.0" name: "godmode:observability-as-infrastructure" description: > Structured tracing for all godmode helpers and subagents. Every script invocation, branching decision, and agent lifecycle transition is recorded as a JSONL event. Use when diagnosing session failures, auditing agent convergence, or reviewing cross-session continuity. requires: [] next: []

Observability as Infrastructure

The trace file is the infrastructure. No external monitoring needed — every helper and agent emits structured events to .ctx/godmode/traces/trace.jsonl, the same append-only file used by the core CLI's start_traced/complete_traced.

Event Schema

All events share a common envelope:

Event kinds

Session identity

Session state lives at .ctx/godmode/session.json. It is created on the first trace write and reused for all subsequent events. session_id = git short SHA

• epoch ms. session-summary.nu uses this to correlate work across sessions.

Shared library

All helpers source skills/_lib/trace.nu:

use ($"(repo-root)/skills/_lib/trace.nu") *
 
def main [...] {
    let tid = (trace-start "skill-name" "helper.nu" ...$args)
    # ... do work, capture results via | complete ...
    if $result.exit_code != 0 {
        trace-error $tid $result.exit_code $result.stderr
        exit $result.exit_code
    }
    trace-end $tid
}

Branching decisions:

trace-decision "ci-fix" "fetch-failure.nu" "ci_class" "test_failure"
trace-decision "tackle-issues" "integrate-branches.nu" "skip_reason" "BLOCKED.md found for #7"

Agent lifecycle (called by the orchestrator, not the subagent):

trace-agent-start    $agent_id $slot $crate
trace-agent-complete $agent_id $slot $commits
trace-agent-blocked  $agent_id $slot $reason

Query helpers

Instrumentation contract

Every helper must:

1. Call trace-start before any work; capture the returned trace_id.
2. Wrap every run-external call with | complete and check exit_code.
3. Call trace-error on non-zero exit before calling exit.
4. Call trace-end on success.
5. Emit trace-decision at every branching point that affects outcome.

Trace writes are non-fatal — a failed append must never abort the helper. Wrap in try { ... } if the .ctx/ directory may not exist.

Guardrails

• Never delete .ctx/godmode/traces/trace.jsonl — archive it instead.
• session_id is read-only after creation. Never mutate .ctx/godmode/session.json.
• Trace writes must not block the main workflow — keep event payloads small.
• stderr_tail is capped at 10 lines to avoid bloating the trace file.