# Atlas Ops Reporting

> Produce cutoff-based operational reports and authorized data corrections from the Atlas Commerce Operations workplace database. Use when a task points at a `<TASK_ENV_BASE_URL>` Atlas service with GET /api/schema, GET /api/data-dictionary, POST /api/sql (read-only) and POST /api/sql/transaction, ships a request-facts payload plus an answer_template.json JSON-Schema, and asks for one exact answer.json — e.g. fulfillment scorecards, refund/settlement reconciliations, warehouse productivity reviews, support-health reviews, or carrier-quality canonical corrections.

- Skill: `prism-shadow/atlas-ops-reporting-5` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add prism-shadow/atlas-ops-reporting-5`
- Raw SKILL.md: https://api.skillmd.com/api/skills/prism-shadow/atlas-ops-reporting-5/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: prism-shadow (https://skillmd.com/u/prism-shadow)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/prism-shadow/atlas-ops-reporting-5

---


# Atlas Commerce Operations reporting & correction

You are given a task folder with `input/prompt.txt`, an
`input/payloads/<something>_request.json` (the authoritative business facts,
windows, thresholds, and orderings), and `input/payloads/answer_template.json`
(the exact output contract). The workplace service is reached over the network
using the credentials in `environment_access.md` (Base URL + `Authorization:
Bearer …`). Your job is to compute the requested result and write it to
`answer.json`, conforming **exactly** to the template with no extra commentary.

## Procedure

1. **Read the two payloads first.** The request payload defines every window,
   cutoff, threshold, tier rule, ordering, and rounding — treat it as ground
   truth and never hardcode values from memory or from past tasks. The
   answer_template defines the output shape. Note whether the task is
   **analytical-only** or an **authorized correction** (it will explicitly grant
   a correction with a reason_code/actor/audit_id/correction_key/success rule).

2. **Connect and discover the real schema.** Use the client:

   ```
   python3 skill/scripts/atlas_client.py schema
   python3 skill/scripts/atlas_client.py dict
   python3 skill/scripts/atlas_client.py sql "SELECT ... "
   ```

   (Or import `AtlasClient` from `skill/scripts/atlas_client.py`.) It reads
   `environment_access.md`, sends the bearer token, and retries transient 5xx.
   Get real table/column names and enum values from `GET /api/schema` and
   `GET /api/data-dictionary`; the dictionary is where domain terms like
   *effective*, *canonical*, *logical*, *production*, and *active time* are
   pinned for this dataset. Probe distinct values before filtering — confirm
   each status/tier/region/currency literal actually exists.

3. **Compute with SQL through `POST /api/sql`** (read-only). Build up the
   metrics the template requires. Honor these recurring rules (details and the
   per-task-type recipes are in `references/playbook.md`):
   - Include only **production** rows; exclude test/sandbox.
   - Evaluate state **as of the stated cutoff**; timestamps are exact UTC
     boundaries with the stated inclusivity. Membership windows and status
     cutoffs are usually different dates — keep them separate.
   - Compute on **effective/canonical** values; refunds net against reversals.
   - Keep full eligible populations in rate **denominators**.
   - **Round only final reported values**; sort and tie-break on unrounded
     values, applying every tie-break key the payload lists.
   - Classify status/risk **top-down, first match wins**, using the exact
     thresholds and comparison operators from the payload.

4. **For an authorized correction only**, use `POST /api/sql/transaction` to
   change the single minimal canonical field and insert exactly one audit row,
   then verify post-change and report `APPLIED`/`NOT_APPLIED` per the success
   rule. Leave raw source values, identity fields, and unrelated rows untouched.
   Never mutate for analytical-only tasks. See the correction section of
   `references/playbook.md`.

5. **Assemble `answer.json` to the contract.** Emit exactly the required keys,
   correct JSON types, exact enum strings, ID formats preserved, arrays sized/
   ordered/deduped as specified. Details and pitfalls: `references/output-
   contract.md`.

6. **Validate before finishing:**

   ```
   python3 skill/scripts/validate_answer.py answer.json input/payloads/answer_template.json
   ```

   Fix every reported shape problem. The output file must contain **only** the
   JSON document — no prose, no code fences, no extra fields.

## Files in this skill

- `references/playbook.md` — recurring Atlas semantics and per-task-type
  computation recipes (fulfillment, refund/FX, warehouse, support, correction).
- `references/output-contract.md` — how to read the answer_template schema and
  the contract mistakes that cost points.
- `scripts/atlas_client.py` — stdlib API client (schema / dictionary / audit /
  sql / transaction / introspect) with token handling and 5xx retry.
- `scripts/validate_answer.py` — best-effort shape validator for answer.json vs
  the template (does not check business correctness).

## Guardrails

- The request payload and data dictionary — not this skill and not prior
  answers — supply all business values. Nothing task-specific is baked in here.
- Analytical tasks are read-only; only run a transaction when the request
  explicitly authorizes the correction and its audit record.
- If the schema endpoints keep returning 5xx, keep retrying (the client backs
  off) and cross-check names via `introspect`; don't guess table names blindly.