/sap-gui-inspect

name: sap-gui-inspect
description: |
  Inspects the currently active SAP GUI session — structurally and/or visually —
  so a stuck GUI script (unexpected popup, a control ID that moved between
  releases, a greyed-out field, a hung transition) can be understood. Two mode
  families: STRUCTURAL dumps component IDs + properties — `tree` (component tree
  of all/one window), `menu` (menu bar), `type` (every component of a type, e.g.
  GuiButton/GuiShell), `id` (full property dump of one findById path), `wnd` (one
  window); VISUAL `screenshot` HardCopies every window into one annotated PNG
  (sub-modes topmost | composite | full, where full also dumps the topmost
  window's tree). The orchestrator reads the PNG with the Read tool. Other skills
  call this mid-flow to discover the current screen state. Replaces the former
  /sap-gui-object-details and /sap-gui-diagnose.
  Prerequisites: active SAP GUI session (/sap-login first); RZ11
  sapgui/user_scripting = TRUE on the server.
argument-hint: "<mode> [filter] [wnd=<n>]   modes: tree | menu | type | id | wnd | screenshot [topmost|composite|full] [--with-details]"

SAP GUI Inspect Skill

You inspect the currently active SAP GUI screen. Two families of modes:

• **Structural** (`tree` / `menu` / `type` / `id` / `wnd`) — dump the component

tree, menu bar, all components of a chosen type, or the full property set of a single component identified by its `findById` path.

• **Visual** (`screenshot`) — capture every visible window as a screenshot,

compose them into one annotated PNG, and hand it to the orchestrator (which reads the PNG with the Read tool). Use this when the structural dump alone isn't enough to see what's on screen.

Task: $ARGUMENTS

---

Shared Resources

| File | Token | Purpose | |---|---|---| | `<SAP_DEV_CORE_SHARED_DIR>/rules/skill_operating_rules.md` | *(rule)* | Mandatory operating rules | | `<SAP_DEV_CORE_SHARED_DIR>/rules/language_independence_rules.md` | *(rule)* | GUI-scripting language independence — identify by component ID + DDIC field name, status-bar checks via `MessageType` codes (S/W/E/I/A), VKey instead of menu-text, no branching on `.Text`/`.Tooltip`/window titles | | `<SKILL_DIR>/references/sap_gui_object_details.vbs` | `%%MODE%%`, `%%FILTER%%`, `%%WINDOW%%`, `%%MAX_DEPTH%%`, `%%OUTPUT_FILE%%` | Structural inspection: component tree / menu / type dump / property dump | | `<SKILL_DIR>/references/sap_gui_diagnose_capture.vbs` | `%%OUTPUT_DIR%%`, `%%MANIFEST%%` | Visual inspection: HardCopy each window's BMP + emit TSV manifest | | `<SKILL_DIR>/references/sap_gui_diagnose_compose.ps1` | `%%MANIFEST%%`, `%%COMPOSITE_PNG%%`, `%%TOPMOST_PNG%%` | Visual inspection: stack BMPs in screen-space order → composite PNG + topmost PNG | | `<SAP_DEV_CORE_SHARED_DIR>/scripts/sap_gui_security_sidecar.ps1` | *(launched)* | OS-level (Win32) auto-dismiss for the "SAP GUI Security" dialog. Launched in parallel with the `screenshot` capture: `HardCopy` writes BMPs through SAP GUI (SAP-GUI-side file IO) and would otherwise hang `cscript` on the modal when the output dir isn't trusted. |

---

When to Invoke (auto-trigger contract)

Other skills SHOULD invoke `/sap-gui-inspect` as the **first resort** — before falling back to manual scripting-recorder probes — when their VBS hits any of:

1. **Hard crash** — `findById` raises `The control could not be found by id`. 2. **Stuck progression** — the script has been waiting on a screen transition for noticeably longer than expected (>5s). 3. **Unexpected popup** — `oSession.ActiveWindow.Id` is `wnd[N]` for N >= 1 and the dispatcher doesn't recognise the popup's component markers. 4. **Failed post-condition** — sbar `MessageType = "E"` or a known verifier (e.g. SE11's RFC verifier) reports `MISSING` / `INACTIVE` when the GUI claimed success.

The dispatch is **visual first** (`/sap-gui-inspect screenshot full`) → **structural** (`/sap-gui-inspect tree` or `wnd <N>`) → recorded fallback (`/sap-gui-probe --record`). `screenshot full` does both in one call (composite PNG + a structural dump of the topmost window), so it is the recommended first move for a stuck flow.

---

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))"

The settings note below still applies to the OTHER keys.

**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`. Resolve sap-dev-core paths: 2 levels up from `<SKILL_DIR>` to the plugin root, then `settings.json` and (if present) `settings.local.json`. | Setting | Default if blank | |---|---| | `work_dir` | `C:\sap_dev_work` |

Set `{WORK_TEMP}` = `{work_dir}\temp`. Ensure it exists:

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

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` and the `_run.json` state) under `{RUN_TEMP}`; keep `{WORK_TEMP}` (base) only for `Get-SapCurrentSessionPath -WorkTemp`.

For the `screenshot` mode, also generate a per-run output directory using a sortable timestamp:

{DIAG_DIR} = {WORK_TEMP}\sap_inspect_<YYYYMMDD_HHMMSS>

Keep `{DIAG_DIR}` so you can r