/trace

name: trace
description: "Dispatch trace subagent to investigate unknown issues — reproduces, traces, and reports root cause for fix handoff."

trace — Investigation and Root Cause Analysis

**Runtime syntax:** in Codex, invoke the plugin copy with the owner-qualified `$genie:<skill>` selector; use bare `$<skill>` only when intentionally selecting a user-tier copy (a separately installed personal copy; Genie no longer seeds this tier). Claude Code and Hermes use `/<skill>`. Cross-skill prose below uses bare names as portable semantic routes; the orchestrator resolves the selector for the active tier.

Investigate unknown failures: dispatch a trace subagent to reproduce, trace, and isolate root cause, then hand the report to `fix`. The deliverable is findings only — report and stop; never apply fixes, however obvious.

When to Use

• A failure exists but the cause is unknown
• Stack traces or error messages don't point to an obvious defect
• Multiple files or systems may be involved
• `review` hit a failure with unclear root cause and needs a diagnosis before `fix`

Flow

1. **Collect symptoms:** error messages, stack traces, logs, and expected vs actual behavior from the wish or reporter. 2. **Dispatch tracer:** native delegation surface → trace subagent, briefed with the symptoms, relevant context (files, recent changes, environment), and read-only stop conditions (see Dispatch). 3. **Investigate:** the tracer reproduces, hypothesizes, traces, and isolates root cause autonomously. 4. **Receive report:** the tracer's final message is the diagnosis (format below); the native team notifies you on completion — no polling. 5. **Hand off:** pass the report to `fix`, or escalate to the orchestrator.

Report Format

Root cause: <what's actually broken — file, line, condition>
Evidence: <reproduction steps, traces, proof>
Causal chain: <root cause → intermediate effects → observed symptom>
Recommended correction: <what to change, where, why>
Affected scope: <other files or features impacted>
Confidence: <high / medium / low>

Include file paths and line numbers in every root-cause claim so `fix` can act without re-investigating. If root cause spans multiple systems, report each separately with its own confidence level.

Dispatch

Trace runs through a fresh read-only scout/explorer role on the active runtime (Codex profile `genie_scout` when installed). It may search files and run non-mutating diagnostic commands, but it must not edit, stage, commit, or publish. Use native follow-up messaging to keep the same investigation context.

Rules

• Report findings and stop — investigation only. `fix` applies the correction; never combine the two.
• Reproduce before theorizing — if the failure can't be reproduced, the report must say so.
• Evidence required: every root-cause claim carries file paths, line numbers, and a causal chain grounded in tool output from this session — never inferred from memory.
• **Verify symbols before citing them.** Confirm every function named in "Recommended correction" via `grep -n "export.*<name>"` against the actual file — a hallucinated name sends `fix` into a failing type-check and wastes a fix loop.

Session close (required)

When spawned as a native subagent, your final message IS the completion signal — the orchestrator is notified when you finish; do not poll or emit a separate contract call. End with exactly one terminal outcome as the last word:

• **done** — diagnosis delivered in the Report Format with root cause, evidence, and confidence.
• **blocked** — cannot proceed (unreproducible without missing access, environment unavailable). State exactly what you need.
• **failed** — aborted or irrecoverable. State why.

`blocked` / `failed` must include a one-line reason.