pactkit-trace git:20260507.80b3331A

Immutable. This exact content is served forever at /api/v1/blob/783e68f8c95d0712.

---
name: pactkit-trace
description: "Deep code tracing and execution flow analysis"
---

# PactKit Trace

Deep code analysis and execution path tracing via static analysis.

## When Invoked
- **Plan Phase 1** (Archaeology): Trace existing logic before designing changes.
- **Act Phase 1** (Precision Targeting): Confirm call sites before touching code.

## Protocol

### 1. Feature Discovery
- Use `Grep` to locate entry points (API route, CLI arg, Event handler).
- Map core files involved — don't read everything yet.

### 2. Call Graph Analysis
- Run `visualize --mode call --entry <function_name>` to obtain call chains.
- Read `docs/architecture/graphs/call_graph.mmd` to see all reachable functions.

### 3. Deep Tracing
- Follow call chain file by file, recording data transformations.
- Note how data structures change (e.g., `dict` -> `UserObj` -> `JSON`).

### 4. Visual Synthesis
Output a **Mermaid Sequence Diagram** to visualize the flow.

### 5. Topology-Aware Trace (Conditional)
If `detect_topology(root)` returns topologies beyond PDCA/Service:

**Frontend API Topology** (if `api_call` detected):
- Run `api_convention_summary(root)` to get path prefixes, fetch function names, total call count.
- Include conventions in output so downstream code uses the correct API path prefix (e.g., `/api/v1/`) and fetch wrapper (e.g., `apiFetch`).
- Flag any dynamic paths (`[dynamic]` markers) that may need special handling.

**Agent Topology** (if `agent` detected):
- AgentParser extracts orchestration from: LangGraph `StateGraph` (stdlib ast), YAML agent definitions, MCP server configs.
- Include agent nodes and `orchestrates` edges in the report.
- Flag multi-strategy merge results — agents may appear in multiple sources but are deduplicated.

### 6. Archaeologist Report
- **Patterns**: Design Patterns used.
- **Debt**: Hardcoded values, complex logic, lack of tests.
- **Key Files**: Top 3 files critical to this feature.
- **API Conventions** (if frontend): Path prefixes, fetch functions, call count.
- **Agent Flow** (if agents): Orchestration graph, delegation chains.