/sap-cc-usage

name: sap-cc-usage
description: |
  Overlays runtime usage data onto the campaign inventory to decide what to
  remediate vs. retire — the step that produces the headline "X% retired without
  remediation" number. Joins a usage export onto inventory.tsv, applies the
  decommission policy, writes usage.tsv + scope.tsv (REMEDIATE / DECOMMISSION /
  REVIEW). Usage sources: FILE (hand-supplied export), SCMON/UPL (RFC read of the
  ABAP Call Monitor / SUSG), WORKLOAD (coarse ST03N fallback, positive-only,
  low-confidence), NONE. FILE/NONE are offline; the others open an RFC connection.
  SAFETY: no monitoring data → NO_DATA → every object defaults to REMEDIATE (never
  "everything unused"); a join-rate guard rejects a wrong-system export;
  conservative parks unused as REVIEW pending the /sap-where-used-list check,
  aggressive flags DECOMMISSION without it (use with care). Run after
  /sap-cc-inventory, before /sap-cc-analyze.
  Prerequisites: FILE/NONE offline; SCMON/UPL/WORKLOAD need SAP NCo 3.1 (32-bit)
  + a saved source_profile.
argument-hint: "--campaign <id> [--usage-source FILE|SCMON|UPL|WORKLOAD|NONE] [--usage-file <path>] [--source-profile <ref>] [--namespaces Z,Y] [--policy none|conservative|aggressive] [--min-exec 0] [--force-low-join] [--workload-months 12]"

SAP Custom-Code Migration — Usage & Decommission Scoping

You decide, for every inventoried custom object, whether it should be **remediated**, **retired (decommissioned)**, or **reviewed** — by overlaying how often it actually runs. Retiring dead code is usually the single biggest scope reduction in a conversion, so this step's savings number matters.

Task: $ARGUMENTS

---

Shared Resources

| File | Token | Purpose | |---|---|---| | `<SAP_DEV_CORE_SHARED_DIR>/rules/skill_operating_rules.md` | *(rule)* | Mandatory operating rules. | | `<SAP_DEV_CORE_SHARED_DIR>/rules/settings_lookup.md` | *(rule)* | Settings / `work_dir` resolution. | | `<SAP_DEV_CORE_SHARED_DIR>/scripts/sap_settings_lib.ps1` + `sap_connection_lib.ps1` | *(dot-source)* | `Get-SapWorkDir`. | | `<SAP_DEV_CORE_SHARED_DIR>/scripts/sap_log_helper.ps1` | *(invoke)* | Start/step/end JSONL logging. | | `<SKILL_DIR>/references/sap_cc_usage.ps1` | *(invoke)* | Joins usage onto inventory, applies the policy, writes `usage.tsv` + `scope.tsv`, advances `state.tsv`. Emits parseable `USAGE:` / `DECISION:` / `METRIC:` / `STATUS:` lines. Offline (files only). | | `<SKILL_DIR>/references/sap_cc_scmon_read.ps1` | *(invoke, RFC)* | **Direct SCMON/UPL reader** (SCMON/UPL source only). Reads the source system's `SUSG_V_DATA` (aggregated) / `SCMON_VDATA` (raw) + `SUSG_ADMIN` (window) via RFC and writes a usage export TSV. Emits `SCMON:` / `WINDOW_WARN:` / `EXPORT:` / `STATUS: OK\|NO_DATA\|ERROR`. | | `<SKILL_DIR>/references/sap_cc_workload_read.ps1` | *(invoke, RFC)* | **Workload fallback reader** (WORKLOAD source only) for systems without SCMON. Reads the ST03N workload monitor via `SWNC_GET_WORKLOAD_STATISTIC` (TCDET per-entry counts) over the last N months, resolves Z/Y tcodes to programs via `TSTC`, and writes the same usage export TSV. **Positive-only, LOW-confidence.** Emits `WORKLOAD:` / `WINDOW_WARN:` / `EXPORT:` / `STATUS: OK\|NO_DATA\|ERROR`. | | `<SAP_DEV_CORE_SHARED_DIR>/scripts/sap_rfc_lib.ps1` + `sap_dpapi.ps1` | *(used by the reader)* | NCo 3.1 connect + source-profile password decrypt (SCMON/UPL path only). | | `/sap-where-used-list` | *(skill)* | Used in the **reference-safety check** (Step 4) to confirm a REVIEW candidate has no inbound callers among still-used objects before it is decommissioned. |

The workspace contract (`usage.tsv` / `scope.tsv` columns, the SCOPED / DECOMMISSIONED / REVIEW states, the upsert rule) is defined by `/sap-cc-campaign`. This skill **owns** `usage.tsv` and `scope.tsv`.

> The scoping helper (`sap_cc_usage.ps1`) and the FILE/NONE paths are offline — > no SAP GUI, broker, attach lib, or TR. Two parts touch SAP, both read-only: > the **SCMON/UPL reader** (RFC against the `source_profile`, Step 1.5) and the > optional reference-safety check (Step 4, via `/sap-where-used-list`).

---

Step 0 — Resolve Work Directory

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 `{WORK_TEMP}` = `{work_dir}\temp` (create if needed) and `{CAMPAIGN_DIR}` = `{work_dir}\migrations\{campaign-id}`.

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

Per the CLAUDE.md "Two-bucket temp model" write this skill's per-run scratch (the log state file below) under `{RUN_TEMP}`, never at a fixed name under the `{WORK_TEMP}` root.

---

Step 0.5 — Start Logging

State file: `{RUN_TEMP}\sap_cc_usage_run.json`. Best-effort.

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

---

Step 1 — Parse Arguments & Pre-flight

• `--campaign <id>` — **required.** Need both `{CAMPAIGN_DIR}\campaign.json` and

a populated `inventory.tsv`. If inventory is missing/empty, stop and tell the operator to run `/sap-cc-inventory` first.

• `--usage-file <path>` — the usage export (FILE source). Recommended format:

TSV/CSV, **col1 = object name**, **col2 = exec count**, optional **col3 = last used**; a header row is auto-detected. A single-column file (just names) is treated as "present = used".

• `--usage-source FILE|SCMON|UPL|WORKLOAD|NONE` — defaults to FILE when

`--usage-file` is given, else NONE.

• `FILE` — ingest the `--usage-file` export (offline).
• `SCMON` / `UPL` — **r