> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsa.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Rule Engine Authoring Skill

> AI skill for deep Corsa rule authoring via REST API — full property catalog, advanced aggregations, lifecycle management, and evaluation.

## Overview

The **corsa-rule-engine-authoring** skill adds deep Corsa rule engine knowledge to your coding tool (Cursor, Claude Code, VS Code, etc.) so it can build, test, and manage transaction-monitoring rules directly via the REST API. It covers the complete property catalog, advanced aggregation operators, nested condition logic, rule lifecycle, and evaluation.

Pair with **corsa-rule-spec-drafting** to go from a compliance policy clause → grounded rule description → implementation.

### What It Helps With

* Translating a compliance policy into a valid rule JSON payload
* Building complex conditions with nested AND/OR logic and aggregation/velocity time windows
* Configuring `CREATE_ALERT` and `HALT_TRANSACTION` actions
* Managing rule lifecycle (draft → activate → disable → delete)
* Testing rules against transaction history with the evaluation API

***

## Quick Start

After installing the skill, ask your coding tool questions like:

* *"Build a rule that flags structuring: 3+ deposits between $9K–$9,999 in 24 hours"*
* *"Create a rule that fires when a sender's total deposits in 7 days exceed \$50K"*
* *"What aggregation operators are available for velocity checks?"*
* *"How do I update an active rule without downtime?"*
* *"Test my rule against a transaction without creating an alert"*

***

## What the Skill Knows

### Rule Lifecycle

```
Create   POST /v1/rules                  → status: "draft"
Activate POST /v1/rules/{id}/activate    → status: "active"
Disable  POST /v1/rules/{id}/disable     → status: "disabled"
Delete   DELETE /v1/rules/{id}           → soft-delete (non-active rules only)
```

* Only **active** rules evaluate incoming transactions
* Updating an **active** rule atomically creates a new version — the old version is disabled
* `activate` and `disable` accept an optional `{ "reason": "..." }` body for the audit trail
* Disable a rule before deleting it

### Condition Types

**Simple conditions** — compare a field on the entity to a value using an operator (`equal`, `notEqual`, `greaterThan`, `lessThan`, `in`, `notIn`, `contains`, `between`, `isNull`, `isNotNull`, and more).

**Aggregation conditions** — rolling time-window checks for velocity and structuring detection (`sum`, `count`, `countDistinct`, `avg`, `min`, `max`, `median`, `stddev`, `percentile`, `velocityChange`, `deviationFromAverage`, `baselineComparison`).

**Dynamic thresholds** — compare an aggregation against a per-client configured limit using `path: "client.sender.dailyLimit"` instead of a hardcoded value.

### Entity Property Catalog

Rules inspect the transaction and its direct participants: `transaction`, `client`, `wallet`, `bankAccount`. Key properties include risk tier/score, KYC/AML status, country, amount, currency, type, and more — the skill knows the full catalog.

### Actions

| Action             | Effect                                                                                                                                                                |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CREATE_ALERT`     | Creates a compliance alert (category, priority, status configurable). When multiple rules match one transaction, alerts are **consolidated** at the highest priority. |
| `HALT_TRANSACTION` | Contributes `FREEZE` to the evaluation decision. Combine with `CREATE_ALERT`.                                                                                         |

### Evaluation API

* **On-demand testing**: `POST /v1/evaluation/evaluate` — returns what *would* happen without creating alerts
* **History by transaction**: `GET /v1/evaluation/transaction/{id}/results`
* **History by rule**: `GET /v1/evaluation/rule/{id}/results`

### Rule Templates

Browse pre-built templates, copy one as a draft, customize, and activate:

```bash theme={null}
GET  /v1/rule-templates            # browse templates
POST /v1/rule-templates/{id}/copy  # copy as draft → returns { ruleId }
```

***

## Common Mistakes It Prevents

| Mistake                                             | What the skill does                                                  |
| --------------------------------------------------- | -------------------------------------------------------------------- |
| Expecting `evaluate` API to create alerts           | Clarifies alerts only come from the ingestion pipeline               |
| Trying to delete an active rule                     | Guides to disable first, then delete                                 |
| Forgetting to activate after creating               | Reminds that rules start as drafts                                   |
| No `label` on conditions                            | Always includes labels for readable evaluation results               |
| Hardcoding thresholds that should scale per client  | Uses `path: "client.sender.dailyLimit"` for dynamic thresholds       |
| Combining `HALT_TRANSACTION` without `CREATE_ALERT` | Reminds to add an alert so analysts see why a transaction was halted |

***

## Source

<Card title="GitHub Repository" icon="github" href="https://github.com/corsa-labs/corsa-skills/tree/main/corsa-rule-engine-authoring">
  View the full skill source with the complete property catalog, aggregation examples, and API reference.
</Card>