investigate-settlement-exception

Files (2)

• SKILL.md
• run_investigation.mjs · scripts/

SKILL.md (first lines)

# ClearSet AI — Settlement Exception Investigation Skill

## Purpose

This skill orchestrates a complete post-trade settlement exception investigation for ClearSet AI.
It calls the live Express backend (running at `http://localhost:3001`) which is connected to
`CLEARSET_DB.CLEARSET_SCHEMA` in Snowflake.

**Never perform irreversible operational actions** (SWIFT message dispatch, trade modification,
email/phone notification) without explicit human analyst approval. This skill is analysis-only.

---

## How to Invoke

Ask in chat:

> "Investigate settlement exception TRD-92831"
> "Run a settlement investigation for trade TRD-92831"
> "Investigate the highest-risk settlement exception"

Or run the demonstration script directly:

```bash
node .kiro/skills/investigate-settlement-exception/scripts/run_investigation.mjs TRD-92831
```

---

## Investigation Workflow (10 Steps)

When asked to investigate a settlement exception, execute the following steps in order.
For each step, call the appropriate live endpoint or service. Do NOT hardcode any data values.

### Step 1 — Verify Backend Health

Before anything else, call `GET http://localhost:3001/api/health`.

- If `snowflake: true` → proceed with live Snowflake data.
- If `snowflake: false` → report that the backend is in local simulation mode and continue
  with the local fallback data available in `src/data/syntheticData.ts`.

### Step 2 — Retrieve Exception Details

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

Find the exception matching the requested trade ID. Extract:
- `EXCEPTION_ID`, `TRADE_ID`, `EXCEPTION_TYPE`, `RISK_SCORE`, `SEVERITY`
- `SSI_STATUS`, `EXCEPTION_STATUS`, `TRADE_VALUE`
- `COUNTERPARTY_NAME`, `CP_ID`

Expected for TRD-92831:
```
EXCEPTION_ID:    EX-92831
TRADE_VALUE:     2400000
RISK_SCORE:      91
SEVERITY:        CRITICAL
EXCEPTION_TYPE:  Missing Instruction
SSI_STATUS:      MISSING
CP_ID:           CP-192
```

### Step 3 — Retrieve Trade Details

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

Find TRD-92831 and extract: ticker, ISIN, asset class, depository, settlement type,
settlement status, instruction status, currency.

### Step 4 — Retrieve Settlement Events

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

List all SWIFT/depository events in chronological order. For TRD-92831, expect 5 live events
from Snowflake `SETTLEMENT_EVENTS` table including SWIFT MT541, MT548, and INTERNAL_ALERT types.

### Step 5 — Retrieve Counterparty Profile

Call `GET http://localhost:3001/api/counterparties/{CP_ID}`.

Extract: `NAME`, `BIC`, `CREDIT_RATING`, `PRIOR_FAILURES_30D`, `HISTORICAL_FAIL_RATE`,
`AVG_RESOLUTION_HOURS`, `PRIMARY_DESK_CONTACT`.

Expected for CP-192:
```
NAME:                  Apex Prime Clearing Ltd.
PRIOR_FAILURES_30D:    7
HISTORICAL_FAIL_RATE:  8.4
```

### Step 6 — Retrieve Applicable SOP via Cortex Search

Call `POST http://localhost:3001/api/cortex/search` with:
```json
{
  "query": "missing settlement instruction expedited SSI repair close to cutoff",
  "limit": 3
}
```

Extract the top matching policy document code, section, and title.

Expected top result:
```
DOC_CODE:      SOP-3.2
POLICY_SECTION: Expedited SSI Repair
```

This uses Snowflake Cortex Search over the live `POLICY_CHUNKS` table.

### Step 7 — Query Cortex Analyst for Analytical Confirmation

Call `POST http://localhost:3001/api/cortex/analyst` with:
```json
{
  "question": "Show me trade TRD-92831 with its trade value, settlement status, instruction status, risk score, and exception type."
}
```

From MADHANKUMAR98/clearset-ai, MIT.

More from MADHANKUMAR98/clearset-ai