--- description: Walk a Gainsight asset through the workspace's deprecation checklist — rename, description prefix, folder move, unschedule — applying what the CLI supports and listing the manual UI steps. disable-model-invocation: true argument-hint: " [--domain rules|data-designer|reports] [--ticket REF] [--slug name]" --- # /gs-superadmin:deprecate Deprecate an asset per this workspace's deprecation process (default source: `.gs-superadmin/conventions/deprecation.md`; fall back to any deprecation guidance in `.gs-superadmin/CONVENTIONS.md`). If neither defines a process, tell the user and stop — never invent a deprecation convention. ## Arguments - `` — the asset to deprecate (required) - `--domain ` — `rules` (default), `data-designer`, or `reports` - `--ticket REF` — ticket reference for the description prefix (e.g. `GAIN-1247`); if omitted, ask the user (the process requires one) - `--slug ` — override the derived slug --- ## Steps ### 1 — Identify instance and load the process Same slug resolution as `/gs-superadmin:refresh` step 1 (`gs-admin whoami` + `*/_manifest.json`). Load the deprecation process file and extract: the rename prefix format (e.g. `D.MM.DD.YYYY `), the description prefix format (e.g. `Deactivated [ticket]`), and the target folder name per domain. ### 2 — Resolve the asset Resolve name → id from the KB manifest first. **Never trust a single page** — list endpoints are paginated (`re r list` defaults to 20 rows, `rp list` to 25), so on a full-size tenant a one-page dump silently misses almost every asset; every live list below runs through the capture helper's paginate mode, which owns the page loop and the short-page/total reconciliation (canon: setup Phase 4 "List exhaustively"). Asset names carry `|`, `&`, and other shell metacharacters: single-quote them in every shell command, and match them as literal strings (fixed-string mode), never as regex patterns. Given an **id** instead of a name, skip the name matching entirely: confirm it directly with the domain describe (rules: `re r describe --id `) — the manifest keys are `/` if you want the KB entry too. 1. **KB manifest (primary).** Grep `/_manifest.json` `inventory{}` for the name — keys are `/` and each entry carries `name`. The manifest is pretty-printed, so a bare grep for the name returns only the `"name": …` line, which contains no id — grep with context: `grep -F -B2 '' /_manifest.json` (the `"/":` key line sits exactly 2 lines above `"name"`; run greps with the Bash tool — `grep` is not a PowerShell command). The key's prefix is whatever domain name the workspace recorded for that asset's list command — `rules-engine/` for `--domain rules` and `report/` for `reports` under setup's naming rule, but older workspaces carry other spellings (`report-reports/`); the name grep finds the key whatever the prefix, and `report`'s `byDomain` lists the names in use (F-429). 2. **Live search (fallback if not in the KB — e.g. the asset postdates the last refresh).** - Rules: `node .gs-superadmin/plugin/scripts/capture.mjs --paginate --page-flag page --out .gs-superadmin/tmp/deprecate-list-{page}.json -- gs-admin --json re r list --search '' --limit 200` (`--search` is a server-side partial name match; the paginate mode exhausts the pages, so a name with more matches than one page holds is never truncated — `{page}` is literal, the script substitutes it, one file per page; read every page file). The capture helper writes the files as clean UTF-8 with no BOM on any shell — never capture with a bare shell redirect (rule canon: setup Phase 4). - Reports: no name filter on `rp list` — sweep the whole list through the same paginate mode, stating the rows path (the envelope carries a root `alerts` block beside the rows; canon: setup Phase 4): `node .gs-superadmin/plugin/scripts/capture.mjs --paginate --page-flag page --items-path data.data --out .gs-superadmin/tmp/deprecate-reports-{page}.json -- gs-admin --json rp list --limit 200` then match the name against every page file locally. The sweep's verdict decides what the pages prove (canon: setup Phase 4): `reconciled` is the complete list; `unverified` (also exit 0 — no payload total) is the CLI-reachable set, and its disclaimer travels with the answer; a non-zero verdict proves nothing — never a "no match". - Data Designer: designs are not indexed in the KB (the `data-designer/` inventory holds Design *Templates*, a different asset) and have no live list command — and no describe command either, so the CLI cannot read a design's current state at all. Ask the user for the design id **and its current name, description, and schedule as shown in the UI**: those user-supplied values are the only possible source for the already-deprecated guard and step 3's Current column. Exactly one match → continue. Multiple → show them and ask the user which one — the manifest grep and `--search` both match substrings, so a longer name containing yours (or the asset's own already-deprecated `D.`-prefixed copy) also hits; trust a match only when its `name` equals the requested name exactly — or equals it after stripping a leading date-shaped rename prefix (e.g. `D.07.22.2026 ` or `D.07.22.26 ` — both year widths occur live), which is the already-deprecated case: resolve to that asset and let the guard below report it, rather than discarding the row and claiming no match. None (KB and live) → report and stop. Then describe it (rules: `gs-admin --json re r describe --id `; reports: `gs-admin --json rp describe --id ` — shapes below), captured to a tmp file via the capture helper (step 2's invocation shape; `` is `.gs-superadmin/tmp/deprecate-describe-.json`, one file per described asset, distinct from step 2's `deprecate-list-{page}.json` sweep, and a single-shot capture, no `--paginate`: `--out `, command after `--`), to capture the current name, description, folder, and schedule state, and confirm the KB-resolved id is live. Data Designer: skip — there is no describe surface; the user-supplied UI values from above stand in for this capture, and the plan must say the id could not be confirmed live. **Already-deprecated guard** — run it on the live name from that describe (rules: `ruleName`; Data Designer: the user-supplied current UI name, the only name available), never the KB name, which may predate a rename: if the live name starts with a date-shaped instance of the rename prefix — for `D.MM.DD.YYYY ` match the digits pattern with the year as **two or four digits** (`D.\d{2}\.\d{2}\.(\d{4}|\d{2}) `, e.g. `D.07.01.2026 ` or `D.07.01.26 `; live tenants mostly deprecate with the two-digit form even where the documented format shows four), never the literal placeholder string — the asset is already deprecated. Report that and ask the user how to proceed instead of proposing a second prefix. JSON shapes, so you don't spend calls probing (`--json` envelope): - `re r list` rows are `data.data[]`, keyed `ruleId` / `ruleName` (not `id`/`name`). - `re r describe` returns `data.ruleDetails`: `ruleName` (NOT `name` — same trap as list; there is no `name` key, though `id` is present here alongside `ruleId`), `description`, `active`, a numeric `folderId` (resolve to a folder name via `re r folders list`), and `nextScheduledRun` — capture it now (an epoch-ms number when set, else null). Non-null proves a pending future run; **null does not prove no schedule** — step 4's search decides. - `rp list` rows are `data.data[]`, keyed `reportId` / `reportName` (plus `reportDescription`; **no folder key of any kind**). `data.pageInfo` carries `totalRecords` and `pageSize` — note `pageSize`, not `limit`. - `rp describe` returns `data` keyed `reportId` / `reportName` / `reportDescription` (the only description-shaped key), alongside the definition fields (`sourceDetails`, `showFields`, `groupByFields`, …). Live-verified 2026-07-25. ### 3 — Present the plan and get approval Show the user exactly what will change, e.g. for a rule deprecated on 2026-07-01 with ticket GAIN-1247: | Field | Current | After | |---|---|---| | Name | `DATA\|USER\|MODIFY Assign License` | `D.07.01.2026 DATA\|USER\|MODIFY Assign License` | | Description | `…` | `Deactivated GAIN-1247 — …` | | Folder | `CTAs` | `Deactivated Rules Pending Delete` | | Schedule | pending run (`nextScheduledRun` 1785360300000) | removed | (The Description row follows step 4's joining rule: when the old description is empty, the After value is just `Deactivated GAIN-1247` — no trailing ` — `. The Schedule row renders what step 2 captured: the `nextScheduledRun` value when non-null, as shown; when null — the live norm even for scheduled rules — render `none pending (null); step 4's search decides` with After `removed if step 4 finds one`, since the schedule search runs only after this plan is approved.) > ⚠️ Since CLI 1.0.8 `re r edit` and `re r delete-schedule` are catalog-mutating — expect > a guard prompt per command when the plan executes. Those prompts confirm each command; > the user's explicit approval of this plan is the gate. **Stop and wait for it.** Before applying — rules domain only — verify the target folder exists (`gs-admin --json re r folders list`). There is no CLI folder creation — if it's missing, ask the user to create it in the UI first (or approve proceeding without the folder move). Skip this check for reports and Data Designer: their folder moves are UI-only manual steps (step 5), and `re r folders list` is the rules-engine namespace. ### 4 — Apply (per domain) Description template: the ` — ` half (em-dash separator included) is appended **only when the old description is non-empty** after trimming whitespace. An undocumented asset gets just `Deactivated ` — never a dangling `Deactivated — `. (The separator is this skill's joining convention, not part of the process file's prefix format.) Build step 3's plan table the same way. **Rules** (fullest CLI support): 1. If step 2's describe showed a non-null `nextScheduledRun` — or the rule appears in the SCHEDULE-filtered list, swept through the paginate mode (canon: setup Phase 4 — the mode exhausts the pages, so a full page is never where the evidence ends): `node .gs-superadmin/plugin/scripts/capture.mjs --paginate --page-flag page --out .gs-superadmin/tmp/deprecate-schedule-{page}.json -- gs-admin --json re r list --search '' --filter-execution-type SCHEDULE --limit 200` with a returned row (any page file) whose **`ruleId` equals ``** — run `gs-admin re r delete-schedule --id `. This search is the **primary** detection path, not an edge case: `nextScheduledRun` means "a future run is pending", not "a schedule object exists" (measured live 2026-07-25: null on all 67 SCHEDULE-type rules of one tenant, 32 of them active). The catalog DOES carry two schedule read commands — `re r schedules --id` (the schedules configured on a rule) and `re r test-schedule` (a CRON preview) — but `re r schedules` returned an EMPTY list for every rule tested at CLI 1.0.9, including active SCHEDULE-type rules (measured on one tenant; a tenant whose rules carry individual non-chain schedules may differ), so the filter is the read surface that actually answers the question. `--search` matches substrings — ignore rows whose `ruleId` differs — and only a sweep that ends `reconciled` (or `unverified` with its disclaimer carried, per the canon; `re r list` carries a total, so expect `reconciled`) has searched every page; a non-zero verdict has not proved the rule unscheduled. 2. `gs-admin re r edit --id --new-name 'D.MM.DD.YYYY ' --description 'Deactivated — ' --folder-name ''` **Reports** (UI-only — kept manual for a FOLDER reason, not a merge reason): do **not** use `rp update` for deprecation. It PUTs a whole GSReportMaster body, but the old fear is retired: its fetch-then-merge is verified live (1.0.7, throwaway report — a name-only call preserved 25 of 27 top-level fields byte-identical; before CLI 1.0.6 the required `--object`/`--show-fields` meant omitted fields reset to defaults, which no longer occurs at this pin). What keeps reports on the manual list is the folder: the PUT body drops the report's folder id, and the folder is invisible to the CLI in both directions (`rp describe` returns no folder field; no `rp list` row carries one), so an edit that silently re-foldered the report could not be detected from the CLI — and deprecation moves reports between folders by design. Rename, description prefix, folder move, and Set-to-Private all go on step 5's manual list until the folder behavior is verified in the UI. `rp describe --id` (read-only) remains the capture path for the plan table and the already-deprecated check. **Data Designer** (no CLI support for rename/unschedule): print the process checklist for the user to execute in the UI; nothing to apply. ### 5 — Manual steps (always print) End with the checklist of what the CLI cannot do, drawn from the process file, e.g.: - Remove the rule from its Rule Chain (UI) - **Deactivate the rule** (UI — no CLI verb) - Rename the report (`D.MM.DD.YYYY ` prefix) and prefix its description (UI — the report's folder is CLI-invisible; see step 4's Reports note) - Remove the report from dashboards / 360 layouts; set report to Private (UI) - Diary note: after the retention period (e.g. 3 months), delete and purge from trash ### 6 — Update the KB Mark the manifest entry stale so the KB reflects the deprecation: ``` node .gs-superadmin/plugin/scripts/manifest.mjs mark --manifest /_manifest.json --key / --status stale ``` (Rules and reports only — Data Designer designs have no inventory entry to mark. Also skip this when the asset was resolved via live search only, i.e. step 2 found no KB entry: there is no manifest key to mark.) Report what was applied, what remains manual, and the retention date.