/sap-docs-convert

name: sap-docs-convert
description: |
  Applies customer-specific normalisation rules to the extracted spec files
  in a work folder. Reads `spec_conversion_rules.tsv` (default at
  sap-dev-core/shared/tables/, override at {custom_url}/spec_conversion_rules.tsv)
  and rewrites the affected `_*.txt` files in place.

  Three rule categories:
    * field_rename  — legacy field name → canonical name
    * type_rename   — legacy DDIC type token → canonical token
    * flag_mapping  — legacy flag value → one or more KEY=VALUE pairs

  Plus optional schema migration (legacy customer YAML/TSV layout → Customer
  Brief layout).

  Input:  work folder containing the extracted `_*.txt` files (output of /sap-docs-extract).
  Output: same files rewritten in place; a `.pre-convert/` snapshot is taken first.
  This skill is OPTIONAL — projects already authoring specs in Customer Brief
  format can skip it entirely.
argument-hint: "<work-folder>  [rules-file-path]"

SAP Docs Convert Skill

You normalise an extracted spec by applying customer-specific rules. Runs between `/sap-docs-extract` and the validation / generation skills:

spec.xlsx ──[sap-docs-extract]──▶ raw _*.txt
                                     │
                                     ▼
                  ──[sap-docs-convert]── (optional, rules-driven)
                                     │
                ┌────────────────────┴─────────────────────┐
                ▼                                           ▼
       /sap-docs-check (ddic + process dimensions)    /sap-gen-abap

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/language_independence_rules.md` | GUI-scripting language independence — offline normaliser, but rule applies to downstream deploy skills the converted spec feeds | | `<SAP_DEV_CORE_SHARED_DIR>/rules/abap_code_quality_rules.md` | ABAP code-quality rules — type-rename and flag-mapping rules that convert legacy spec fields into Customer Brief layout must preserve ABAP-quality affordances (DTEL vs. primitive, currency reference) so the generated code stays clean |

---

Step 0 — Resolve Work Directory and Rules File

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

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

Locate the rules file (priority order — first hit wins):

1. The 2nd positional argument, if provided. 2. `{custom_url}\spec_conversion_rules.tsv` — customer override. 3. `<SAP_DEV_CORE_SHARED_DIR>\tables\spec_conversion_rules.tsv` — built-in default.

If no rules file is found, abort with: > "No spec_conversion_rules.tsv found. Either pass the path as the 2nd argument, drop one in {custom_url}, or use the default at sap-dev-core/shared/tables/."

Also set `{WORK_TEMP}` = `{work_dir}\temp` (base dir only) and `{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 Step 0.5 / Step 6 log state file. Mint it once here and reuse the same value below — do not call `Get-SapRunTemp` again in a later step.

---

Step 0.5 — Start Logging

Start a structured log run. Best-effort: silently no-ops if disabled or the lib can't load. `<SAP_DEV_CORE_SHARED_DIR>` resolves to `plugins/sap-dev-core/shared/`. State file: `{RUN_TEMP}\sap_docs_convert_run.json`.

powershell -ExecutionPolicy Bypass -File "<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_log_helper.ps1" -Action start -StateFile "{RUN_TEMP}\sap_docs_convert_run.json" -Skill sap-docs-convert -ParamsJson "{\"work_folder\":\"<WORK_FOLDER>\",\"rules_file\":\"<RULES_PATH>\"}"

---

Step 1 — Resolve Work Folder

Extract the work-folder argument. If missing, ask: > "Please provide the work folder path containing the extracted `_*.txt` files."

Verify the folder exists and contains at least one `*_raw.txt` file. Locate the single `*_raw.txt` to derive `{doc_name}` (strip `_raw.txt` suffix). If zero or multiple raw files exist, abort with a clear error.

---

Step 2 — Snapshot Pre-Convert State

Before any rewriting, copy the current `_*.txt` files to a snapshot folder so the operation is reversible:

$snap = Join-Path "{work_folder}" ".pre-convert"
if (-not (Test-Path $snap)) { New-Item -ItemType Directory -Path $snap | Out-Null }
Get-ChildItem -Path "{work_folder}" -Filter "*.txt" -File |
    ForEach-Object { Copy-Item $_.FullName -Destination $snap -Force }

If `.pre-convert` already exists from a prior run, leave it alone — keep the oldest snapshot so the user can always roll back to the original extract output.

---

Step 3 — Read the Rules File

The rules file is TSV with a header line. Required columns:

| Column | Meaning | |---|---| | `CATEGORY` | One of `field_rename`, `type_rename`, `flag_mapping`, `schema_migration` | | `FROM` | Source token (legacy value) | | `TO`