investigate-settlement-exception

Files (1)

• SKILL.md

SKILL.md (first lines)

# ClearSet AI — Settlement Exception Investigation

## Overview

ClearSet AI is a post-trade settlement operations application backed by
`CLEARSET_DB.CLEARSET_SCHEMA` in Snowflake. This skill orchestrates a complete
10-step settlement exception investigation using live Snowflake data.

**Snowflake objects used by this skill:**

| Object | Type | Purpose |
|---|---|---|
| `V_EXCEPTIONS_ENRICHED` | Semantic view | Exception details, risk scores, SSI status |
| `TRADES` | Table | Trade master data |
| `COUNTERPARTIES` | Table | Counterparty failure records |
| `SETTLEMENT_EVENTS` | Table | SWIFT / depository event audit trail |
| `CLEARSET_ANALYTICS` | Semantic view | Cortex Analyst NL-to-SQL queries |
| `CLEARSET_POLICY_SEARCH_SERVICE` | Cortex Search service | SOP and policy retrieval |

**Safety constraint:** This skill is read-only. It retrieves and analyses data only.
It must **never** autonomously send SWIFT messages, send emails, place calls, modify trades,
modify settlement instructions, or approve exceptions. Every recommended operational action
requires explicit human analyst authorisation before execution.

---

## Invocation

CoCo will auto-select this skill when the prompt clearly matches its description.
You can also invoke it explicitly:

```
$investigate-settlement-exception <TRADE_ID>
```

Or ask in plain language:

> "Investigate settlement exception <TRADE_ID>"
> "Run a settlement investigation for the highest-risk open exception"
> "Why is <TRADE_ID> critical?"

---

## Prerequisites

The ClearSet backend Express server must be running on `http://localhost:3001` for the
application API steps (Steps 1–5). Steps 6 and 7 use Snowflake Cortex directly.

To start the backend:
```bash
cd server
node --import tsx index.ts
```

Alternatively, run the bundled demonstration script which exercises all steps end-to-end:
```bash
node .kiro/skills/investigate-settlement-exception/scripts/run_investigation.mjs <TRADE_ID>
```

> Note: The demonstration script lives under `.kiro/skills/` because it was created
> alongside the Kiro version of this skill. It is shared between both skill registrations
> and calls the same live backend endpoints. No credentials are embedded in the script.

---

## Investigation Workflow

Execute all 10 steps in sequence. Do **not** hardcode values — retrieve current data
from the application and Snowflake at runtime.

### Step 1 — Verify Connection and Data Mode

Call `GET http://localhost:3001/api/health`.

- Response `snowflake: true` → all subsequent steps use live Snowflake data.
- Response `snowflake: false` → the application is in local simulation mode.
  Report this clearly and proceed using the local fallback data, noting that
  results are simulated.

### Step 2 — Retrieve Exception Details

Call `GET http://localhost:3001/api/exceptions`.

Locate the exception matching the requested trade ID. Extract:

- `EXCEPTION_ID` — unique exception reference (e.g. EX-92831)
- `TRADE_ID` — linked trade identifier
- `EXCEPTION_TYPE` — failure category (e.g. Missing Instruction, Cash Discrepancy)
- `RISK_SCORE` — Snowflake-calculated risk score (0–100)
- `SEVERITY` — CRITICAL / HIGH / MEDIUM / LOW
- `SSI_STATUS` — MISSING / MISMATCHED / PENDING / MATCHED
- `EXCEPTION_STATUS` — OPEN / INVESTIGATING / PENDING_APPROVAL / RESOLVED
- `TRADE_VALUE` — gross monetary exposure in USD
- `COUNTERPARTY_NAME`, `CP_ID` — counterparty identity

This endpoint queries `V_EXCEPTIONS_ENRICHED` in `CLEARSET_DB.CLEARSET_SCHEMA`.

### Step 3 — Retrieve Trade Master Data

Call `GET http://localhost:3001/api/trades`.

Locate the matching trade and extract: ticker symbol, ISIN, asset class,
depository (DTC / Euroclear / Fedwire), settlement type (DVP / FOP / RVP),
settlement status, instruction status, settlement date, and booking desk.

### Step 4 — Retrieve Settlement Event History

Call `GET http://localhost:3001/api/settlement-events/{TRADE_ID}`.

List all events in chronological order. Each event includes:
- `EVENT_ID`, `EVENT_TIMESTAMP`
- `MESSAGE_TYPE` — SWIFT MT541, MT548, MT599, ISO 20022, INTERNAL_ALERT
- `STATUS` — depository milestone (e.g. TRADE_BOOKED, SSI_NOT_FOUND, CRITICAL_RISK_FLAGGED)
- `DESCRIPTION` — message payload text
- `SOURCE` — MATCHING_ENGINE / DEPOSITORY / CLEARSET_AGENT

This data comes from `CLEARSET_DB.CLEARSET_SCHEMA.SETTLEMENT_EVENTS`.

### Step 5 — Retrieve Counterparty Risk Profile

From MADHANKUMAR98/clearset-ai, MIT.

More from MADHANKUMAR98/clearset-ai