@1aboveio/skills 1.0.10 → 1.0.12

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

@@ -1,27 +0,0 @@
-# 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.
-
-## 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-analysis/references/contexts/card-payment.md

@@ -1,30 +0,0 @@
-# Context: card payment
-
-Typical grains are authorization attempt, payment attempt, clearing event, or
-dispute. Default decision point for preventive rules is pre-authorization.
-
-## 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.
-
-Fit BIN, country, merchant, and other rate lists on train only. 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
-
-- Current CVV/AVS/auth response/3DS result respects decision timing.
-- BIN lists are train-fit; issuer names are operable only if available live.
-- 3DS and authorization denominators are explicit.

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

@@ -1,20 +0,0 @@
-# Context: payment collection
-
-Typical grains are collection attempt, receipt, settlement, return, or linked
-collection-to-outflow sequence. State whether funds are card, bank debit,
-transfer, cash-equivalent, or mixed because timing and reversibility differ.
-
-## Features
-
-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-analysis/references/contexts/payout.md

@@ -1,20 +0,0 @@
-# Context: payout
-
-Typical grains are beneficiary setup, payout request, approval, release,
-completion, return, or investigation. State the rule's exact decision point.
-
-## Features
-
-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-analysis/references/workflow.md

@@ -1,175 +0,0 @@
-# Fraud-analysis workflow (steps 0–9)
-
-Called from [SKILL.md](../SKILL.md). Paths below are relative to the skill root.
-
-## 0 — Pre-flight
-
-Inspect the input, requested target, and label provenance before planning a
-supervised analysis. Record:
-
-```yaml
-label_provenance: file-column | user-defined | absent
-positive_definition: ""
-negative_definition: ""
-unlabeled_definition: ""
-preflight_status: pass | needs-user-input | descriptive-only | blocked
-```
-
-- Confirm the file is readable and identify its row grain, candidate time field,
-  outcome/label fields, and requested positive definition.
-- When the positive label comes from an existing row-level outcome column, map
-  its positive value(s). Assume the rest of the mature analysis population is
-  negative, except explicit missing, pending, unknown, or unlabeled states.
-  State this assumption and show the observed values to the user when ambiguous.
-- When the user defines the positive label as a condition or derived rule,
-  require the user to define the negative condition during pre-flight. Do not
-  infer `NOT positive` as negative. Ask one focused clarification and set status
-  to `needs-user-input` until answered.
-- Rows matching neither class, both classes, explicit unknown states, or an
-  immature outcome window are unlabeled.
-- If no usable positive and negative definitions exist, offer descriptive
-  segmentation without precision/recall, or block supervised analysis.
-
-Do not proceed to the supervised workflow until pre-flight passes. A
-`descriptive-only` analysis may select a profile and explore segments, but it
-must not compute precision, recall, lift, or supervised strategy performance.
-Profile clarification may be grouped into the same user question when both
-label and attribution inputs are missing.
-
-## 1 — Select analysis profile
-
-Read [taxonomy.md](taxonomy.md). Record:
-
-```yaml
-archetype: third-party-fraud | first-party-fraud | authorized-payment-scam | unclassified
-customer_role: victim | perpetrator | knowing-participant | facilitator | unknown
-customer_consent: present | absent | disputed | unknown
-technical_authentication: passed | failed | not-applicable | unknown
-mechanisms: []
-contexts: []
-subtype: null
-attribution_confidence: confirmed | probable | proxy | unknown
-event_grain: ""
-decision_point: ""
-```
-
-- Select exactly one primary archetype. Select one or more mechanisms and
-  contexts when the data supports them.
-- Customer consent and technical authentication are separate facts. Passed
-  login, MFA, or session checks do not prove genuine-customer consent.
-- `APP scam` is a subtype of `authorized-payment-scam` in a `bank-transfer`
-  context; it is not a synonym for first-party fraud.
-- If victimization versus knowing participation is unresolved, use
-  `unclassified`. Do not silently force attribution.
-- If multiple archetypes are confirmed, run separate labels, rules, metrics,
-  and impact sections. Never blend them into one positive class.
-
-Read the selected archetype, mechanism, and context references before Step 2.
-
-## 2 — Formalize label
-
-- One primary label per archetype analysis. Confirmed outcomes are ground truth;
-  proxies must be identified as proxies.
-- Carry forward the pre-flight provenance and class definitions; do not discover
-  the negative class here.
-- Validate the pre-flight mapping against observed rows and record the resulting
-  positive, negative, and unlabeled counts.
-- If the mapping is incomplete or contradictory, return to pre-flight with
-  `needs-user-input`; do not ask for or invent a negative class in this step.
-- Derive labels only from supplied data and documented business meaning. Positive
-  and negative conditions must be disjoint. Rows matching neither, both, or an
-  immature/pending state are unlabeled and excluded from supervised metrics.
-- Record positive definition/count, negative definition/count, unlabeled
-  definition/count, base rate among labeled rows, maturity window, exclusions,
-  and attribution confidence.
-- Exclude the label, synonyms, investigations, recalls, disputes, or other later
-  outcomes from features when unavailable at the selected decision point.
-- For delayed outcomes, ensure enough observation time or mark recent rows as
-  immature rather than negative.
-- Do not continue to precision, recall, or supervised rule scoring until both
-  positive and negative classes are defined.
-
-## 3 — Freeze temporal validation
-
-- Freeze the cut before feature work. Train is earlier; holdout is later.
-- Do not random-shuffle rows or use random k-fold as headline validation.
-- History and graph snapshots contain prior events only.
-- No time column means full-sample descriptive analysis; mark metrics
-  **unvalidated**.
-
-## 4 — Engineer candidates
-
-Read [feature-engineering.md](feature-engineering.md) and all selected
-profile packs.
-
-- Declare event grain and decision point before assessing columns.
-- Classify fields as allowed now, excluded for zero variance, excluded for
-  timing, excluded for leakage, or context-only.
-- Build thresholds, rate lists, graph lists, and watchlists on train only.
-- Prefer interpretable conditions with explicit units and windows.
-- Do not invent columns, identity links, consent, intent, or actor attribution.
-
-## 5 — Select shortlist
-
-Use train only: lift, support, stability, operability, and meaningful
-interactions. Keep tiny or attribution-uncertain spikes for monitoring.
-
-## 6 — Score rules
-
-State explicit conditions, event grain, units, windows, and decision point.
-Headline holdout metrics use this order:
-
-**occurrence → precision → recall**
-
-Train metrics are debugging evidence only. If outcomes are value-bearing, also
-measure captured positive amount without replacing count-based metrics.
-
-## 7 — Map actions and packages
-
-Use actions from the selected context packs; there is no universal 3DS action.
-
-| Metric and evidence profile | Shared guidance |
-|---|---|
-| High precision, stable, severe impact | Consider the context's strongest preventive action |
-| Higher recall, moderate precision | Add verification, review, warning, hold, or friction |
-| Weak, unstable, small-N, uncertain attribution | Monitor or investigate |
-
-- Legal, regulatory, policy, and operational authority constrain account holds,
-  freezes, rejects, beneficiary blocks, and reporting.
-- Keep individual rules separate from multi-rule **strategy packages**.
-- Freeze default and comparison packages before report writing.
-- For each package compute triggered count/rate and amount/share, then precision
-  and recall, plus the context-specific customer, operations, conversion, delay,
-  and loss measures required by its pack.
-
-## 8 — Write business report
-
-Read [report-template.md](report-template.md),
-[terminology.md](terminology.md), and selected profile packs.
-
-Use reader order:
-
-执行摘要 → 抽样、分析画像与标签 → 规则发现 → 策略整体影响 → 特征 → 附录
-
-- Include the analysis profile and actor attribution near the start.
-- Report only domain-appropriate actions, denominators, and impact KPIs.
-- Strategy impact always includes count/rate and amount/share, then precision
-  and recall. Add only the selected contexts' required impact measures.
-- Do not present scenario estimates or proxy-label value as measured loss saved.
-- Save to a path such as `reports/fraud-analysis/<scope>.md`.
-- Before finishing: grep the report for banned strings in
-  [terminology.md](terminology.md) and fix language only (not numbers,
-  BIN lists, or thresholds).
-
-## 9 — Independent review
-
-Read [review-checklist.md](review-checklist.md) and selected packs.
-
-- Review the common method and presentation contract.
-- Apply checks from every selected archetype, mechanism, and context pack.
-- Auto-fix mechanical issues only. Do not silently change attribution, label,
-  customer role, or action severity.
-- Prefer a fresh independent reviewer. If unavailable, use a fresh same-session
-  checklist and disclose that only in the chat delivery note.
-- Deliver the business report plus a short note with verdict, fixes, and open
-  judgment issues. Keep review process details out of the report.

package/skills/risk-compliance/tld-detection/references/chinese-polish.md

@@ -1,55 +0,0 @@
-# Chinese polish guardrails
-
-The final step runs `polish-cn` (`{polish-cn baseDir}/SKILL.md`) after `editorial-review`. This
-file holds what `polish-cn` needs from this skill: what to cover, the protected terms, and the
-guardrails to send with the brief.
-
-## Cover
-
-Every Chinese deliverable: the main report, complete evidence, methodology, any separate FX
-sensitivity reports, chart captions, expandable-view notes, and the Chinese chat handoff. Extract
-each `.zh.md`; when a script renders the files, polish its narrative source and re-render instead.
-Never send raw authorization records, card identifiers or credentials.
-
-## Protected terms
-
-Pass these with `--protect-file`, plus every term in [terminology.md](terminology.md):
-
-```text
-高风险
-中风险
-低风险
-直接充值模式
-换汇充值模式
-电商模式
-其他模式
-推断充值币种
-扣款币种
-授权拒绝
-潜在 TLD
-```
-
-Cluster ids (`C1`, `FXC1`), descriptors, amounts and currencies are protected by the script.
-
-## Guardrails
-
-Send with the brief, plus [decision.md](decision.md) for business-reader terms:
-
-> 这是潜在交易洗钱（TLD）调查报告。保持三节主报告结构、风险等级顺序、证据—假设—关联关系的先后顺序。
-> 潜在 TLD 不是已确认的洗钱；收款模式名称是推断，不是已验证的经营类型；定额是补充特征。
-> 推断充值币种与扣款币种不得混用；原币结果 `C*` 与汇率敏感性结果 `FXC*` 分开表述，保留全部汇率集中度说明。
-> 结论摘要不超过三个短句，每句不超过 80 个字，数字事实合计不超过两个（日期区间和编号不计），
-> 并保留"审查谁、为什么、未知什么、下一步查什么"。授权拒绝不是拒付。
-> 未识别到聚类不等于商户风险低。不得补回已删除的诊断表或结尾 Verdict。
-
-## Accept
-
-- Each protected value stays attached to the same descriptor, period, denominator and metric. A
-  matching set of numbers is not enough if their labels moved.
-- Unspecified periods, denominators and reasons stay unknown. Other-pattern uncertainty never
-  becomes a failed test, missing fields or low risk.
-- Recheck the summary's sentence and number limits, the banned strings in
-  [terminology.md](terminology.md), paired links, and Markdown / HTML agreement, including visible
-  chart labels, without changing chart data.
-- Write the `polish-cn` record (model, fallback reason, files covered) into the run's task record,
-  never into the report's HTML footer.

package/skills/risk-compliance/tld-detection/references/clustering.md

@@ -1,235 +0,0 @@
-# Currency-amount-pair clustering
-
-Goal: partition the cleaned universe by descriptor, find stuffing (掺量)
-as **approximate geometric ladders** inside each descriptor, then decompose
-each qualifying ladder into BIN-country attribution components and contrast
-it against the remainder.
-
-## Payment patterns before clustering
-
-Run [streams.md](streams.md) before ranking pairs, but keep the entire frozen
-descriptor as the canonical partition for rung pools, ladders, exact members,
-and baseline. Inferred payment patterns provide context only; they never filter
-or split this population. Date-varying converted presets can fragment exact
-anchors and are reported separately as pattern hypotheses. BIN-country groups
-used during inference are not ladder partitions or membership keys.
-
-## Descriptor partition
-
-Partition key = `normalized descriptor`.
-
-- Trim, case-fold, and collapse repeated whitespace. Preserve the most
-  frequent source spelling for display.
-- Do not fuzzy-match or strip dynamic suffixes unless the extract documents
-  their semantics.
-- Use `UNKNOWN_DESCRIPTOR` for missing values; do not drop them.
-
-Freeze descriptor assignment before ranking amounts. Report each descriptor's
-attempt count and share of `U`. A ladder belongs to exactly one descriptor;
-the same exact currency-amount-pair may legitimately belong to ladders in
-different descriptors.
-
-BIN country is **not** a partition or membership key. Normalize it after
-ladder formation and report its attempt counts, shares, auth rates, suspected-
-fraud rates, and local-hour shapes as attribution components.
-
-## Currency-amount-pair
-
-Key = (`currency`, `amount`) on the original (not FX-converted) amount. This is
-the canonical key. A requested BIN-country base-currency analysis is a separate
-sensitivity under [fx-conversion.md](fx-conversion.md), never a replacement for
-or input to canonical membership.
-
-Count = authorization **attempts** in the current partition. Rank
-descending by count. Ties: smaller amount first, then currency code.
-
-## High-count set and rung pool
-
-Work **per partition, then per currency**. In the table below, `|P|` is
-the authorization-attempt count of the current partition.
-
-| Set | Membership |
-|---|---|
-| High-count (seeds) | union of (a) pairs with count ≥ `max(30, 0.5% of \|P\|)` (b) the partition top 25 pairs by count (c) per currency in the partition, the top 10 pairs with count ≥ 30 |
-| Rung pool | pairs with count ≥ `max(5, 0.1% of \|P\|)` |
-
-State the thresholds. Use the high-count set for ranking. Test every rung-pool
-pair as a possible seed for a three-level 2x relationship; otherwise a
-representative lower-volume path can be structurally impossible to discover.
-Extra levels may be quieter amounts in
-the rung pool, and (c) keeps a smaller currency visible inside the partition.
-
-If the rung pool has fewer than three pairs in every currency of a partition,
-that partition has no three-level ladder to test. Still publish its ranking
-table when it is among the largest partitions or has a below-threshold family.
-
-## Ladder detection
-
-Ladder detection has two separate phases. **Discovery** uses an adjacent,
-currency-specific absolute residual cap. **Membership and every downstream
-metric use the exact descriptor plus selected currency-amount-pairs only.**
-Never widen final membership to a numeric interval or another descriptor.
-
-### Adjacent absolute-residual rule
-
-For exact amounts `a < b` in one descriptor and currency, multiplier `m` has:
-
-```text
-residual = |b - a · m|
-```
-
-They are adjacent anchors only when `residual ≤ ε_currency`. Do not use one
-percentage tolerance across amounts: its absolute allowance grows with the
-amount and can merge materially different upper-rung prices.
-
-Configure and report one cap per currency represented in a partition's rung
-pool. For a two-decimal currency, test a sensitivity grid such as `0.02,
-0.05, 0.10, 0.15, 0.25` and retain the smallest operationally justified cap
-under which material paths are stable. Fail closed when a rung-pool currency
-has no cap; currencies below the rung-pool threshold need no cap.
-
-Use the bundled deterministic implementation after producing a cleaned
-authorization CSV:
-
-```bash
-python3 {baseDir}/scripts/detect_ladders.py cleaned-authorizations.csv \
-  --descriptor-column descriptor --bin-country-column bin_country \
-  --currency-column currency --amount-column amount \
-  --cap USD=0.15 --multi-anchor-min-attempts 24 \
-  --sensitivity-cap USD=0.02 --sensitivity-cap USD=0.05 \
-  --sensitivity-cap USD=0.10 --sensitivity-cap USD=0.15 \
-  --sensitivity-cap USD=0.25
-```
-
-The CLI does not clean or deduplicate the CSV; complete
-[clean.md](clean.md) first.
-
-### Family from a seed (up and down)
-
-Starting from every rung-pool seed, expand recursively upward and downward
-using only adjacent matches. A theoretical level may contain several exact
-anchors. Select the highest-count match as its primary anchor; retain an
-additional match only when that exact pair independently clears the stated
-portfolio support floor (default 24 attempts, corresponding to the Worldpay
-portfolio rung floor). Record that floor and test it separately for a new
-portfolio.
-
-Every retained key must be in the partition's rung pool and match an anchor
-in the adjacent level. The finite retained keys become the explicit anchor
-set. Tolerance never acts on transactions after selection: final membership
-is exact equality on (`descriptor`, `currency`, `amount`). BIN country is
-attached only after this membership is frozen.
-
-### Required 2x family
-
-A candidate family must use **`m = 2`** between every adjacent theoretical
-level and contain **at least three theoretical levels**. Example: 1x, 2x, 4x,
-8x around the seed, including downward (`19.99` can find `9.99` and `39.99`).
-There is no two-level exception, and relationships based on `m = 3`, `4`, `5`,
-`10`, or any other multiplier do not form clusters.
-
-For each seed, rank qualifying paths by: more theoretical levels; more exact-
-member attempts; then lower summed adjacent residual. The attempt threshold
-below independently determines whether the family becomes a reported cluster.
-
-### Minimum cluster size
-
-Sum attempts only over rows in the partition whose keys are the selected
-exact currency-amount-pairs. A family is a reported cluster only when that
-exact membership has **≥100 authorization attempts**. Keep smaller
-families in the run methodology document as `below threshold`; do not validate them or
-issue cluster verdicts for them. Their rows remain in canonical baseline
-`B` and descriptor remainder `B_D` unless selected exact keys are claimed
-by another reported ladder in the same descriptor.
-
-### Several groups
-
-Within each partition, process unused rung-pool seeds in descending attempt
-count. A currency-amount-pair joins **at most one** reported cluster in that
-partition — the first qualifying family that claims it. Below-threshold
-families do not reserve keys. Never let a claim in one partition reserve the
-same pair in another partition.
-
-Name clusters `C1`, `C2`, … by descending total attempts. For each, record
-the descriptor partition, seed, currency, multiplier, absolute cap, summed
-fit residual, theoretical levels, all exact anchors and counts, multi-anchor
-levels, total attempts, and post-formation BIN-country components.
-
-Ignore one-off round amounts (`100`, `1000`) unless they sit on a ladder.
-A popular SKU price is not a cluster by itself.
-
-### None found
-
-If no family qualifies in any partition, **do not invent clusters** from
-MCC or comparison features. Publish the partition and pair rankings, contrast
-the top pairs only as context if useful, and skip cluster verdicts.
-
-## Baseline
-
-For each cluster, **Baseline** means every authorization in the same descriptor
-after removing that cluster's exact member keys. Other identified
-currency-amount pairs remain in this baseline. This is the only comparison
-population used in cluster characteristics. If the cluster consumes the whole
-descriptor, report comparison values as `n/a`.
-
-For the overall impact table only, `Baseline` means rows in the cleaned universe
-that belong to no identified currency-amount pair. Keep this distinct from the
-per-cluster same-descriptor baseline.
-
-If two currencies each have a ladder, they are separate clusters. Do not
-merge across currencies.
-
-## Contrast vs baseline
-
-Same window and descriptor. Compare each cluster with its baseline on:
-
-| Metric | Formula |
-|---|---|
-| Authorization success rate | approvals / attempts |
-| Suspected fraud as share of attempts | suspected-fraud attempts / attempts |
-| Top 3 issuing banks | count and share of that series |
-| Top 3 BIN countries | count and share of that series |
-
-Separately report Descriptor, descriptor total attempts, cluster attempts,
-cluster share of descriptor, and MCC.
-
-Require a stated min-n before ranking a cluster-versus-baseline rate
-(default attempts ≥ 30). Below that, show the contrast rate as `n/a (n=…)`.
-The definition anchor table is not a ranking contrast: always compute
-authorization success rate and suspected-fraud share for every theoretical
-level from that level's exact member attempts, including n < min-n. Combined
-`*` levels use the combined attempts of the level. Do not write `n/a` on the
-anchor table because the rung is small.
-
-Use the contrast to assign investigation-priority risk under
-[decision.md](decision.md), not as a fraud label. Treat materially different
-authorization, suspected-fraud, issuing-bank, date, and local-hour behavior as
-independent characteristics under thresholds declared in the run methodology.
-
-For each Top 3 cluster BIN country, report both its share of the cluster and
-the cluster's share of all attempts in the same descriptor-country slice. In
-the canonical original-currency run only, an exact 100% single-country cluster
-is a standout. `Mixed` is neutral, and country-slice coverage is descriptive
-only: do not set a universal threshold or award risk points for values such as
-20% or 33.8%. In the FX sensitivity, even 100% concentration is descriptive,
-must be captioned as constructed by the target-currency mapping, and cannot
-raise the FX tier.
-
-## What not to do
-
-- Do not treat MCC as a partition or clustering key.
-- Do not discover ladders across descriptor boundaries.
-- Do not use BIN country as a ladder partition or membership key.
-- Do not k-means the amounts.
-- Do not convert to USD or another currency and use that result as the canonical ladder run. Keep any BIN-country base-currency detection in the separate FX sensitivity.
-- Do not search only upward from the busiest rung.
-- Do not use a percentage tolerance across amounts.
-- Do not turn stream inference into cluster membership: its relative tolerance is discovery in the wallet currency; canonical membership stays exact on original currency and amount.
-- Do not assign every amount inside an interval; select finite exact anchors first.
-- Do not retain a low-support additional anchor merely because it is near a primary anchor.
-- Do not report a cluster with fewer than three theoretical levels.
-- Do not use any adjacent-level multiplier other than 2x.
-- Do not report a cluster with fewer than 100 attempts.
-- Do not put the same pair in two clusters within one partition.
-- Do not merge matching amount fingerprints across descriptors.
-- Do not call the output a customer segment or a marketing cohort.