# dotTrace DTP Parser Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Add a Python-first tool that reads a raw dotTrace `.dtp` snapshot family and emits JSON call-tree and hotspot data for LLM analysis.

**Architecture:** A small .NET helper uses JetBrains’ local dotTrace assemblies to decode snapshot storage, performance call-tree nodes, payloads, and metadata. A Python wrapper validates input, builds the helper if needed, runs it, and writes the resulting JSON.

**Tech Stack:** Python 3 standard library, .NET 10 console app, local JetBrains dotTrace assemblies, `unittest`

---

### Task 1: Add the failing end-to-end test

**Files:**
- Create: `tools/tests/test_dtp_parser.py`

**Step 1: Write the failing test**

Write a `unittest` test that runs:

```bash
python3 tools/dtp_parse.py snapshots/js-ordered-consume.dtp --stdout
```

and asserts:

- exit code is `0`
- stdout is valid JSON
- `call_tree.children` is non-empty
- `hotspots.inclusive` is non-empty
- at least one node name is not marked as special

**Step 2: Run test to verify it fails**

Run: `python3 -m unittest tools.tests.test_dtp_parser -v`

Expected: FAIL because `tools/dtp_parse.py` does not exist yet.

**Step 3: Commit**

```bash
git add tools/tests/test_dtp_parser.py
git commit -m "test: add dtp parser end-to-end expectation"
```

### Task 2: Implement the .NET snapshot extractor

**Files:**
- Create: `tools/DtpSnapshotExtractor/DtpSnapshotExtractor.csproj`
- Create: `tools/DtpSnapshotExtractor/Program.cs`

**Step 1: Write the minimal implementation**

Implement a console app that:

- accepts snapshot path and optional output path
- opens the snapshot through JetBrains snapshot storage
- constructs performance call-tree and payload readers
- resolves method names via metadata sections
- builds a JSON object with root tree, thread roots, and hotspot lists
- writes JSON to stdout or output file

**Step 2: Run helper directly**

Run:

```bash
dotnet run --project tools/DtpSnapshotExtractor -- snapshots/js-ordered-consume.dtp
```

Expected: JSON is emitted successfully.

**Step 3: Commit**

```bash
git add tools/DtpSnapshotExtractor/DtpSnapshotExtractor.csproj tools/DtpSnapshotExtractor/Program.cs
git commit -m "feat: add dottrace snapshot extractor helper"
```

### Task 3: Implement the Python entrypoint

**Files:**
- Create: `tools/dtp_parse.py`

**Step 1: Write the minimal implementation**

Implement a CLI that:

- accepts snapshot path
- supports `--out` and `--stdout`
- checks that dotTrace assemblies exist in the local install
- runs `dotnet run --project tools/DtpSnapshotExtractor -- <snapshot>`
- forwards JSON output

**Step 2: Run the wrapper**

Run:

```bash
python3 tools/dtp_parse.py snapshots/js-ordered-consume.dtp --stdout
```

Expected: JSON is emitted successfully.

**Step 3: Commit**

```bash
git add tools/dtp_parse.py
git commit -m "feat: add python dtp parsing entrypoint"
```

### Task 4: Make the test pass and tighten output

**Files:**
- Modify: `tools/DtpSnapshotExtractor/Program.cs`
- Modify: `tools/dtp_parse.py`
- Modify: `tools/tests/test_dtp_parser.py`

**Step 1: Run the failing test**

Run: `python3 -m unittest tools.tests.test_dtp_parser -v`

Expected: FAIL with an output-schema or execution issue.

**Step 2: Fix the minimal failing behavior**

Adjust:

- special-node labeling
- JSON schema stability
- helper invocation details
- fallback behavior for unresolved metadata

**Step 3: Re-run the test**

Run: `python3 -m unittest tools.tests.test_dtp_parser -v`

Expected: PASS

**Step 4: Commit**

```bash
git add tools/DtpSnapshotExtractor/Program.cs tools/dtp_parse.py tools/tests/test_dtp_parser.py
git commit -m "test: verify dtp parser output"
```

### Task 5: Final verification

**Files:**
- Modify: none unless fixes are required

**Step 1: Run end-to-end extraction**

Run:

```bash
python3 tools/dtp_parse.py snapshots/js-ordered-consume.dtp --out /tmp/js-ordered-consume-calltree.json
```

Expected: JSON file is created.

**Step 2: Run test suite**

Run:

```bash
python3 -m unittest tools.tests.test_dtp_parser -v
```

Expected: PASS

**Step 3: Inspect a hotspot sample**

Confirm the JSON contains:

- resolved method names
- inclusive and exclusive hotspot lists
- nested thread call trees

**Step 4: Commit**

```bash
git add docs/plans/2026-03-14-dtp-parser-design.md docs/plans/2026-03-14-dtp-parser.md
git commit -m "docs: add dtp parser design and plan"
```