/sap-docs-extract

name: sap-docs-extract
description: |
  Reads a SAP design document (Excel .xlsx, Word .docx, PDF) — or an existing work
  folder / a _raw.txt file — and extracts structured information into separate text
  files by type: program summary, domains, data elements, tables, error messages,
  text elements, and process logic. From a document it creates a fresh work folder,
  dumps {doc_name}_raw.txt, then structures; existing {doc_name}_*.txt files are
  silently overwritten. Optionally chain /sap-docs-convert afterwards for
  customer-specific normalisation, then /sap-docs-check and /sap-gen-abap. Legacy
  binary .doc is not supported (save as .docx first); an unsupported format aborts
  with "ERROR: Unsupported file format."
argument-hint: "<path-to-document  OR  work-folder  OR  _raw.txt>"

SAP Docs Extract Skill

You read a SAP design document (Excel / Word / PDF) and extract structured information into separate files by information type. The previous two-step flow (`sap-docs-convert` → `sap-docs-extract`) is now folded into this single skill: if the input is a raw document, extract handles the format conversion itself before structuring.

Task: $ARGUMENTS

---

Shared Resources

| File | Purpose | |---|---| | `<SAP_DEV_CORE_SHARED_DIR>/rules/skill_operating_rules.md` | Mandatory operating rules | | `<SAP_DEV_CORE_SHARED_DIR>/rules/ddic_excel_layout_rules.md` | DDIC Excel-spec authoring rules — naming-suffix consistency, primitive-type-as-DTEL trap, currency reference, column order, no merged data cells. Detect spec-side defects at extract time. | | `<SAP_DEV_CORE_SHARED_DIR>/rules/language_independence_rules.md` | GUI-scripting language independence — offline extractor, but rule applies to downstream deploy skills the spec feeds |

---

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)); Write-Output ('RUN_TEMP=' + (Get-SapRunTemp))"

The settings note below still applies to the OTHER keys.

**Settings reads/writes follow `<SAP_DEV_CORE_SHARED_DIR>/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 cross-plugin paths: 3 levels up from `<SKILL_DIR>`, then into `sap-dev-core\settings.json` and (if present) `sap-dev-core\settings.local.json`. Read `custom_url`, `design_docs_url`, `source_code_url`.

| Setting | Default if blank | |---|---| | `work_dir` | `C:\sap_dev_work` | | `custom_url` | `{work_dir}\custom` | | `design_docs_url` | `{work_dir}\design_docs` | | `source_code_url` | `{work_dir}\source_code` |

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

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

Set `{RUN_TEMP}` = the `RUN_TEMP=` value printed above (`Get-SapRunTemp` mints + creates a fresh per-run dir `{work_dir}\temp\run_<id>`) — the per-run scratch dir holding the log state file. Mint it once here and reuse the same value in Step 0.5 and Final — do not call `Get-SapRunTemp` again later (each call mints a NEW dir, and the `-Action end` state-file lookup would miss).

---

Step 0.5 — Start Logging

Start a structured log run. The shared helper persists `run_id` to a state file so subsequent steps and Step 4 can append to the same run. Logging is best-effort — if `userConfig.log_enabled=false` or the lib can't load, the helper silently no-ops.

`<SAP_DEV_CORE_SHARED_DIR>` resolves to `plugins/sap-dev-core/shared/`.

State file: `{RUN_TEMP}\sap_docs_extract_run.json`

powershell -ExecutionPolicy Bypass -File "<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_log_helper.ps1" -Action start -StateFile "{RUN_TEMP}\sap_docs_extract_run.json" -Skill sap-docs-extract -ParamsJson "{\"input\":\"<USER_INPUT_PATH>\"}"

---

Step 1 — Resolve Input and Locate / Create the Raw Text File

Extract the path argument from `$ARGUMENTS`.

If no path is given, ask the user: > "Please provide the path to the design document (.xlsx / .docx / .pdf), an existing work folder, or a `_raw.txt` file."

Classify the argument using this decision table (evaluate rules in order; the first matching rule wins):

| # | Condition | Action | Section | |---|---|---|---| | 1 | Argument is a file ending in `_raw.txt` | Use it directly | 1a | | 2 | Argument is an existing directory | Locate the single `_raw.txt` inside | 1b | | 3 | Argument is a file with extension `.xlsx`, `.docx`, or `.pdf` | Create work folder and dump to `_raw.txt` | 1c | | 4 | Argument is a file with extension `.doc` (legacy binary Word — no working extraction path) | Abort with: `ERROR: .doc (legacy binary Word) is not supported. Open the file in Word, save it as .docx, then re-run /sap-docs-extract.` | — | | 5 | None of the above | Abort with: `ERROR: Unsupported file format.` | — |

1a. Raw text file (`*_raw.txt`)

If the argument ends with `_raw.txt` and exists as a file → use it directly. Set `{work_folder}` = the parent directory of that file. Set `{doc_name}` = filename minus `_raw.txt` suffix.

1b. Existing work folder

If the argument is a directory, locate the single `*_raw.txt` file inside it:

Get-ChildItem -Path "{work_folder}" -Filter "*_raw.txt"

If zero or multiple `_raw.txt` files exist, abort with the error message: "ERROR: Expected exactly one `_raw.txt` file in the directory."

1c. Design document (.xlsx / .docx / .pdf) — produces the raw file

If the argument is a document file with one of those extensions, create a fresh work folder and dump the document to plain text first:

1. Der