/dx-devops-request-status

name: dx-devops-request-status
description: "Use this skill to poll the status of an asynchronous DevOps Center request — a promotion or deploy operation. Provide the request token returned by dx-devops-promote (the promote response) to check completion, monitor progress, or verify success or failure via sf devops request status. TRIGGER when the user wants to check whether a promotion or deploy finished, monitor an in-flight async request, poll until a request completes, or confirm a request succeeded before finalizing. DO NOT TRIGGER for initiating a promotion or deploy (use dx-devops-promote), for work item creation or status transitions (use dx-devops-work-item-manage), or for conflict detection. Read-only status check — never mutates pipeline state."
metadata:
  version: "1.0"
  domains: ["Developer Experience"]
  minApiVersion: "58.0"
  relatedSkills:
    - "dx-devops-promote"
    - "dx-devops-work-item-manage"
  cliTools:
    - tool: ["jq"]
      semver: ">=1.6"
    - tool: ["sf"]
      semver: ">=2.0.0"
  accessCheck: "(OrgPreferences.ALMDevopsCorePref) && (UserPermissions.UserHasDevOpsCore)"

DevOps Center Request Status

Polls the status of an asynchronous DevOps Center request — a promotion or deploy operation — by its request token via `sf devops request status`. Provides headless, `--json`-driven, read-only status checks for autonomous release workflows in CI. This skill never mutates pipeline state; it only reports the current status of an in-flight or completed request.

Scope

• **In scope**: Check the status of a single async request by its request token; interpret the two-level outcome (request-processing `.result.status` vs. the `.result.errorDetails` failure oracle); poll with backoff until a request finishes or a caller-supplied timeout is reached; surface parsed error details on failure
• **Out of scope**: Initiating a promotion or deploy (use `dx-devops-promote`), work item creation/status updates (use `dx-devops-work-item-manage`), conflict detection, running `sf devops promotion complete` (that is the caller's next step after this skill confirms success), pipeline or project setup

---

Required Inputs

Gather or infer before proceeding:

• **Request token** (required): the request token returned in the `dx-devops-promote` promote response. Passed via `-i/--request-token`. Without it, this skill cannot proceed — ask for it or obtain it from the prior promote step's output
• **Target org**: `-o/--target-org <alias>` (required unless the `target-org` config variable is set)

Defaults unless specified:

• Output format: `--json` for headless consumption
• Polling interval: 10 seconds between checks; cap total wait at a caller-supplied timeout (default 30 minutes). Never poll faster than every 5 seconds — DOCe API rate limits apply

If the user gives a clear request ("check request a0B…", "poll request a0B… until it finishes"), proceed once you have the request token.

---

Workflow

All operations use `sf devops request status` with `--json` output. This skill is **read-only** — it issues no mutations. The command's flags and JSON output schema are documented in `references/cli-commands.md`.

Phase 1 — Authenticate and confirm the request token

1. **Verify org authentication** before any operation:

   sf org display --json

• If it fails, instruct the user to run `sf org login web --set-default --alias <alias>`
• Pass `-o/--target-org <alias>` on every subsequent command (required unless the `target-org` config variable is set)

2. **Confirm you have a request token.** If the user initiated a promotion in the same session, reuse the request token captured from the `dx-devops-promote` promote response. If no token is available, STOP and ask for it — do NOT guess or fabricate a token.

Phase 2 — Single status check (two-level semantics)

> **CRITICAL:** `.result.status` (uppercase, e.g. `SUCCESS`) reports whether the async **request finished processing** — NOT whether the underlying deploy succeeded. A request can show `status: "SUCCESS"` while the deployment itself **failed**. The real outcome oracle is `.result.errorDetails`: **non-null `errorDetails` means the operation failed, even when `status == SUCCESS`.**

3. **Run a single status check** with `scripts/poll-status.sh --once`, which queries the request once and derives the true outcome deterministically (glob-matches the operation-prefixed `.result.status` suffix, then applies the `.result.errorDetails` failure oracle). Do NOT hand-roll the JSON parsing in prose — the script owns the two-level rule so it stays consistent with the polling path:

   scripts/poll-status.sh --once <request-token> <target-org-alias>

Interpret the exit code (the script prints a human-readable line to match):

• `0` — request finished and the operation **succeeded** (`errorDetails` null) → hand back to the caller
• `2` — request finished but the operation **FAILED** (status suffix `*FAILED*`/`*ERROR*`/`*CANCELED*`, or a `*SUCCESS*` status with non-null `errorDetails`) → the printed line carries the parsed `errorType`/`errorMessage`
• `4` — request is **still processing** (non-terminal suffix) → proceed to Phase 3 to poll, or report in-progress for a one-shot check
• `1` — query/usage error (bad token, auth, or missing dependency)

Phase 3 — Poll until terminal (only when asked to wait)

4. **Poll with a bounded loop** when the user asks to wait for completion. Run `scripts/poll-status.sh` and report the final status it prints:

   scripts/poll-status.sh <request-token> <target-org-alias> [interval-seconds] [timeout-seconds]

• The script polls every `interval-seconds` (default 10), never sleeps past `timeout-seconds`, stops on a terminal request state, and applies the same two-level outcome check as `--once`. Exit codes: `0` = finished + succeeded (`errorDetails` null), `2` = finished but the operation failed (`errorDetails` set, or