trace

---
name: trace-ce821398e5b9
description: Evidence-driven tracing and execution tracking. Use for "trace this", "execution trace", and "track progress".
trigger: /oma:trace
---

## Skill: trace

Track and document execution flow with evidence.

## When to Use

- Complex execution paths
- Debugging multi-step processes
- Understanding code flow
- Performance analysis
- Compliance auditing

## Trace Elements

### Entry Point
Where execution begins.
- File and line
- Function name
- Arguments
- Timestamp

### Execution Steps
Individual operations.
- Operation performed
- Input/output
- Duration
- Success/failure

### Handoffs
Transfers between components.
- From component
- To component
- Data passed
- Context preserved

### Decisions
Branching points.
- Condition evaluated
- Options considered
- Path chosen
- Rationale

### Exit Point
Where execution ends.
- Final result
- Duration
- Side effects

## Trace Levels

### DEBUG
Full detail, all operations.
- Every function call
- All variable values
- Complete timing

### INFO
Key operations only.
- Major steps
- Handoffs
- Decisions

### WARN
Warnings and errors.
- Problem detection
- Recovery attempts
- Failures

### ERROR
Failures only.
- Exception details
- Stack traces
- Impact assessment

## Trace Storage

### In-Memory
Fast, temporary.
- Current session only
- Limited history
- Quick access

### File-Based
Persistent.
- `traces/` directory
- JSON format
- Searchable

### External
For distributed systems.
- Jaeger
- Zipkin
- Custom collector

## Commands

### Start Trace
```
/oma:trace start {name}
```

### Add Event
```
/oma:trace event {type} {description}
```

### Add Span
```
/oma:trace span {name} {duration}
```

### End Trace
```
/oma:trace end
```

### List Traces
```
/oma:trace list
```

### View Trace
```
/oma:trace view {trace-id}
```

## Output Format

```
## Trace: {name}

### Summary
**Started:** {timestamp}
**Duration:** {duration}
**Status:** {running|complete|error}

### Timeline
```
{time}  Entry: {component}::{function}()
{time}  ├── Event: {event}
{time}  ├── Span: {span} ({duration})
{time}  └── Exit: {result}
```

### Spans
| Name | Duration | Start | End |
|------|----------|-------|-----|
| {span} | {dur} | {time} | {time} |

### Events
| Time | Type | Description |
|------|------|-------------|
| {time} | {type} | {desc} |

### Handoffs
| From | To | Data |
|------|----|------|
| {src} | {dst} | {data} |

### Errors
- **{error}** at {location}

### Attachments
- {file/link}
```

## Constraints

- Don't over-trace
- Use appropriate levels
- Secure sensitive data
- Clean old traces
- Make traces queryable