/sap-trace

name: sap-trace
description: |
  Analyzes an already-recorded SAP performance trace and ranks the hotspots.
  Two sources: --import <file> reads a trace you exported yourself (fully
  offline, no SAP needed); --source st05|sat drives the GUI to display the
  latest recorded SQL trace (ST05, "Summarized SQL Statements") or runtime-
  analysis hit list (SAT) and exports it as a tab file. The analyzer
  normalizes either shape into a ranked hotspot list, flags anti-patterns
  (SELECT in loop, SELECT *, full-scan, unguarded FOR ALL ENTRIES, many
  executions, ABAP-side hotspots), maps each to a rule in
  abap_code_quality_rules.md and to the object's volume band, and proposes a
  fix. This v1 reads a trace that ALREADY EXISTS — it does not activate/
  deactivate ST05 or start a SAT measurement (capture orchestration is a later
  phase), and does not read SQL Monitor (SQLM).
  Pure read-only — never modifies the SAP system.
  Prerequisites: for --source, an active SAP GUI session (use /sap-login
  first); for --import, none.
argument-hint: "[--import <file>] [--source st05|sat] [--kind st05|sat|auto] [--user <u>] [--top N] [--threshold-ms N] [--perf-band small|medium|large] [--with-source] [--output <path>]"

SAP Performance / SQL-Trace Analysis Skill

You take a recorded SAP performance trace (ST05 SQL trace or SAT runtime analysis), rank the most expensive statements / units, map each to a known ABAP performance anti-pattern, and suggest a concrete fix calibrated to the object's volume band. The trace either already exists as an exported file (`--import`) or is displayed-and-exported from the live GUI (`--source`).

Task: $ARGUMENTS

---

Shared Resources

| File | Token | Purpose | |---|---|---| | `<SAP_DEV_CORE_SHARED_DIR>/rules/skill_operating_rules.md` | *(rule)* | Mandatory operating rules — read-only skill | | `<SAP_DEV_CORE_SHARED_DIR>/rules/language_independence_rules.md` | *(rule)* | GUI-scripting language independence — identify by component ID + DDIC field name, status-bar via `MessageType` codes (S/W/E/I/A), VKey over menu-text, no branching on `.Text`/`.Tooltip`/window titles | | `<SAP_DEV_CORE_SHARED_DIR>/rules/abap_code_quality_rules.md` | *(rule)* | Performance gates (§12) the analyzer maps findings back to | | `<SAP_DEV_CORE_SHARED_DIR>/templates/customer_brief.md` | *(template)* | Source of the object's volume band (small/medium/large) when `--perf-band` is not given | | `<SAP_DEV_CORE_SHARED_DIR>/tables/perf_antipattern_map.tsv` | *(table)* | Maps a detected trace signal → §12 rule → fix template | | `<SKILL_DIR>/references/sap_trace.ps1` | *(script)* | Offline analyzer: normalize → rank → map → render report | | `<SKILL_DIR>/references/sap_trace_st05.vbs` | many | GUI: display latest ST05 trace, switch to summarized view, export tab file | | `<SKILL_DIR>/references/sap_trace_sat.vbs` | many | GUI: open a SAT measurement, display hit list, export tab file | | `<SAP_DEV_CORE_SHARED_DIR>/scripts/sap_attach_lib.vbs` | `%%ATTACH_LIB_VBS%%` | Parallel-safe session attach (GUI path) | | `<SAP_DEV_CORE_SHARED_DIR>/scripts/sap_log_helper.ps1` | *(script)* | Structured run logging |

---

Step 0 — Resolve Work Directory

**Resolve `work_dir` via the env-aware helper** — do NOT take `work_dir` from a direct `settings.json` read (that ignores the `SAPDEV_AI_WORK_DIR` env var and `userconfig.json`). Use the `WORK_DIR=` value printed by:

powershell -NoProfile -ExecutionPolicy Bypass -Command ". '<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_settings_lib.ps1'; . '<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_connection_lib.ps1'; Write-Output ('WORK_DIR=' + (Get-SapWorkDir))"

**Settings reads/writes follow `shared/rules/settings_lookup.md`** — merge per-key on the `.value` field (env var → `settings.local.json` → `userconfig.json` → `settings.json`); non-per-connection writes go to `userconfig.json`. Read:

| Setting | Default if blank | |---|---| | `trace_threshold_ms` | `100` | | `trace_top_n` | `20` |

Set `{WORK_TEMP}` = `{work_dir}\temp` and `{TRACE_OUT}` = `{work_dir}\trace`. Ensure both exist:

cmd /c if not exist "{WORK_TEMP}" mkdir "{WORK_TEMP}"
cmd /c if not exist "{TRACE_OUT}" mkdir "{TRACE_OUT}"

Set `{RUN_TEMP}` = the per-run scratch dir (`Get-SapRunTemp` mints + creates `{work_dir}\temp\run_<id>`):

powershell -NoProfile -ExecutionPolicy Bypass -Command ". '<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_connection_lib.ps1'; Write-Output ('RUN_TEMP=' + (Get-SapRunTemp))"

Per the CLAUDE.md "Two-bucket temp model" write this skill's generated scratch (`*_run.ps1` / `*_run.vbs`) under `{RUN_TEMP}`; keep `{WORK_TEMP}` / `{TRACE_OUT}` (base) for outputs, log state, and `Get-SapCurrentSessionPath -WorkTemp`.

---

Step 0.5 — Start Logging

Start a structured log run. State file: `{RUN_TEMP}\sap_trace_run.json`. Best-effort.

powershell -ExecutionPolicy Bypass -File "<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_log_helper.ps1" -Action start -StateFile "{RUN_TEMP}\sap_trace_run.json" -Skill sap-trace -ParamsJson "{\"source\":\"<SOURCE>\"}"

---

Step 1 — Parse Arguments

| Flag | Meaning | Default | |---|---|---| | `--import <file>` | Analyze an already-exported trace file (offline; no SAP) | — | | `--source st05\|sat` | Drive the GUI to display + export the latest recorded trace | — | | `--kind st05\|sat\|auto` | Format of the `--import` file when auto-detection is ambiguous | `auto` | | `--user <u>` | ST05 display filter (whose trace to show) | pinned SAP user | | `--from <HH:MM> --to <HH:MM>` | ST05 display time window | last 10 min | | `--measurement <id>` | SAT: which saved measurement to open | latest | | `--top N` | Max hotspots reported | `trace_top_n` (20) | | `--threshold-ms N` | Surface statements whose total time ≥ N ms | `trace_threshold_ms` (100) | | `--perf-band small\|medium\|large` | Volume band override | from customer brief | | `--with-source` | Best-effort: annotate the offending program/include/line | off | | `--output <pa