/sap-workflow

name: sap-workflow
description: |
  Diagnose, explain, and fix SAP Business Workflow runtime over RFC — the SWI1/SWIA/SWEL/SWU3
  expert path in one skill. diagnose finds stuck/errored workitems for an anchor (WI id /
  business object / task / user / status+date), decodes the SWWLOGHIST error (message class +
  number rendered via T100), flags agent-determination gaps (a READY dialog workitem with no
  actual agent), and reports event-queue + type-linkage + WF-BATCH health. explain builds a
  dossier for a WS/TS task or live WI (text, active definition version/status, triggering event
  linkages). act restart / cancel / forward a workitem through released SAP_WAPI_* write APIs
  behind a refusal matrix (restart only from ERROR; cancel refused if already
  COMPLETED/CANCELLED; forward needs --to + a dialog item) and a confirm gate, verified by an
  authoritative SWWWIHEAD.WI_STAT re-read (a WAPI success code with an unchanged status is
  WF_ACT_FAILED, never a false success). Pure RFC (all FMs FMODE=R on ECC6 + S/4, single code
  path); no GUI, no wrapper FM, no Z object, no dev-init. RFC unavailable fails LOUD (BLOCKED ->
  /sap-doctor), never a silent GUI degrade. Registers as /sap-diagnose's workflow reader.
  Prerequisites: pinned /sap-login RFC profile; NCo 3.1 (32-bit).
argument-hint: "diagnose [--status error|all] [--task TS/WS..] [--user U] [--since YYYYMMDD] [--wi ID] | explain <WS/TS/WI> | act <restart|cancel|forward> <WI> [--to USER]"

SAP Workflow Runtime Skill

You answer "why is this approval / workflow stuck?" and, on request, fix it — all over RFC. `diagnose` and `explain` run unprompted (read-only); every `act` verb is confirm-gated and verified by an authoritative status re-read. You never write a table and never guess a status.

Task: $ARGUMENTS

---

Shared Resources

| File | Token / call | Purpose | |---|---|---| | `<SAP_DEV_CORE_SHARED_DIR>/rules/safety_policy.md` | *(rule)* | **Rule 0 (highest priority)** — environment guard; enforced at the top of Step 5 via `sap_safety_gate.ps1` (`act` only — `diagnose`/`explain` are read-only and skip it) | | `<SKILL_DIR>/references/sap_workflow_rfc.ps1` | `-Mode diagnose\|explain\|act` | The whole backend (all three modes) | | `<SAP_DEV_CORE_SHARED_DIR>/scripts/sap_rfc_lib.ps1` · `sap_connection_lib.ps1` | dot-source | RFC connect + pinned profile | | `<SAP_DEV_CORE_SHARED_DIR>/scripts/sap_finding_lib.ps1` · `sap_artifact_lib.ps1` | dot-source | Finding/coverage model + evidence registration | | `/sap-explain-object` · `/sap-st22` · `/sap-diagnose` | sub-skills | Z-object chain / dump drill / evidence reader (`workflow` row) |

---

Step 0 — Directories + Logging

Resolve `work_dir` + `{RUN_TEMP}` (canonical one-liner — `sap_connection_lib.ps1` is dot-sourced there — with `Write-Output ('RUN_TEMP=' + (Get-SapRunTemp))` appended). `{RUN_TEMP}` = the per-run scratch dir holding the log state file; mint it once here and reuse (re-minting breaks the `-Action end` state-file lookup). Start logging (`sap_log_helper.ps1`, state `{RUN_TEMP}\sap_workflow_run.json`). Pure RFC — no GUI, no session attach, no baseline.

Step 1 — Parse & Dispatch

First token = `diagnose` (default) | `explain` | `act`. `act` requires a verb (`restart|cancel|forward`) + WI id. `diagnose` takes `--wi/--task/--user/--object/--status/ --since/--top` (default `--status error --since <today-30d> --top 20`, hard cap 200). Pinned profile via `/sap-login` (or `--connection <hint>` -> backend `-Profile`).

Step 2 — Connect

Backend connects the pinned RFC profile. RFC unavailable -> `STATUS: BLOCKED` -> tell the user to run `/sap-doctor`; do NOT degrade to GUI (v1 is RFC-only by design).

Step 3 — diagnose

... sap_workflow_rfc.ps1 -Mode diagnose [-Status error|all] [-Task ..] [-User ..] [-WiId ..] [-Since YYYYMMDD] -Top 20 -OutDir "{RUN_TEMP}\wf"

Emits `WFSEL:` (match count), one `WF:` per workitem (`wi/type/stat/task/top/agent/flag/err/text` — `err` is the decoded SWWLOGHIST message, `flag=AGENT_DETERMINATION` when a READY dialog WI has no agent), `WFENV:` health rows (event-queue backlog, inactive type linkages, WF-BATCH lock state, SWU3 = COULD_NOT_CHECK), then `STATUS: OK matched=.. errors=.. agent_gaps=..`. Map each error/agent-gap to `New-SapFinding` (severity per signal, tri-state coverage — SWU3/absent reads are COULD_NOT_CHECK, never "passed"); `Get-SapVerdict`; render a table + next-action hints (`/sap-workflow act restart <wi>`, manual SWU3, `/sap-st22` when SWWLOGHIST shows a runtime abort). Zero matches -> say so explicitly (never an empty-file false success).

Step 4 — explain

... sap_workflow_rfc.ps1 -Mode explain -Task <WS/TS..>   (or -WiId <id>)

`WFEXPL:` lines give task short/text, active definition version+status (WS only; COULD_NOT_CHECK if no active SWDSHEADER row), and triggering event linkages (`WFEVENT:` objtype/event/active). Render a dossier MD; when the task calls a Z class/FM, offer to chain `/sap-explain-object`.

Step 5 — act (confirm-gated)

**Rule 0 first** (`safety_policy.md`; `act` only — `diagnose`/`explain` are read-only and skip it): `powershell -NoProfile -ExecutionPolicy Bypass -File "<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_safety_gate.ps1" -Action assert -Skill sap-workflow` — `SAFETY: ALLOW` (0) proceed; `TYPED_CONFIRM_REQUIRED` (3) -> the operator types the shown `PROD <SID>/<CLIENT>` token, re-run with `-ConfirmationText '<their verbatim answer>'`, proceed only on `ALLOW_CONFIRMED`; `REFUSED class=<C>` (1) / `ERROR` (2) -> **STOP**, end `FAILED` with `-ErrorClass <C>`, relay the remediation lines — never bypass or work around it manually. The CONFIRM gate below (item 2) still applies after ALLOW/ALLOW_CONFIRMED.

1. Backend pre-reads the WI and applies the **refusal matrix** BEFORE any prompt: restart needs `WI_STAT=ERROR`; cancel refused on COMPLETED/CANCELLED; forward needs `--to` + a dialog (W) item. A refusal -> `WFACT: REFUSED` + `WF_ACT_INVALID_STATE`; sto