> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automagik.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# /trace

> Dispatch trace subagent to investigate unknown issues — reproduces, traces, and reports root cause for /fix handoff.

# /trace — Investigation and Root Cause Analysis

Investigate unknown failures. Dispatch a trace subagent to reproduce, trace, and isolate root cause — then hand the report to `/fix`.

## 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` encounters a failure with unclear root cause

## Flow

1. **Collect symptoms** — gather error messages, stack traces, logs, and expected vs actual behavior.
2. **Dispatch tracer** — the spawned agent performs a read-only inline investigation.
3. **Investigate** — the tracer autonomously reproduces, hypothesizes, traces, and isolates root cause.
4. **Signal findings** — tracer reports back to the leader via `genie send`.
5. **Receive report** — structured diagnosis.
6. **Hand off** — pass the report to `/fix` or escalate.

## Report Format

```text theme={"dark"}
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
```

## Dispatch

Trace runs in **isolation** — the subagent must not modify any source files.

```bash theme={"dark"}
# Spawn a tracer subagent (read-only investigation)
genie spawn tracer
```

The tracer uses only read-only tools: Read, Bash, Glob, Grep. No Write, no Edit.

## Task Lifecycle Integration

When a PG task exists for the work being investigated, findings are logged as task comments:

| Event                | Command                                                                          |
| -------------------- | -------------------------------------------------------------------------------- |
| Investigation start  | `genie task comment #<seq> "Trace: investigating — [symptom summary]"`           |
| Root cause found     | `genie task comment #<seq> "Root cause: [summary] — [file:line]"`                |
| Multiple causes      | `genie task comment #<seq> "Root causes: [count] identified — see trace report"` |
| Investigation failed | `genie task comment #<seq> "Trace: could not determine root cause — [reason]"`   |

File paths and line numbers are included in every root cause comment so task history is actionable without reading the full report. Task integration is graceful — if no PG task exists, logging is skipped.

## Rules

* Never fix during trace — investigation only, always separate from correction
* Always reproduce before theorizing
* Evidence required — every root cause claim must include file paths, line numbers, and a causal chain
* Hand off to `/fix` — trace produces a report, `/fix` applies the correction
* If root cause spans multiple systems, report each separately with confidence levels