/sap-doc-flow

name: sap-doc-flow
description: |
  Reconstructs the O2C document chain from a bare business-document number and finds
  where it stalled — read-only over RFC (no VA03/VL03N/VF03/FB03 hopping). Walks VBFA in
  both directions from an order/delivery/invoice, decodes every node's status
  release-aware (S/4 in-table VBAK/LIKP/VBRK vs ECC VBUK), follows the invoice into FI via
  BKPF/AWKEY, and writes a flow map + "where it stalled" narrative. Auto-detects the
  document category. Doubles as a /sap-diagnose evidence source (the business-document
  dimension incident triage otherwise lacks). Prerequisites: pinned profile via /sap-login
  (RFC); SAP NCo 3.1 (32-bit). No GUI, no Z-object, no dev-init — safe to point at
  production, same posture as /sap-diagnose.
argument-hint: "<DOCNO>  |  order|delivery|invoice <DOCNO>  [--max-nodes N] [--no-narrative] [--evidence-dir <RUN_DIR>] [--connection PROFILE]"

SAP Document Flow — O2C Chain & Stall Finder

A support ticket arrives as a bare number ("invoice 90001234 is wrong"). You reconstruct the whole order→delivery→goods-issue→invoice→accounting chain and name where it stalled — seconds instead of minutes of VA03/VL03N/VF03/FB03 hopping. Read-only.

Task: $ARGUMENTS

**Pure read-only** (RFC_READ_TABLE only) — no writes, no report execution, no GUI. No confirm gates. Safe to point at production.

---

Shared Resources

| File | Token / call | Purpose | |---|---|---| | `<SAP_DEV_CORE_SHARED_DIR>/rules/skill_operating_rules.md` | *(rule)* | Mandatory operating rules — read-only here | | `<SKILL_DIR>/references/sap_doc_flow_read.ps1` | `-Category -DocNo [-MaxNodes -NoNarrative -EvidenceDir] -OutDir` | VBFA walker + release-aware decode + BKPF hop | | `<SKILL_DIR>/references/doc_flow_vbtyp_map.tsv` | map | VBTYP → node category/label | | `<SKILL_DIR>/references/doc_flow_status_map.tsv` | map | (category, field, value) → health/label | | `<SAP_DEV_CORE_SHARED_DIR>/scripts/sap_artifact_lib.ps1` | Step 5 | Artifact index for /sap-evidence-pack | | `/sap-diagnose` (evidence consumer) | `--object VBELN:… --reader docflow` | This skill is diagnose's `docflow` reader |

---

Step 0 — Resolve Work Directory & OUT

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

Set `{RUN_TEMP}` via `Get-SapRunTemp`. `{OUT}` = `Get-SapArtifactDir -ScopeKey DOC_<CATEGORY>_<KEY> -Skill sap-doc-flow`.

Step 0.5 — Start Logging

powershell -ExecutionPolicy Bypass -File "<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_log_helper.ps1" -Action start -StateFile "{RUN_TEMP}\sap_doc_flow_run.json" -Skill sap-doc-flow -ParamsJson "{}"

---

Step 1 — Parse Arguments

Bare `<DOCNO>` → `auto`. Explicit `order|delivery|invoice <DOCNO>`. Flags: `--max-nodes N` (default 200), `--no-narrative`, `--evidence-dir <RUN_DIR>` (reader mode for /sap-diagnose), `--connection PROFILE` (else pinned). `accounting <BELNR> --company <BUKRS>` and `po <EBELN>` are **v1.5 / v2 (not implemented)** → say NOT_YET_IMPLEMENTED and STOP. All modes read-only — no confirm-gate step.

Step 2 — Walk & Decode (RFC)

C:\Windows\SysWOW64\WindowsPowerShell\v1.0\powershell.exe -ExecutionPolicy Bypass -File "<SKILL_DIR>\references\sap_doc_flow_read.ps1" -Category <auto|order|delivery|invoice> -DocNo "<DOCNO>" -MaxNodes 200 -SharedDir "<SAP_DEV_CORE_SHARED_DIR>" -OutDir "{OUT}"

Add `-EvidenceDir "{RUN_DIR}"` and `-NoNarrative` in diagnose-reader mode. The engine detects the release schema (DD03L VBAK-GBSTK probe → `SCHEMA: S4|ECC`), ALPHA-pads the key, auto-detects the category, walks VBFA both directions (visited-set, depth 8, `--max-nodes`), decodes each node's status release-aware, and follows the invoice into FI. Parse:

SCHEMA: <S4|ECC>
NODE: cat=.. key=.. status=.. health=<OK|OPEN|IN_PROCESS|BLOCKED|CANCELLED|NOT_POSTED|COULD_NOT_CHECK> date=.. detail=".."
EDGE: from=.. to=.. vbtyp=..->..
STALL: node=.. reason=".."
STATUS: OK|DOCFLOW_NOT_FOUND|DOCFLOW_AMBIGUOUS_KEY|RFC_ERROR nodes=.. truncated=<bool> schema=..

• `DOCFLOW_NOT_FOUND` (exit 1) → the key is in no SD header; log FAILED, STOP.
• `DOCFLOW_AMBIGUOUS_KEY` (exit 1, only in `--evidence-dir` mode) → the same number exists

as >1 category; **interactively** (non-reader mode) ask the user which category and re-run with it. In reader mode the engine emits skipped-with-reason and stops.

• `truncated=true` → the node cap was hit; surface it **loudly** in map + narrative.
• A node whose header could not be read is `health=COULD_NOT_CHECK` — never rendered

healthy.

Step 3 — Render Flow Map + "Where It Stalled" (you write this)

Unless `--no-narrative`, write `docflow_report.md` into `{OUT}` from `docflow_nodes.tsv` + `docflow_edges.tsv`. **Grounding rule: every node/status traces to a TSV row.** 1. **Flow map** — indented tree / mermaid, each node with a `[health]` badge and its decoded status ("order 4969 — completely processed [OK]"). 2. **Where it stalled** — the first unhealthy or missing-expected-successor node along order→delivery→goods-issue→invoice→accounting, citing the decoded status ("invoice 90005177 posted (RFBSK=C) but no FI document — not posted to accounting"). State `truncated`/`COULD_NOT_CHECK` caveats explicitly. 3. **Release note** — `schema=S4` reads status in-table (VBAK/LIKP/VBRK); `schema=ECC` from VBUK — noted so the reader knows the source.

Step 4 — Register & Log End

Register `docflow_nodes.tsv`/`docflow_edges.tsv` (kind `docflow_map`), `docflow_report.md` (kind `docflow_report`), and `evidence_docflow.json` (kind `docflow_evidence`, when `--evidence-dir`) via `Register-SapArtifact` under scope `DOC_<CATEGORY>_<KEY>`. Emit one finding per stalled/blocked node (`New-SapFinding`; MEDIUM for BLOCKED/NOT_POSTED, LOW for OPEN; Coverage `COULD_NOT_CHECK` where a status table was unreadable