---
name: call-chain
role: entrypoint
description: Traces execution paths through the code graph with criticality scoring and Mermaid charts. Use when understanding how a function propagates through the system.
---

# Call Chain Tracing

Trace execution flows through the codebase using the
code knowledge graph.

## When NOT To Use

- Static import relationships (use `cartograph:dependency-graph`)
- Scoring the risk of a change (use `pensive:blast-radius`)

## Prerequisites

This skill requires the **gauntlet** plugin for graph
data. Discover it:

```bash
GRAPH_QUERY=$(find ~/.claude/plugins -name "graph_query.py" -path "*/gauntlet/*" 2>/dev/null | head -1)
```

**If gauntlet is not installed**: Fall back to static
analysis. Use `grep` to trace function calls and build
a Mermaid diagram manually from import/call patterns.
Skip graph-specific steps.

**If installed but no graph.db**: Tell the user to run
`/gauntlet-graph build`.

## Steps

1. **Accept target**: Get a function name or entry point
   from the user (or trace all entry points).

2. **Run flow tracing** (requires gauntlet):
   ```bash
   python3 "$GRAPH_QUERY" --action flows --depth 15
   ```

   To filter by entry point:
   ```bash
   python3 "$GRAPH_QUERY" --action flows --entry "main"
   ```

   **Fallback (no gauntlet)**: Trace calls with rg (or grep):
   ```bash
   # Prefer rg (ripgrep) for speed; fall back to grep
   if command -v rg &>/dev/null; then
     rg -n "function_name\(" --type py . | head -20
   else
     grep -rn "function_name(" --include="*.py" . | head -20
   fi
   ```
   Build the call tree manually from search results.

3. **Display as indented tree**:
   ```
   main() [criticality: 0.72]
     -> validate_input()
       -> parse_config()
     -> process_data()
       -> db.execute_query()
       -> cache.store()
     -> send_response()
   ```

4. **Generate Mermaid flowchart**:
   ```mermaid
   flowchart LR
     main --> validate_input
     main --> process_data
     main --> send_response
     validate_input --> parse_config
     process_data --> db.execute_query
     process_data --> cache.store
   ```

5. **Show criticality breakdown**:
   - File spread: how many files the flow touches
   - Security sensitivity: auth/crypto code in the path
   - Test coverage gaps: untested nodes in the flow

## Criticality Scoring

| Factor | Weight | Meaning |
|--------|--------|---------|
| File spread | 0.30 | Touches many files |
| Security | 0.25 | Contains auth/crypto code |
| External calls | 0.20 | Unresolved dependencies |
| Test gap | 0.15 | Untested nodes in flow |
| Depth | 0.10 | Deep call chains |

## Exit Criteria

- [ ] Indented call tree displayed for the target function with
      criticality scores in the form `[criticality: N.NN]`
- [ ] Mermaid `flowchart LR` generated with edges representing
      each caller-to-callee relationship in the traced path
- [ ] Criticality breakdown table shown covering: file spread,
      security sensitivity, external calls, test gap, and depth
- [ ] If gauntlet is not installed, fallback to static `rg`/`grep`
      analysis is used and the absence of graph data is noted
- [ ] If gauntlet is installed but `graph.db` is absent, user is
      told to run `/gauntlet-graph build` before the skill halts