@1aboveio/skills 1.0.10 → 1.0.11

package/skills/risk-compliance/fraud-detection/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: fraud-detection
+description: >
+  Rapidly discover interpretable transaction-level fraud detection rules from
+  tabular payment, transfer, collection, payout, account, or fraud-case data
+  (CSV, XLSX, TXT).
+  Supports third-party fraud (including stolen credentials and account takeover),
+  first-party fraud or deliberate account abuse, and authorized payment scams
+  (including APP scams), across card payments, collections, bank transfers, and
+  payouts. Supports rapid rule discovery, evidence-qualified metrics,
+  domain-appropriate actions, strategy
+  impact, and a business report. Use for fraud, scam, mule, account-takeover,
+  chargeback, dispute, transfer, collection, or payout risk analysis even when the
+  user does not name this skill.
+release-version: 0.45.0
+---
+**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
+# Fraud Detection
+
+Analyze fraud through composable dimensions rather than treating every case as
+card fraud:
+
+- **Archetype** — the genuine customer's relationship to the fraud
+- **Mechanism** — how compromise, deception, or abuse occurred
+- **Context** — the product or money-movement surface where a rule fires
+
+Run this **10-step** loop:
+
+0. Pre-flight → 1. Profile → 2. Label → 3. Evidence basis → 4. Engineer features →
+5. Shortlist → 6. Score rules → 7. Map actions + packages → 8. Write report →
+9. Review
+
+**Produce:** operable rules and portfolio impact in a business report.  
+**Do not produce:** a black-box model as the main answer. Design and evaluate
+rules; do not deploy or operate a live detection engine.
+
+## Foundational contract
+
+- Score one transaction at a declared decision point; retain every applicable
+  rule hit. A transaction may trigger zero, one, or several rules.
+- Real-time features combine the current transaction with history available to
+  the detector. Include the current transaction in velocity by default.
+- Transaction-triggered rolling aggregates are real-time features. Completed
+  entity/period summaries are post-transaction review, not real-time rules.
+- Discover rules rapidly from recent transactions without requiring a
+  train/test/holdout split. State the evidence and limits of each metric.
+- Keep the core generic. Load selected domain references for expert candidate
+  patterns, not universal diagnoses, mandatory features, or thresholds.
+
+> Paths under `references/` are relative to this skill directory. Step detail:
+> [references/workflow.md](references/workflow.md).
+
+## Required references
+
+| File | When |
+|---|---|
+| [references/workflow.md](references/workflow.md) | Every step — full procedure |
+| [references/taxonomy.md](references/taxonomy.md) | Step 1; select archetype, mechanism, and context |
+| [references/entities.md](references/entities.md) | Pre-flight and Step 4; entity definitions and matching |
+| [references/enrichment.md](references/enrichment.md) | Pre-flight and Step 4; BIN, IP, FX, phone, bank-account, and ID-document readiness |
+| [references/feature-sql.md](references/feature-sql.md) | Step 4; executable SQL and standard rolling windows |
+| [references/feature-engineering.md](references/feature-engineering.md) | Step 4; shared decision-time rules |
+| [references/report-template.md](references/report-template.md) | Step 8; common report contract and overlay selection |
+| [references/terminology.md](references/terminology.md) | Step 8; fixed terms and language proofread |
+| [references/review-checklist.md](references/review-checklist.md) | Step 9; common and selected-profile checks |
+
+After Step 1, read only the selected profile references:
+
+| Dimension | References |
+|---|---|
+| Archetype | `references/archetypes/<archetype>.md` |
+| Mechanism | `references/mechanisms/<mechanism>.md` when present |
+| Context | `references/contexts/<context>.md` for every selected context |
+
+Read [references/collection-payout-features.md](references/collection-payout-features.md)
+for collection/payout features and review: event sequences, FIFO fund lots, and
+counterparty velocity. This is domain guidance across archetypes, not evidence
+that every rapid flow is knowing abuse.
+
+Current packs: archetypes `third-party-fraud`, `first-party-fraud`,
+`authorized-payment-scam`; mechanism `account-takeover`; contexts
+`card-payment`, `payment-collection`, `bank-transfer`, `payout`.
+
+## Progress
+
+Track a task plan. One item is `in_progress` at a time.
+
+1. Pass pre-flight
+2. Select analysis profile
+3. Formalize label
+4. Declare discovery and scoring evidence
+5. Engineer candidate features
+6. Select shortlist
+7. Score candidate rules
+8. Map actions and packages
+9. Write business report and proofread language
+10. Independent review
+
+Suggested notes: `preflight=…`, `profile=…`, `label=…`, `evidence=…`,
+`allowed/excluded=…`, `shortlist=…`, `N rules, recent|retrospective|subsequent`,
+`packages=…`, `report=…`, `verdict=…`.
+
+## Input
+
+CSV / XLSX / TXT; optional outcome column. Input may contain transaction,
+event, or case records, but real-time rule scoring is always transaction-level.
+Resolve transaction identity, retries, duplicates, and lifecycle updates first.
+Other events can supply context; entity/case summaries belong to review.
+
+## Workflow
+
+Follow [references/workflow.md](references/workflow.md) for each step. The map:
+
+| Step | Do | Gate |
+|---|---|---|
+| 0 Pre-flight | Transaction, entity, enrichment, and label readiness | Missing inputs block affected features or metrics, not all discovery |
+| 1 Profile | Archetype + mechanism(s) + context(s) from taxonomy | Read selected packs before Step 2 |
+| 2 Label | Formalize known positives / negatives / unlabeled | Do not invent negative labels or unsupported metrics |
+| 3 Evidence | Declare discovery/scoring windows and selection overlap | Temporal validation is optional |
+| 4 Features | Engineer transaction-triggered candidates | Current transaction included; no future information |
+| 5 Shortlist | Support / known fraud caught / reach / operability | Explain hypotheses and benign alternatives |
+| 6 Score | occurrence → precision → recall when supported | Name evidence basis and denominators |
+| 7 Actions | Map to context packs + strategy packages | Freeze packages before report |
+| 8 Report | Business report per template; grep terminology banned strings | No review process in the file |
+| 9 Review | Checklist + selected packs | Prefer fresh independent reviewer |
+
+## Output contract
+
+| Item | Requirement |
+|---|---|
+| Analysis profile | Archetype, role, consent, technical authentication, mechanism, context, confidence, grain, decision point |
+| Rule metrics | occurrence → precision → recall where supported; discovery/scoring windows and same-sample selection disclosed |
+| Strategy coverage | Union of triggered transactions: count + rate and amount + share, with currency; overlap and incremental coverage |
+| Domain impact | Measures and denominators from selected context packs only |
+| Uncertainty | Proxy labels, immature outcomes, weak identity links, and unresolved attribution stated |
+| Report file | Business content only; no reviewer model, verdict, or repair log |
+
+Steps 0–7 are analysis and its entry gate. Step 8 writes the report. Step 9
+reviews it.
+
+For step 8, read `{house-style baseDir}/references/analytical-reporting.md` and its
+required references, then use `{write-report baseDir}/SKILL.md`, passing this skill's
+report template, selected context packs, frozen results and required output artifacts.
+Keep all domain metrics, uncertainty disclosures and step 9 checks; report writing does
+not rerun rule discovery or replace the domain review. If a required skill or reference
+is unavailable, report the blocker instead of claiming the report stage is complete.
+For step 9, give the independent reviewer the shared analytical entrypoint and its
+required references as well as the domain checklist and selected packs.

package/skills/risk-compliance/{fraud-analysis → fraud-detection}/references/archetypes/first-party-fraud.md

@@ -14,7 +14,7 @@ claim, knowing mule activity, or another subtype.
 
 Do not classify a deceived, coerced, compromised, or merely unusual customer as
 first-party fraud without evidence of participation. Outcome maturity may extend
-beyond transaction settlement and must be reflected in the split.
+beyond transaction settlement and must be reflected in label eligibility.
 
 ## Feature families
 
@@ -39,6 +39,7 @@ from a proxy label alone.
 
 - Evidence supports knowing participation rather than victimization.
 - Mule status is not inferred from transaction shape alone.
-- Graph features and linked-entity lists are train-fit and point-in-time.
+- Graph features and linked-entity lists declare their discovery evidence and
+  are available at the scored decision.
 - Account restrictions and reporting recommendations identify policy and legal
   dependencies.

package/skills/risk-compliance/fraud-detection/references/archetypes/third-party-fraud.md

@@ -0,0 +1,47 @@
+# Archetype: third-party fraud
+
+The genuine customer did not consent; an external actor used the customer's
+identity, account, credentials, token, or payment instrument.
+
+## Label guidance
+
+Prefer confirmed unauthorized-fraud outcomes. Chargebacks, customer claims,
+issuer codes, account compromise flags, and manual decisions may be proxies;
+state their scope and maturity. Do not treat every decline or dispute as fraud.
+
+## Useful evidence
+
+- Instrument, account, customer, device, IP, email, phone, and session history
+- Deviation from the genuine customer's prior behavior
+- New or shared identifiers, credential failures, and compromise events
+- Transaction velocity, retries, beneficiary novelty, and location changes
+
+Use only evidence available at the selected decision point. A current response,
+claim, chargeback, or investigation outcome is not a pre-decision feature.
+
+## Velocity-pattern catalog
+
+These are hypotheses for transaction-triggered aggregates, not diagnoses, mandatory
+Cartesian combinations or prescribed thresholds. Use only available normalized
+identifiers and the decision-time windows in [feature engineering](../feature-engineering.md);
+include the current transaction. Examine support and benign alternatives before action.
+[Entities](../entities.md) explains weak linkage; [feature SQL](../feature-sql.md)
+shows the eligibility and null rules.
+
+| Candidate | What it may suggest | Benign alternatives |
+|---|---|---|
+| One email with multiple distinct PANs | Stolen-card use or card testing | Family purchases, shared mailbox, card replacement |
+| One device fingerprint with multiple distinct PANs | Concentrated stolen-card use or card testing | Shared household device, merchant terminal, fingerprint collision |
+| One IP with multiple distinct emails | Coordinated activity | NAT, workplace, VPN, public Wi-Fi |
+| Same PAN, amount and currency repeated | Split payments, repeated charges, or testing | Customer retry, network timeout, recurring purchases; splitting can also use differing amounts |
+| One PAN with multiple distinct names, with name role explicit | Card testing or identity variation | Authorized users, cardholder name variants, gifts or different shipping recipients |
+
+A completed-period entity review can investigate these patterns retrospectively,
+but cannot be substituted for the per-transaction features available at a decision.
+
+## Actions and review
+
+Actions depend on context: block or authenticate a card payment; terminate or
+reauthenticate a compromised session; hold/review a transfer or payout; restrict
+an account where policy permits. Review that technical authentication is not
+used as proof of genuine-customer consent.

package/skills/risk-compliance/fraud-detection/references/collection-payout-features.md

@@ -0,0 +1,151 @@
+# Collection and payout feature candidates
+
+Use at Steps 4 and 9 with the selected context packs and the shared feature,
+entity, enrichment, and review references. These are hypotheses, not diagnoses,
+mandatory features, thresholds, or evidence of a person's role. They apply across
+supported archetypes; retain the selected profile and its attribution confidence.
+
+## Decision-time sequence
+
+Score the current collection or payout transaction at its declared real-time
+decision point. Include current in eligible transaction counts and sums. Use only
+prior events and attributes available then, plus current attributes; never use
+current or later outcomes. An example journey is payer receipt → funds available →
+beneficiary setup → payout request. At receipt, a later payout, its completion,
+or its outcome cannot be a feature. At payout, prior known receipts and beneficiary
+setup may be features. Record the event timestamp, availability time, order,
+source, identity links and their confidence. Late-arriving records cannot rewrite
+what the earlier scorer knew. Deduplicate lifecycle updates and duplicate deliveries;
+count retries according to the declared transaction-identity policy.
+
+Candidates include time since last available receipt, receipt-to-payout sequences,
+new beneficiary followed by a payout, and number of prior receipts before current.
+Fast movement may also reflect scheduled supplier payments, payroll, or a merchant
+settling its sales. A sequence alone does not establish intent or participation.
+
+## FIFO funding attribution
+
+FIFO is an accounting attribution convention for candidate features, not a trace
+of actual money or proof of common ownership or intent. Scope lots to the
+balance-owning ledger account and currency. Use the availability timestamp of
+each eligible incoming receipt, then the actual deterministic order known to the
+ledger for ties. Never pool currencies or invent a tie-break order. If account,
+currency, available balance, receipt availability, or order is unknown, ask for
+the missing semantics and mark affected features unavailable.
+
+Reconstruct the state known immediately before the current payout debit, including
+prior committed debits and existing reservations. For the current payout, propose
+an allocation oldest available lot first, consuming partial lots and as many lots
+as needed. This is a preview: do not debit the candidate first and then allocate
+it again. For a release of an existing reservation, include its own reserved lots
+in the preview without allocating them a second time; exclude other reservations.
+Commit or release allocations only according to declared ledger lifecycle rules.
+Rejected or failed attempts before any reservation/debit consume no funds. A
+failure after a committed debit does not restore its lots: keep them consumed
+until an explicit reversal/return entry makes funds available under the declared
+policy. Restore reservations only when the ledger releases them; failure alone
+is not a release. Pending reservations cannot fund another payout. Ask which
+statuses reserve, debit, fail, and release, and when;
+if undefined, leave affected features unavailable rather than guessing. Reconcile
+retries and duplicate events against the same reservation/debit.
+
+Reconcile opening balance and known available lots to the ledger. Do not truncate
+FIFO state to a rolling velocity window: old unspent lots can still fund current
+payouts. Carry forward reconciled remaining lots or disclose missing history.
+Report unmatched
+opening balance and unknown or truncated history separately; do not invent source
+lots or treat unknown funding as zero. If ledger balance and reconstructable lots
+differ, expose both the matched and unmatched amounts and ask how the difference
+should be handled. An insufficient balance or incomplete history is not evidence
+of fraud. FX, fees, reversals and refunds require explicit point-in-time ledger
+entries and allocation semantics; do not assume ordinary inflows or rewrite a
+past decision using later corrections. Do not silently convert or pool currencies.
+
+For current payout amount `P > 0`, let `a_i` be each proposed matched amount,
+`age_i` the elapsed time from lot availability to the decision, and `M = Σa_i`.
+Report `M`, `P - M` as unmatched, and `M / P` as attribution coverage. Define:
+
+- Matched weighted fund age: `Σ(a_i × age_i) / M` when `M > 0`; otherwise unknown.
+  Label it matched-only and report coverage alongside it.
+- Recent funds share for a declared elapsed window: `Σ(a_i for lots available
+  in (t − window, t]) / P`. Report coverage; unmatched is unknown, not known old
+  funding. With incomplete attribution, this is the known recent share, not the
+  full share.
+- Distinct known funding counterparties among matched lots: count non-null,
+  normalized payer keys; report matched amount with known payer divided by `P`,
+  plus unknown-payer and unmatched amounts. A missing key is not a counterparty.
+  State entity type, role, linkage method and confidence; do not infer a person
+  from an account key or pool nulls.
+
+### Worked example
+
+At payout decision time `t`, one USD ledger account has two available receipts:
+A: $60 available 10 hours ago from known payer X; B: $50 available 2 hours ago
+with unknown payer. No other balance or reservations exist. A $90 payout previews
+$60 from A and $30 from B, leaving $20 of B. The $110 opening amount equals
+$90 allocated plus $20 remaining. Matched coverage is $90/$90 = 100%; weighted
+fund age is `(60 × 10 + 30 × 2) / 90 = 7.33 hours`. For a 6-hour window,
+recent share is $30/$90 = 33.33%. Distinct known payers = 1; known-payer coverage
+is $60/$90 = 66.67%, and $30 has unknown payer. These are proposed allocations,
+not proof of where the payout's money went.
+
+If a separate $130 candidate is scored against the same $110 pre-debit balance,
+FIFO matches $60 + $50 = $110 and leaves $20 unmatched: coverage is 84.62%.
+The known recent share is $50/$130 = 38.46%, not $50/$110. Weighted age of the
+matched portion is `(60 × 10 + 50 × 2) / 110 = 6.36 hours`; known-payer coverage
+is $60/$130 = 46.15%. Report the $20 shortfall and do not infer a funding source
+or a payout outcome. If a reservation or an unknown opening balance exists, the
+example's inputs and results change according to the declared ledger semantics.
+
+### Lifecycle example
+
+Given $100 available in one ledger account/currency, reserving $70 leaves $30
+spendable and $70 reserved. Committing that debit leaves $30 spendable, $0
+reserved, and $70 consumed. A later payout-failed notification without a return
+entry leaves those amounts unchanged; another $40 request has a $10 shortfall.
+If the ledger later posts a $70 return as available, spendable balance becomes
+$100. Whether returned funds restore original lot age or create a new available
+lot is a declared ledger policy, not inferred from the failure notification.
+Before the return, conservation is $100 = $30 remaining + $70 consumed; after
+it, account reconciliation is $100 original + $70 returned − $70 debited = $100.
+Do not both undo consumption and add the same return as a second credit.
+
+## Counterparty velocity
+
+Choose only useful combinations of direction, entity type and window. Name the
+balance-owning account, inbound payer or outbound beneficiary, and whether each
+key is an account, person, business, instrument or other declared type. Keep
+inbound and outbound roles separate, and disclose deterministic versus probabilistic
+links and confidence. Unknown identifiers are not pooled or counted as distinct.
+
+For each direction, distinguish (1) transaction count and same-currency amount
+sum for the same account–counterparty pair from (2) distinct inbound payers or
+distinct outbound beneficiaries per balance-owning account. Include the current
+transaction in eligible counts, sums and distinct values when its key is known.
+Missing keys yield unknown for the affected pair feature; report missing-key
+coverage for distinct counts. Missing amount or currency makes the affected sum
+unknown; do not silently omit it or sum currencies. Follow the shared as-of
+availability and tie-order rules and `(t − window, t]` boundaries.
+
+- `counterparty_pair_txn_count_<window>`: count on the declared account/payer
+  or account/beneficiary pair, with direction encoded in the specification.
+- `account_inbound_payer_distinct_count_<window>` and
+  `account_outbound_beneficiary_distinct_count_<window>`: distinct role-specific
+  keys for the same balance-owning account. Record entity type in the spec.
+
+The standard windows are 1m, 5m, 15m, 30m, 1h, 2h, 6h, 24h, 2d, 7d,
+14d, 21d and 30d; a day is 86,400 seconds. For example, a high count for one
+account–payer pair differs from many distinct payers; a marketplace may naturally
+have both many payers and many beneficiaries. Frequent payments to one beneficiary
+may be routine supplier settlement. Treat these as candidates with benign
+alternatives, not proof of fraud or a customer role.
+
+## Step 9 checks
+
+Check that sequence inputs were known at the decision, current is counted once,
+and no later outcome leaks into an earlier score. Check account/currency scope,
+actual lot order, pre-debit preview, partial allocations, reservation lifecycle,
+conservation, unknown history and coverage, and explicit nonordinary ledger
+semantics. Check pair versus distinct direction, entity linkage confidence and
+benign alternatives. Escalate undefined business or ledger semantics rather than
+inventing a policy; independent review remains owned by the reviewer.

package/skills/risk-compliance/{fraud-analysis → fraud-detection}/references/contexts/bank-transfer.md

@@ -1,8 +1,9 @@
 # Context: bank transfer
 
-Typical grains are beneficiary creation, transfer instruction, transfer
-execution, recall, or case. Decision points may be beneficiary setup,
-pre-execution, or post-transfer investigation.
+Score one transfer transaction, normally at instruction or pre-execution.
+Beneficiary creation supplies prior context; recall and case records supply
+outcomes or post-transaction review. Do not score beneficiary creation as a
+transaction.
 
 ## Features
 

package/skills/risk-compliance/fraud-detection/references/contexts/card-payment.md

@@ -0,0 +1,70 @@
+# Context: card payment
+
+Score one payment transaction, normally at pre-authorization. Authorization
+attempts need a retry policy; clearing and dispute records supply lifecycle
+context or post-transaction review, not additional scored copies.
+
+## Reported-fraud labels
+
+For reported-fraud rule analysis, combine available network/acquirer fraud reports
+(such as Worldpay DART/340FRD) with fraud-category disputes, including pre-dispute
+resolution records. A transaction is positive if either source reports it. Do not
+restrict fraud labels to financially settled or first-chargeback stages. This
+label is reported fraud, not necessarily independently confirmed fraud or loss.
+An explicit task-specific label definition overrides this default.
+
+- Identify fraud from documented category/reason mappings, not the mere presence
+  of a dispute or a pre-dispute stage. Non-fraud quality, service and clerical
+  disputes are not positive solely because they appear in the dispute file.
+- Link each source to a unique transaction using corroborated references and
+  original transaction attributes. Preserve unmatched/ambiguous records and
+  conflicting evidence instead of forcing a match.
+- Union positives by transaction ID. Repeated reports, multiple dispute stages,
+  and DART/dispute overlap contribute one positive transaction, not extra cases.
+- Retain evidence provenance and lifecycle. A later reversal or recovery does not
+  erase an earlier fraud allegation from a reported-fraud label; do not call its
+  disputed amount a confirmed or unrecovered loss.
+- Report DART-only, dispute-only, overlap and union counts in each scoring window,
+  plus pre-dispute/stage coverage. A transaction may appear in several stage
+  subsets, so do not sum those subsets as unique fraud transactions.
+- Network-metric exclusions (for example excluding certain pre-disputes from a
+  scheme monitoring ratio) do not define the fraud-detection positive class.
+  Keep regulatory/scheme ratio calculations separate from rule labels.
+- Absence from both feeds remains unlabeled unless a justified negative
+  definition exists. Delayed reports affect capture completeness, not whether an
+  already observed fraud pre-dispute qualifies as positive.
+- These later reports supply evaluation labels only. Historical fraud evidence
+  can enter a real-time feature only after it became available to the detector;
+  never leak the current transaction's future dispute into its own features.
+
+## Features
+
+Amount and currency, network, card type, token/PAN-derived identity, BIN, country,
+channel, entry method, MCC, merchant, device, customer history, and prior-event
+velocity. A masked PAN may be a weak identity key.
+
+CVV, AVS, authorization response, and 3DS result are same-response or later
+fields unless the chosen decision point explicitly occurs after them. Issuing
+bank name may be derived; prefer BIN for pre-authorization lists.
+
+Record discovery evidence and versions for BIN, country, merchant, and other
+lists. Reference rates must have been available at the scored decision; newly
+discovered lists are prospective candidates. Tiny lists remain monitor-only.
+
+## Actions and impact
+
+Actions: block, require 3DS/additional authentication, route, manual review, or
+monitor. For 3DS scenarios, failed authentication does not enter the subsequent
+authorization denominator. Report authorization success and absolute approval
+change only when measured or under explicit pass/conversion assumptions.
+
+## Review overlay
+
+- Available DART/network fraud reports and fraud disputes are unioned by
+  transaction, including fraud pre-disputes, with source overlap disclosed.
+- Non-fraud disputes are not positive; lifecycle reversals are not confused with
+  absence of an allegation or confirmed loss.
+- Current CVV/AVS/auth response/3DS result respects decision timing.
+- BIN lists declare discovery evidence and causal availability; issuer names
+  are operable only if available live.
+- 3DS and authorization denominators are explicit.

package/skills/risk-compliance/fraud-detection/references/contexts/payment-collection.md

@@ -0,0 +1,34 @@
+# Context: payment collection
+
+Score one collection transaction at its declared attempt or receipt decision.
+Settlement, return, and linked outflow records supply context at the time they
+become known, not duplicate scored transactions. State whether funds are card,
+bank debit, transfer, cash-equivalent, or mixed because reversibility differs.
+
+## Features
+
+For Step 4 feature engineering and Step 9 review, read
+[collection and payout features](../collection-payout-features.md). First-class
+entities include the balance-owning ledger account, inbound payer and funding
+instrument/account, plus linked outbound beneficiary where known. Enrichment may
+include point-in-time receipt availability, ledger status and currency, event
+order, and role-link confidence; use only available sources.
+
+Mandatory matching prerequisites are in [entities](../entities.md); inspect
+[enrichment](../enrichment.md) for phone country/area, bank-account platform/PSP
+and holder-type flags, and jurisdiction-specific ID-document geography. Company,
+person, role-specific address, and composite bank account are first-class
+entities, not interchangeable counterparty identifiers.
+
+Payer and funding-source novelty, amount and velocity, return history, settlement
+state known at decision time, payer concentration, many-payer fan-in, linked
+accounts/devices, account age, and elapsed time from receipt to intended outflow.
+
+Do not use a later return, recall, dispute, or investigation outcome to decide an
+earlier collection. Do not describe unsettled or reversible funds as final.
+
+## Actions and impact
+
+Actions: accept, review, delay availability, reserve, restrict downstream use,
+or reject where supported. Measure accepted/held value, return and loss exposure,
+funds-availability delay, review workload, and legitimate-customer impact.

package/skills/risk-compliance/fraud-detection/references/contexts/payout.md

@@ -0,0 +1,34 @@
+# Context: payout
+
+Score one payout transaction at its declared request, approval, or release
+point. Beneficiary setup is context; completion, return, and investigation are
+later lifecycle evidence, not additional scored copies.
+
+## Features
+
+For Step 4 feature engineering and Step 9 review, read
+[collection and payout features](../collection-payout-features.md). First-class
+entities include the balance-owning ledger account, inbound payer or funding
+account, and outbound beneficiary and beneficiary account. Enrichment may include
+point-in-time available receipt lots, ledger balance, currency, status and
+reservation lifecycle, event order, and role-link confidence; use only available
+sources.
+
+Read [entities](../entities.md) and [enrichment](../enrichment.md) for company,
+person, role-specific address and composite bank-account definitions, plus phone
+country/area, bank-account platform/PSP/holder classifications, and supported
+ID-document location. Keep sender/beneficiary roles and uncertain links explicit.
+
+Beneficiary novelty and sharing, payout velocity and amount, balance-drain ratio,
+time from collection to payout, account age, KYC state, device/account links,
+fan-out, counterparty concentration, prior returns, and point-in-time graph risk.
+
+Do not use later payout completion, return, recall, restriction, or investigation
+as a pre-release feature.
+
+## Actions and impact
+
+Actions: approve, verify, review, delay, hold, reject, restrict account, or
+monitor where policy permits. Measure held/reviewed count and value, payout
+completion, release delay, review workload, legitimate-customer intervention,
+exposure, and confirmed value captured.

package/skills/risk-compliance/fraud-detection/references/enrichment.md

@@ -0,0 +1,74 @@
+# Optional enrichment
+
+Use only data and versions actually available at the transaction decision. Record
+source, lookup key, as-of time, coverage, unknown values and normalization. A later
+lookup can support retrospective review but is not a causal real-time feature.
+
+- Inventory existing attributes before deriving missing ones. BIN can supply
+  `bin_country`, issuer and card type from an identified reference table or
+  lookup. Do not require a service integration now; a future BIN service is an
+  optional adapter. These are lookup attributes, not proof of customer location, identity
+  or intent. Handle missing, stale and ambiguous mappings explicitly.
+- IP geolocation can derive `ip_country`, `ip_state`/region and `ip_city` from
+  an available IP and point-in-time database. VPNs, proxies, shared networks and database error limit
+  its interpretation. Unknown geography is not a mismatch.
+- Preserve original amount and currency. For cross-currency comparison declare the
+  common currency, FX source, rate and as-of time available at decision, plus the
+  conversion convention. Missing currency or rate means the converted amount is
+  unknown; do not invent a local currency or mix currencies in a sum.
+
+## Collection and payout enrichment
+
+Apply these only where the source fields and jurisdiction support them. Read
+[entity definitions](entities.md) before resolving names or ownership. Missing
+lookups block the affected feature, not other rapid rule discovery.
+
+### Phone geography
+
+Derive `phone_country` and `phone_area` from a documented numbering-plan source
+and a reliably normalized phone number. Record number type and portability
+limits where supported. Area may be unavailable for mobile or non-geographic
+numbers. Numbering-plan country/area is not the person's current location,
+residence, nationality, or proof of a country mismatch's cause.
+
+### Bank-account classification
+
+Resolve using account name, account number and institution with evidence, not
+name substrings alone. Record the classified object (account holder, institution,
+platform association or PSP relationship) so one flag does not imply another.
+
+| Attribute | Meaning and limits |
+|---|---|
+| `is_platform` | Account is associated with an identified commerce/platform role, for example Amazon, under a stated relationship. Does not imply platform ownership. |
+| `is_psp` | Account is associated with an identified payment-service provider, for example PingPong or Airwallex, under a stated relationship. Does not identify the ultimate merchant/customer. |
+| `holder_type` | `corporate`, `non_corporate`, or `unknown`, supported by holder/legal-entity evidence. Non-corporate does not mean fraudulent. |
+| `is_corporate` / `is_non_corporate` | Optional nullable flags derived from the same holder classification. Unknown maps to null for both, not false; contradictory evidence remains unresolved. |
+
+Platform and PSP flags are independent of holder type and can overlap. Set false
+only where evidence supports a negative classification; absence from a reference
+list is unknown unless that list's coverage justifies a negative. Example names
+illustrate categories, not hard-coded watchlists or automatic matches.
+Record source, evidence, lookup version, effective/available time, confidence,
+and unresolved classifications. Neither PSP/platform association nor corporate
+status alone is a fraud diagnosis or verified account ownership.
+
+### ID-card geography
+
+For supported jurisdiction/document types, derive `id_document_location` and its
+administrative level from an authorized, versioned reference. Record whether the
+value represents an encoded administrative origin, registration, or issuance
+location according to that document's actual rules. Do not assume every ID has
+an embedded location, decode unsupported documents, or equate that location with
+current residence. Handle historical administrative boundaries and invalid IDs
+explicitly. Retain only necessary derived fields; do not expose full ID numbers
+in feature reports or lookup logs.
+
+## Encoding and mismatch
+
+Frequency encoding counts how often a known attribute value appears in eligible
+history, optionally including the current transaction for transaction velocity.
+Mismatch compares two explicitly named comparable attributes, such as known BIN
+country and known IP country. Return unknown if either side is missing; a mismatch
+is a hypothesis, not a fraud diagnosis. An encoding based on outcomes must obey
+label availability and maturity rules. Read [feature engineering](feature-engineering.md)
+and [feature SQL](feature-sql.md) for encoding definitions and examples.

package/skills/risk-compliance/fraud-detection/references/entities.md

@@ -0,0 +1,48 @@
+# Entity definitions and linkage
+
+Normalize consistently before matching; retain original values under appropriate
+access controls. Empty, malformed or unavailable identifiers become null, not a
+shared identity. Null keys never form a pooled entity or count as a distinct value.
+Record normalization version, source, availability and collisions. Do not generate
+an identifier or recover sensitive values that the source did not provide.
+
+| Entity | Meaning and normalization | Limits |
+|---|---|---|
+| `pan` | Payment account number or stable token for the same instrument. Remove formatting only where permitted; use a consistent secure token. | Masked PANs collide; token scopes can differ. A card may have several users. Protect full PAN under applicable controls. |
+| `email` | Email address; trim whitespace and normalize domain case. Apply local-part case or alias rules only if justified by the provider and source. | Shared mailboxes and aliases can join or split people. |
+| `phone` | Telephone number; normalize to international form only with a reliable country context. | Numbers are shared, recycled or changed; do not invent a country code. |
+| `address` | Registered, operating, residential, billing, shipping or another explicit address role; normalize components with locale-aware rules. | Shared premises and incomplete addresses are weak links. Keep roles separate; registered and operating addresses need not match. |
+| `company` | Legal or business entity; record jurisdiction, registration identifier where available, legal name and aliases. | A name match alone is not one company; distinguish legal entity, trading brand and platform. |
+| `person` | Natural person with explicit roles: account holder, beneficial owner, payer, beneficiary or representative. Use a lawful stable identifier where available. | Names are not unique; name similarity, shared contact details or an address do not establish identity. |
+| `bank_account` | Composite account name + account number + institution; preserve and normalize all three, including institution/branch/routing scope where needed. | Same numbers at different institutions are different accounts. Name variants are not automatically new accounts; masked numbers and missing components weaken matching. |
+| `ip` | Parsed IPv4 or IPv6 address in canonical form; preserve version. | NAT, proxies, VPNs and mobile networks share or change addresses. |
+| `device_fingerprint` | Source-issued fingerprint under a known version and scope. | Fingerprints can collide, reset, be shared or be unavailable; they are not verified people. |
+
+An exact normalized match is a deterministic match of an attribute, not proof of
+one customer, account, intent or fraud. Probabilistic links need stated evidence
+and uncertainty. Declare the chosen IP source (for example, trusted client IP
+rather than an untrusted forwarded header). Keep name roles, such as cardholder,
+account holder, billing recipient, or shipping recipient, separate and normalize
+consistently when counting distinct names.
+
+## Collection and payout relationships
+
+Represent `person -> company`, `person/company -> bank_account`, and
+`person/company -> address` as typed, sourced relationships, not inferred ownership.
+Record role, evidence, confidence, and when each relationship became known.
+A counterparty is a transaction role, not a new entity type: specify whether it
+is a person, company, bank account, platform, or PSP. Do not mix those grains in
+one distinct-counterparty count.
+
+Keep the balance-owning internal ledger account separate from an external
+`bank_account`. Virtual accounts, pooled accounts, and underlying settlement
+accounts need explicit links; an account number alone does not reveal the
+ultimate customer or beneficial owner. Preserve raw evidence under access
+controls, but use safe identifiers in reports and examples.
+
+Prefer supplied stable account IDs backed by the composite components. Track
+name variants separately; do not split a known account solely on spelling or
+merge accounts solely on a name. If institution or number is missing/ambiguous,
+mark linkage confidence or omit features requiring a reliable account identity.
+An ID-card reference identifies a document under a jurisdiction and document
+type; it is not by itself verified person identity or a public report field.