/sap-explain-object

name: sap-explain-object
description: |
  Read-only comprehension aid for an EXISTING ABAP object. Auto-detects the type
  (program / include / function module / class) via RFC, acquires the active
  source, resolves the include tree, and builds a structure + call/data map (units,
  PERFORM / CALL FUNCTION / CALL METHOD edges, DB read/write targets, SUBMIT / CALL
  TRANSACTION, selection screen); optionally pulls callers via /sap-where-used-list.
  Emits an explanation dossier + machine-readable map.json. Never modifies SAP.
  With --spec it enriches the map over RFC (DDIC table texts + keys, message texts,
  auth objects) and renders a formal, review-ready spec document — Markdown, Word
  (--format docx), or a filled spec_template.xlsx (--format xlsx) that round-trips
  through /sap-docs-extract; each section marked CONFIRMED vs INFERRED. --spec folds
  in the former /sap-document-object.
  Prerequisites: pinned /sap-login connection. Class download, --callers, and
  --format docx/xlsx need a GUI session / the anthropic-skills docx|xlsx.
argument-hint: "<OBJECT_NAME> [--type program|include|fm|class|auto] [--callers] [--no-gui] [--depth N] [--spec] [--format md|docx|xlsx] [--audience functional|technical]"

SAP Explain Object Skill

Produces a read-only "object dossier" for an existing ABAP object: what it does, its internal structure and call graph, the data it touches, its dependencies, and a change-impact note. Pure read — never deploys, activates, or edits.

With **`--spec`** the same comprehension base is upgraded into a **formal, review-ready specification document** (Markdown / Word / a filled `spec_template.xlsx`) — the inverse of `/sap-gen-abap`'s spec-to-code flow. That mode (Step 7.5) folds in the former `/sap-document-object` skill.

This skill observes `shared/rules/skill_operating_rules.md` (reads only — no SQL writes, no unsolicited deployment).

Shared Resources

| File / token | Path | Purpose | |---|---|---| | `sap_settings_lib.ps1` | `<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_settings_lib.ps1` | `Get-SapSettingValue`, settings merge | | `sap_connection_lib.ps1` | `<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_connection_lib.ps1` | `Get-SapWorkDir`, `Get-SapCurrentSessionPath` | | `sap_rfc_lib.ps1` | `<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_rfc_lib.ps1` | `Connect-SapRfc` (+ the `New-RfcReadTable` / `Add-RfcOption` / `Add-RfcField` primitives) | | `sap_object_resolver.ps1` | `<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_object_resolver.ps1` | `Read-SapTableRows` (validated RFC_READ_TABLE reader for the type probe; CLI body self-guarded on dot-source) | | `sap_rfc_read_source.ps1` | `<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_rfc_read_source.ps1` | `Read-SapAbapSource` (RPY source + include tree) | | `sap_explain_parse.ps1` | `<SKILL_DIR>\references\sap_explain_parse.ps1` | offline source -> `map.json` | | `sap_attach_lib.vbs` (`%%ATTACH_LIB_VBS%%`) | `<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_attach_lib.vbs` | `AttachSapSession` (GUI download / where-used) | | SE24 download VBS | `<SKILL_DIR>\..\sap-se24\references\sap_se24_check_and_download.vbs` | class source (GUI) | | where-used VBS | `<SKILL_DIR>\..\sap-where-used-list\references\sap_where_used_list.vbs` | callers (GUI) | | `sap_object_resolver.ps1` (again) | `<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_object_resolver.ps1` | `Read-SapTableRows` for the `--spec` DD02T/DD03L/T100 enrichment | | `spec_template.xlsx` | `<SAP_DEV_CORE_SHARED_DIR>\templates\spec_template.xlsx` | (`--spec --format xlsx`) the 17-sheet layout filled from the enriched map — round-trips into `/sap-docs-extract` | | `sap_log_helper.ps1` | `<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_log_helper.ps1` | structured logging |

**Skills orchestrated in `--spec` mode** (skills-first): `anthropic-skills:docx` (`--format docx`), `anthropic-skills:xlsx` (`--format xlsx`).

Step 0 — Resolve Work Directory

Resolve `work_dir` via the env-aware helper (do NOT read `settings.json` directly — that ignores `SAPDEV_AI_WORK_DIR` / `userconfig.json`):

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`.

| Setting | Default if blank | |---|---| | `work_dir` | `C:\sap_dev_work` |

Set `{WORK_TEMP}` = `{work_dir}\temp` and `{OUT}` = `{WORK_TEMP}\explain\{OBJECT}`. Ensure `{OUT}` exists:

cmd /c if not exist "{OUT}" mkdir "{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))"

Write this run's generated scratch (`explain_dl.vbs`) and the `_run.json` log state under `{RUN_TEMP}`; keep `{WORK_TEMP}` (base) for `{OUT}` and `Get-SapCurrentSessionPath -WorkTemp`.

Step 0.5 — Start Logging (best-effort)

powershell -NoProfile -ExecutionPolicy Bypass -File "<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_log_helper.ps1" -Action start -StateFile "{RUN_TEMP}\sap_explain_object_run.json" -Skill sap-explain-object -ParamsJson "{\"args\":\"{RAW_ARGS}\"}"

The `-StateFile` carries the `run_id` between this start and the Final end event — pass the same path to both; no `RUN_ID=` capture is needed.

Step 1 — Parse Arguments

• `{OBJECT}` = first positional, uppercased.
• `--type` -> `{TYPE}` (default `auto`).
• `--callers` -> `{CALLERS}` = true (default false; requires GUI session).
• `--no-gui` -> `{NOGUI}` = true (RFC-only; classes degrade to signature only).
• `--depth N` -> `{DEPTH}` (default 3).
• `--spec` -> `{SPEC}` = true (default false; activates the **spec-document mode**, Step 7.5).
• `--format` -> `{FORMAT}` (default `md`; `md` | `docx` | `xlsx`; only meaningful with `--spec`).
• `--audience` ->