Trace

---
name: trace
description: Follow causality - trace backward (why did X happen?) or forward (what will X cause?)
accepts_args: true
arg_schema:
  - name: event
    required: true
    description: "Event or observation to trace (starting point)"
  - name: direction
    required: false
    description: "Optional: 'backward' (default, root cause) or 'forward' (consequences)"
composition:
  - skill: research
---

# Trace Command

**Purpose**: Follow causal chains backward or forward

**Core Principle**: "Follow the thread" - understand how one thing leads to another

**When to use**:
- Retrying loop (trace backward to root cause)
- Impact analysis (trace forward to consequences)
- Debugging (why did this fail?)
- Understanding data flow
- Following execution paths

---

## Execution Flow

### Phase 1: Identify Direction

**Backward tracing** (default): Why did X happen?
- Start from observed event
- Work backward through causal chain
- Find root cause(s)

**Forward tracing**: What will X cause?
- Start from proposed change/event
- Work forward through causal chain
- Predict downstream effects

---

### Phase 2: Build Causal Chain

**For each step in the chain**:

1. **Identify immediate cause/effect**:
   - What directly caused this? (backward)
   - What will this directly cause? (forward)

2. **Gather evidence**:
   - Code: Execution paths, function calls
   - Data: Value transformations, state changes
   - Logs: Observed sequences
   - Configuration: Settings that affect behavior

3. **Continue until terminal condition**:
   - Backward: Reach root cause (external input, configuration, user action)
   - Forward: Reach final effect (output, side effect, state change)

---

### Phase 3: Identify Contributing Factors

At each step:
- **Primary cause**: Main reason this occurred
- **Contributing factors**: Conditions that enabled/amplified
- **Confidence level**: How certain are we about this link?

---

### Phase 4: Detect Principle Violations (NEW)

**For each step in causal chain, check if CLAUDE.md principles were violated**:

Step: "Lambda timeout because no timeout config in code"

Principle violations:

• ❌ Principle #20 (Execution Boundaries): Didn't verify Lambda timeout matches code requirements
• ❌ Principle #1 (Defensive Programming): No validation of external API call duration
• ❌ Principle #2 (Progressive Evidence): Stopped at code inspection, didn't verify runtime config

Violation enabled this step: YES How: Not verifying execution boundaries allowed mismatch between code needs (120s) and Lambda config (30s)

**Pattern**: Principle violation → Enabled failure → Appeared in causal chain

**Why detect violations**:
- Reveals which principles, if followed, would have prevented issue
- Connects failures to specific CLAUDE.md guidance
- Identifies systematic compliance gaps

**Violation categories**:
1. **Prevented failure**: Following principle would have blocked this step entirely
2. **Early detection**: Following principle would have caught issue earlier
3. **Better recovery**: Following principle would have reduced impact

---

### Phase 5: Generate Causal Diagram

Visualize chain:

[Root Cause] → [Step 1] → [Step 2] → [Observed Effect] ↓ ↓ ↓ [Contributing] [Contributing] [Contributing]

---

## Output Format

```markdown
## Trace Analysis: {event} ({direction})

### Starting Point

**Event**: {What we're tracing from}

**Direction**: {Backward (root cause) | Forward (consequences)}

**Context**: {Relevant background information}

---

## Causal Chain

### Step 1: {event-name}

**What happened**: {Description of this step}

**Caused by** (backward) / **Causes** (forward): {Previous/next step in chain}

**Evidence**:
- Code: `{file:line}` - {What code shows}
- Logs: {What logs show}
- Data: {What data shows}

**Contributing factors**:
- {Factor 1}: {How it contributed}
- {Factor 2}: {How it contributed}

**Principle violations** (if any):
- ❌ Principle #{X} ({Name}): {How violated}
  - Impact: {How violation enabled this step}
  - Prevention: {How following principle would have helped}

**Confidence**: High | Medium | Low

---

### Step 2: {event-name}

[... repeat structure ...]

---

### Terminal: {root-cause OR final-effect}

**What happened**: {Description}

**Why this is terminal**:
- Backward: This is the root cause because {reason}
- Forward: This is the final effect because {reason}

**Evidence**: {Supporting evidence}

---

## Causal Diagram

{Visual representation of chain}

Example (backward): [External API Timeout] → [Lambda Waits] → [Lambda Timeout] → [User Error] ↓ ↓ ↓ [No timeout config] [25s API limit] [30s Lambda limit]

---

## Analysis

### Primary Causal Path

{Narrative explanation of how we got from start to end}

### Key Contributing Factors

1. **{Factor 1}**: {How it contributed to the chain}
2. **{Factor 2}**: {How it contributed to the chain}

### Confidence Assessment

**Overall confidence**: High | Medium | Low

**Why**: {Explanation of confidence level}

**Uncertainty areas**:
- {What we're not sure about}
- {What we're not sure about}

---

## Principle Violations Summary

**Total violations found**: {N}

### Critical Violations (Prevented Failure)

**Principle #{X} ({Name})**: {How violated}
- **Where in chain**: {Which step(s)}
- **Impact**: {How violation enabled failure}
- **Prevention**: {What would have happened if principle followed}
- **Fix**: {How to apply principle going forward}

[Repeat for each critical violation]

### Early Detection Violations

**Principle #{Y} ({Name})**: {How violated}
- **Where in chain**: {Which step(s)}
- **Impact**: {Would have caught issue earlier}
- **Fix**: {How to apply principle}

[Repeat for each early detection violation]

### Recovery Violations

**Principle #{Z} ({Name})**: {How violated}
- **Impact**: {Would have reduced impact}
- **Fix**: {How to apply principle}

---

## Recommendations

**Based on