Add tma-drilldown skill: TMA methodology with PMU event toolkit

.gitignore

@@ -1,3 +1,13 @@
 local.md
 *workspace
 evals/
+
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+.pytest_cache/
+
+# TMA drilldown runtime
+skills/tma-drilldown/sessions/
+skills/tma-drilldown/.venv/

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "skills/tma-drilldown/perfmon"]
+	path = skills/tma-drilldown/perfmon
+	url = https://github.com/intel/perfmon.git

README.md

@@ -42,6 +42,7 @@ Once installed, you can talk to the agent naturally. A few examples:
 | `skills/linux-perf/` | Data collection skill: `perf` workflows, building blocks, hotspot reporting |
 | `skills/performance-patterns/` | Pattern detection and fix playbooks: source code and profiling signals |
 | `skills/phoronix-test-suite/` | Supporting skill: install, run, and optimize PTS benchmarks |
+| `skills/tma-drilldown/` | TMA drill-down: PMU event lookup, perf command generation, cross-platform comparison, iterative bottleneck identification |
 
 ---
 
@@ -112,6 +113,35 @@ Trigger: any `pts/<name>` reference, or the words *"phoronix"* / *"phoronix-test
 
 ---
 
+### `tma-drilldown` — TMA drill-down investigation
+
+**Automate Intel's Top-down Microarchitecture Analysis methodology with deterministic
+PMU event handling.**
+
+When the user needs to identify performance bottlenecks at the microarchitectural
+level, this skill provides:
+
+- **Event/metric lookup** — Search 2600+ PMU events and 300+ TMA metrics across 50+
+  Intel platforms
+- **Command generation** — Generate counter-budget-aware `perf stat` commands (knows
+  GP/fixed counter limits per platform)
+- **Cross-platform comparison** — Diff events and metrics between generations (e.g.,
+  ICX to SPR)
+- **TMA drill-down** — Iterative state-machine engine that walks the TMA tree from L1
+  (Frontend_Bound, Backend_Bound, Bad_Speculation, Retiring) to leaf nodes, generating
+  the right perf commands at each step and providing tuning guidance at the end
+
+Includes a Python CLI (`perfmon-skills`) and the Intel perfmon data repository as a git
+submodule. Complements `linux-perf` (which handles profiling data collection) by
+automating the structured TMA methodology. After bottleneck identification, delegates
+to `performance-patterns` for fix playbooks.
+
+Trigger phrases: *"TMA"*, *"Top-down Microarchitecture Analysis"*, *"PMU events"*,
+*"performance counters"*, *"which events to collect"*, *"counter budget"*,
+*"Frontend_Bound"*, *"Backend_Bound"*, *"platform comparison"*.
+
+---
+
 ## Installation
 
 This skill collection follows the open [Agent Skills standard](https://agentskills.io).
@@ -137,6 +167,7 @@ The easiest way to install across any supported agent. Requires
 gh skill install intel/intel-performance-skills linux-perf
 gh skill install intel/intel-performance-skills performance-patterns
 gh skill install intel/intel-performance-skills phoronix-test-suite
+gh skill install intel/intel-performance-skills tma-drilldown
 ```
 
 Keep them up to date:
@@ -145,6 +176,7 @@ Keep them up to date:
 gh skill update linux-perf
 gh skill update performance-patterns
 gh skill update phoronix-test-suite
+gh skill update tma-drilldown
 ```
 
 ### GitHub Copilot CLI
@@ -155,6 +187,7 @@ Skills are installed per-user under `~/.copilot/skills/`:
 cp -r skills/linux-perf ~/.copilot/skills/
 cp -r skills/performance-patterns ~/.copilot/skills/
 cp -r skills/phoronix-test-suite ~/.copilot/skills/
+cp -r skills/tma-drilldown ~/.copilot/skills/
 ```
 
 ### GitHub Copilot in VS Code
@@ -166,11 +199,11 @@ whole team benefits automatically:
 ```bash
 # Project-level (commit to your repository)
 mkdir -p .github/skills
-cp -r skills/linux-perf skills/performance-patterns skills/phoronix-test-suite \
+cp -r skills/linux-perf skills/performance-patterns skills/phoronix-test-suite skills/tma-drilldown \
     .github/skills/
 
 # User-level (available in every project)
-cp -r skills/linux-perf skills/performance-patterns skills/phoronix-test-suite \
+cp -r skills/linux-perf skills/performance-patterns skills/phoronix-test-suite skills/tma-drilldown \
     ~/.copilot/skills/
 ```
 
@@ -185,11 +218,11 @@ Claude Code discovers skills in `.claude/skills/` (project) or `~/.claude/skills
 ```bash
 # Project-level
 mkdir -p .claude/skills
-cp -r skills/linux-perf skills/performance-patterns skills/phoronix-test-suite \
+cp -r skills/linux-perf skills/performance-patterns skills/phoronix-test-suite skills/tma-drilldown \
     .claude/skills/
 
 # User-level
-cp -r skills/linux-perf skills/performance-patterns skills/phoronix-test-suite \
+cp -r skills/linux-perf skills/performance-patterns skills/phoronix-test-suite skills/tma-drilldown \
     ~/.claude/skills/
 ```
 
@@ -201,11 +234,11 @@ at user level:
 ```bash
 # Project-level
 mkdir -p .agents/skills
-cp -r skills/linux-perf skills/performance-patterns skills/phoronix-test-suite \
+cp -r skills/linux-perf skills/performance-patterns skills/phoronix-test-suite skills/tma-drilldown \
     .agents/skills/
 
 # User-level
-cp -r skills/linux-perf skills/performance-patterns skills/phoronix-test-suite \
+cp -r skills/linux-perf skills/performance-patterns skills/phoronix-test-suite skills/tma-drilldown \
     ~/.agents/skills/
 ```
 
@@ -215,7 +248,7 @@ Gemini CLI reads project skills from `.gemini/skills/`:
 
 ```bash
 mkdir -p .gemini/skills
-cp -r skills/linux-perf skills/performance-patterns skills/phoronix-test-suite \
+cp -r skills/linux-perf skills/performance-patterns skills/phoronix-test-suite skills/tma-drilldown \
     .gemini/skills/
 ```
 
@@ -225,7 +258,7 @@ OpenCode has native skill support and reads skills from `.opencode/skills/`:
 
 ```bash
 mkdir -p .opencode/skills
-cp -r skills/linux-perf skills/performance-patterns skills/phoronix-test-suite \
+cp -r skills/linux-perf skills/performance-patterns skills/phoronix-test-suite skills/tma-drilldown \
     .opencode/skills/
 ```
 

skills/tma-drilldown/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+sessions/
+.venv/

skills/tma-drilldown/CLAUDE.md

@@ -0,0 +1,84 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+perfmon-skills is a performance analysis toolkit that wraps Intel's perfmon data repository (included as a symlink at `./perfmon/`) into CLI tools and Claude Code slash commands. It implements deterministic TMA (Top-down Microarchitecture Analysis) drill-down without requiring an LLM for the core logic.
+
+## Build & Development
+
+```bash
+# Install in development mode
+pip install -e .
+
+# Install with dev dependencies (pytest)
+pip install -e ".[dev]"
+
+# Run all tests
+python -m pytest tests/ -v
+
+# Run a single test
+python -m pytest tests/test_perf_output.py::TestParseText::test_basic_values -v
+
+# Run CLI
+perfmon-skills lookup "cache miss" --platform SPR
+perfmon-skills cmdgen --tma-level 1 --platform SPR
+perfmon-skills compare ICX SPR --type metrics
+perfmon-skills recommend start --platform SPR --cmd "sleep 1"
+
+# Enable decision tracing
+PERFMON_TRACE=1 perfmon-skills recommend start --platform SPR
+```
+
+## Architecture
+
+Two-layer design:
+1. **Deterministic layer** (Python, no LLM): parses perf output, evaluates TMA threshold formulas, selects drill-down path, generates perf commands, tracks context budget
+2. **LLM layer** (Claude Code skills in `skills/`): interprets findings conversationally, adds tuning advice — never sees raw perf data
+
+### Core Library (`src/perfmon_tools/core/`)
+
+- `platform.py` — CPU detection (`/proc/cpuinfo`), mapfile.csv parsing, platform resolution. Handles hybrid platforms (ADL/RPL) with separate P-core/E-core event files. Uses `PERFMON_DATA` env var or `./perfmon/` symlink.
+- `catalog.py` — Loads event/metric JSON from perfmon data. `PlatformCatalog` provides search indexes and coverage stats. SPR: ~2693 events, ~308 metrics.
+- `tma_tree.py` — Builds parent→child TMA hierarchy from `ParentCategory` field. 4 L1 roots, up to L6 depth on SPR (114 nodes).
+- `formula.py` — Expands metric formula aliases (a,b,c → event names) and evaluates via restricted `eval()`. Also evaluates threshold formulas for bottleneck detection.
+- `perf_output.py` — Parses perf stat text/JSON/interval formats. `PERF_TO_PERFMON` dict translates perf's `topdown-*` names to perfmon's `PERF_METRICS.*` names. `_normalize_event_values()` strips `cpu/` wrappers.
+- `context_budget.py` — Tracks token usage per step (~200 tokens/step compact finding vs. raw data on disk). Prevents attention loss in multi-step workflows.
+- `tracer.py` — Decision tracing (`PERFMON_TRACE=1`). Records a DAG of decisions with inputs/alternatives/confidence. Renders to JSON/Mermaid/DOT/HTML. Zero overhead when disabled.
+
+### Tool Modules
+
+- `lookup/search.py` — Cross-field event/metric search with platform, type, category, level filters
+- `cmdgen/generate.py` — Generates `perf stat` commands with counter budget awareness. Knows platform-specific counter counts (SPR: 8 GP + 4 fixed).
+- `compare/diff.py` — Cross-platform event/metric comparison with formula diffs
+- `recommend/` — Stateful TMA drill-down engine:
+  - `engine.py` — State machine orchestrator (IDLE→COLLECTING→ANALYZED→COMPLETE)
+  - `tma_drilldown.py` — Node evaluation, threshold checking, next-step suggestion
+  - `preflight.py` — SMT detection, steady-state detection, counter budget
+  - `session.py` — File-based session persistence (`sessions/` directory)
+  - `coverage.py` — Event coverage tracking, domain-affinity gap suggestions
+  - `guidance.py` — Tuning advice keyed by TMA leaf node
+
+### Key Data Flow (Recommendation Engine)
+
+1. `start()` → detect platform, run preflight, generate L1 perf command
+2. User runs perf, feeds output → `analyze()`:
+   - `parse_auto()` normalizes event names (perf→perfmon mapping)
+   - `evaluate_level()` computes metric values from event counters
+   - `_evaluate_threshold()` checks bottleneck thresholds (arithmetic)
+   - `suggest_next()` picks highest-value threshold-passing node → children events
+   - Compact finding saved; next perf command generated
+3. Iterate until leaf node → guidance + coverage report
+
+### Event Name Translation
+
+perf outputs names like `topdown-fe-bound`, `cpu/INST_RETIRED.ANY/`. Perfmon JSON uses `PERF_METRICS.FRONTEND_BOUND`, `INST_RETIRED.ANY`. The `_normalize_event_values()` function in `perf_output.py` handles this bidirectionally.
+
+## Key Design Constraints
+
+- Zero mandatory dependencies (stdlib only). Optional: `rich` for pretty output, `pytest` for dev.
+- perfmon data accessed via symlink `./perfmon/` or `PERFMON_DATA` env var pointing to the Intel perfmon repo root.
+- Session state is plain JSON files in `sessions/` (gitignored). No database.
+- Context budget: raw perf output stays on disk, only ~200-token compact findings flow between steps.
+- Counter budget: knows each platform's GP/fixed counter count to minimize multiplexing.