@1aboveio/skills 0.19.2 → 0.20.1

package/skills/payment/tld-detection/references/report-template.md

@@ -0,0 +1,169 @@
+# Report template
+
+Save:
+
+```text
+reports/tld-detection/<scope>_clusters.md
+reports/tld-detection/<scope>_clusters.zh.md
+reports/tld-detection/<scope>_clusters.zh.html
+reports/tld-detection/<scope>_methodology.md
+reports/tld-detection/<scope>_methodology.zh.md
+reports/tld-detection/<scope>_methodology.zh.html
+```
+
+HTML is preferred when there are charts (Chart.js bars). No Markdown bold in report body.
+The cluster report and methodology document must link to each other. After
+writing, grep banned strings in [terminology.md](terminology.md).
+
+English Markdown headings on the left; Chinese HTML / `.zh.md` on the right.
+
+```markdown
+# Potential TLD currency-amount pairs — <window>
+# 潜在 TLD 币种金额对 — <window>
+
+## TLD Risk Assessment                  # TLD 风险评估
+[Separate methodology link]             # [独立方法文档链接]
+## High-Risk Clusters                   # 高风险 Cluster
+## TLD Risk Exposure                    # TLD 风险敞口
+### By risk tier and descriptor          # 按风险等级及 Descriptor
+### Overall exposure                     # 整体风险敞口
+## All Identified Currency-Amount Pairs # 全部识别出的币种金额对
+### Currency-Amount Pair C1             # 币种金额对 C1
+#### Definition                         # 定义
+#### Characteristics                    # 特征
+## Verdict                              # 结论
+```
+
+The separate methodology document uses this structure:
+
+```markdown
+# TLD currency-amount-pair detection methodology — <scope/window>
+# TLD 币种金额对识别方法 — <范围/时段>
+
+## Universe and cleaning                # 分析总体与清洗
+## Descriptor partition logic           # Descriptor 分区逻辑
+## Currency-amount-pair logic           # 币种金额对逻辑
+## Baseline and audit details           # 基线与审计明细
+```
+
+## Chapter requirements
+
+### TLD Risk Assessment / TLD 风险评估
+
+Answer these three questions directly and in this order:
+
+1. What is the highest investigation-priority risk tier found?
+2. Which clusters are High, Medium, and Low risk; what characteristics support
+   each tier; and what share do they represent inside their descriptors?
+3. What is the exact-member exposure by risk tier, descriptor, and across all
+   authorization attempts?
+
+Risk tiers prioritize investigation and do not confirm TLD. List results in
+`High → Medium → Low` order, then by evidence strength and attempts inside each
+tier. The ≤3-sentence conclusion lives in Verdict, not here.
+
+### Separate methodology / 独立方法文档
+
+Document the logic and values actually used for this run, not generic skill
+instructions. State the authorization grain and window; give the census from
+[clean.md](clean.md), BIN-country and currency mix, and portfolio
+constants.
+
+Partition logic defines the normalized descriptor key, normalization rules,
+the unknown bucket, descriptor counts, and shares. Currency-amount-pair
+logic explains within-descriptor ranking, adjacent currency-specific
+absolute residual caps, sensitivity evidence, the multi-anchor support floor,
+exact final membership, and the ≥100-attempt threshold. BIN country is
+post-formation attribution, not a partition or membership key.
+
+The ranking table contains partition, currency, exact amount, attempts,
+share of the descriptor, share of all authorization attempts, and selected
+cluster id or `baseline`. Chart attempt bars within the most relevant
+descriptors, sorted by count descending.
+
+Audit details contain drop counts, currency caps, sensitivity results,
+multi-anchor support floor, ≥100 cluster attempts, min-n for
+cluster-versus-baseline rate ranking (not the definition anchor table),
+descriptor-local high-count rule, baseline definitions, below-threshold
+families, risk-tier rules, all run-specific materiality thresholds, and files
+used. No skill name in the HTML footer; filenames only.
+
+### High-risk clusters / 高风险 Cluster
+
+Include High-risk clusters only. For each, show descriptor, representative
+anchors, attempts, share of its descriptor, share of all authorization attempts,
+risk basis, standout evidence, and the clearest independent corroborating
+characteristic. Do not describe the tier as confirmation that TLD occurred.
+
+### Risk exposure / 风险敞口
+
+Exposure is the disjoint exact-member attempt count of all identified clusters,
+separated into High, Medium, and Low risk. The by-tier-and-descriptor table
+reports descriptor attempts, cluster attempts, share of descriptor, share of
+all authorization attempts, risk tier, and cluster IDs. The overall view has
+one row per risk tier plus `Baseline` / `基线`, and the rows conserve all
+authorization attempts. Never combine the three tiers into a single “confirmed”
+or “supported TLD” impact figure.
+
+### Currency-amount-pair analysis / 全部识别出的币种金额对
+
+One subsection per identified currency-amount pair. Definition contains only
+Descriptor, seed, representative anchors, and cluster attempts. Express
+anchors as `USD 11.7 → USD 23.39* → USD 46.78`. Follow that with an anchor
+table whose columns are anchor, attempts, authorization success rate, and
+suspected fraud as share of attempts. Always compute both rates for every
+theoretical level from that level's exact member attempts, including levels
+with fewer than the contrast min-n (default 30). Do not write `n/a` on this
+table because the rung is small. For a level containing multiple nearby exact
+values, display its highest-count amount with `*`; the table totals attempts
+and rates across that level and explains `*`.
+
+Show the risk tier and concise basis immediately below the cluster heading.
+Characteristics contain Descriptor, descriptor total attempts, cluster
+attempts, cluster share of descriptor, and MCC. Then compare Cluster with the
+baseline formed by removing that cluster from the same descriptor. The
+comparison contains authorization success rate, suspected fraud as a share of
+attempts, Top 3 issuing banks, and Top 3 BIN countries.
+
+For every Top 3 cluster BIN country, add a table with country, cluster attempts,
+share of cluster, total attempts in the same descriptor-country slice, and
+cluster coverage of that slice. Mark exact 100% single-country composition as a
+standout. Treat `Mixed` as neutral. Do not assign a threshold or risk points to
+country-slice coverage, and do not promote any composition below 100% merely
+because it is high.
+
+Follow the tables with transaction-date and transaction-time charts comparing
+the cluster with the same-descriptor baseline. These are characteristics, not
+cluster membership conditions.
+
+When clustering finds no qualifying family, omit currency-amount-pair subsections,
+publish the ranking and below-threshold candidates in the methodology
+document, show zero identified-cluster exposure, and still write Verdict.
+
+### Verdict / 结论
+
+[decision.md](decision.md). **≤3 sentences** for the whole book, then an
+optional one-row-per-cluster table (risk tier + short basis). No extra
+bullets under this heading.
+
+## Charts
+
+Place each currency-amount pair's charts inside its analysis after the
+characteristics tables.
+
+| View | Mark |
+|---|---|
+| Representative-anchor attempts | Horizontal bar |
+| Cluster vs same-descriptor baseline rates | Grouped bar |
+| Transaction date trend, cluster vs same-descriptor baseline | Two-series line, each series normalized to its own attempt total |
+| Transaction time by BIN-country local hour, cluster vs same-descriptor baseline | Two-series line, each series normalized to its own attempt total |
+
+Label axes with the full metric (`授权笔数`, `比率 %`, `每日授权占比 %`,
+`每小时授权占比 %`). State that transaction time uses the BIN country's local
+hour and UTC when the BIN country has no configured timezone.
+
+## What the report is not
+
+Not a payment overview (`payment-analysis`). Not a holdout rule pack
+(`fraud-analysis`). Not a recommendation to file a SAR or to terminate a
+merchant.

package/skills/payment/tld-detection/references/terminology.md

@@ -0,0 +1,69 @@
+# Terminology
+
+Use these terms in TLD reports. Read before writing. After writing, run
+the proofread in `SKILL.md`.
+
+TLD in this skill is **transaction laundering**. Spell it out on first
+use. It is not a top-level domain.
+
+## Canonical glossary
+
+| English | Chinese | Do not write |
+|---|---|---|
+| TLD (transaction laundering) | 交易清洗 / TLD | 把 TLD 写成域名；洗钱结案 |
+| potential TLD currency-amount pair | 潜在 TLD 币种金额对 | 已确认 TLD；TLD 商户 |
+| cluster (report section) | 币种金额对 | 客户簇；客群；分群结果 |
+| anchor detection | 锚点识别 | 客户聚类（对业务读者） |
+| currency-amount-pair | 币种金额对 | 金额币种对；金额对；price point（作指标名时） |
+| descriptor partition | descriptor 分区 | 客群；BIN 国家分区 |
+| BIN-country attribution component | BIN 国家归因组件 | 客户国家；成员分区 |
+| geometric anchor family | 币种金额对 | 阶梯（业务报告中）；价格带；SKU |
+| stuffing | 掺量 | 注水（可括注一次）；corridor |
+| MCC miscoding | MCC 错配 | 改 MCC；纠正 MCC |
+| descriptor | descriptor / 账单描述 | 商户名（指 descriptor 时） |
+| baseline | 基线 | 对照组（可括注）；everything else |
+| all authorization attempts | 全部授权尝试 | U（业务报告中）；原始全量 |
+| US-BIN | US BIN / 美国发卡 | 美国交易（指卡BIN时） |
+| attempt | 授权尝试 | 交易（指授权行时） |
+| approval | 授权成功 | 批准 |
+| auth rate | 授权成功率 | 转化率 |
+| suspected fraud | 疑似欺诈 | 已确认欺诈；正文里写 D102（表内代码可留） |
+| BIN country / issuer country | 发卡行国家 / BIN 国家 | 客户国家；收货国；发卡国 |
+| cluster composition by BIN country | BIN 国家占 Cluster | 客户国家占比 |
+| descriptor-country slice coverage | Cluster 占 Descriptor 对应 BIN 国家 | BIN 国家风险率；国家命中率 |
+| exact single-country standout | 100% 单一 BIN 国家 standout | 高国家占比；接近 100% |
+| BIN-country local hour | BIN 国家当地小时 | 客户所在地时间；统一美国东部时间 |
+| this analysis window | 当前分析时段内 | 本窗口 |
+| MCC vs descriptor | MCC 与 descriptor 合理性 | 纠正 MCC；改 MCC |
+| verdict | 结论 | 长文综述（作结论部分时） |
+| High / Medium / Low risk | 高风险 / 中风险 / 低风险 | Supported；Weak；Ladder only；已确认 TLD |
+| risk exposure | 风险敞口 | 已确认 TLD 影响；定罪金额 |
+
+Keep proper nouns: Visa, MasterCard, BIN, IIN, MCC, MID, Worldpay,
+Pazien, Order ID, descriptor. Tables may show response codes; prose uses
+疑似欺诈 / suspected fraud.
+
+## Axis and UI
+
+- Amount axes name the **original** currency of that cluster
+  (`授权尝试金额 USD`, `授权尝试金额 EUR`). Do not mix currencies on one
+  axis.
+- Date charts use each series' share of attempts by UTC transaction date.
+- Time charts use each BIN country's local hour, falling back to UTC when no
+  timezone is configured. Normalize Cluster and Baseline independently.
+- HTML footer: data-source filenames only. No skill name.
+
+## Banned strings (grep after writing)
+
+Chinese: `走廊`, `杠杆`, `转化率`, `赋能`, `抓手`, `闭环`, `打法`,
+`本窗口`, `已确认 TLD`, `已确认交易清洗`, `洗钱`, `发卡国`, `客群运营`,
+`客户簇`, `金额币种对`
+
+English: `confirmed laundering`, `confirmed TLD`, `money laundering`,
+`SAR`, `file a SAR`, `top-level domain`, `customer country`,
+`conversion rate` (when meaning auth rate), `corridor`, `price band`
+(as the cluster name)
+
+`洗钱` is banned as a finding. If a source document uses the legal term,
+quote it in supporting evidence and keep the report on potential TLD
+currency-amount pairs.

package/skills/payment/tld-detection/references/workflow.md

@@ -0,0 +1,78 @@
+# Workflow detail
+
+SKILL.md is the index. This file is the procedure those steps run.
+
+## Input
+
+Typical file: `Authorizations_*.csv`. Grain: **one authorization attempt**.
+
+Amount, currency, and descriptor columns are required. BIN/issuer country,
+issuing bank, MCC, and response are expected for characteristics; a missing
+optional column is captioned. Missing descriptor values enter an explicit
+partition bucket; missing BIN-country values enter a reporting bucket after
+membership is frozen. Do not drop those rows.
+
+Settlements and chargebacks are not the clustering universe. Do not join
+them into `U`. If only settlements exist, stop and say the clustering
+grain is auth attempts.
+
+## Column aliases
+
+Use the first present name. Record the alias actually used.
+
+| Role | Common names |
+|---|---|
+| Time | `Timestamp`, `Auth timestamp`, `Transaction date` |
+| Amount | `Amount`, `Transaction amount`, `Requested amount` |
+| Currency | `Currency`, `Transaction currency`, `Auth currency` |
+| BIN / issuer country | `BIN country`, `IIN country`, `Issuer country`, `Card country` |
+| Issuing bank | `Issuing bank`, `Issuer`, `Issuer name`, `Bank name` |
+| Descriptor | `Billing descriptor`, `Descriptor`, `Soft descriptor`, `Submerchant`, `DBA` |
+| MCC | `MCC`, `Merchant category code` |
+| Response | `Response code`, `Response message`, `Auth response` |
+| Identity | `Order ID`, `Transaction ID`, `Auth ID` |
+| Card | `IIN`, `BIN`, `Payment method`, `Card type`, masked `Account` |
+
+Portfolio constants (MID, acquirer, entry method) are recorded once. They
+are not partition or clustering keys.
+
+## Window
+
+Default: min→max of the time field on the **cleaned** universe. If the user
+names a week or month, cut there and state it.
+
+## Response classes
+
+Recompute from the file. Pazien-style defaults when those codes exist:
+
+| Class | Typical |
+|---|---|
+| Approval | A001 / message contains approval |
+| Suspected fraud | D102 / message contains suspected fraud |
+| Other decline | remaining non-approvals |
+
+Suspected-fraud decline ≠ confirmed fraud loss. Do not treat D102 as a
+positive label for `fraud-analysis`.
+
+## What this skill is looking for
+
+Transaction laundering in this book usually shows up as:
+
+1. **MCC miscoding** — different kinds of goods mixed under one “normal” MCC
+2. **Descriptor mixing** — several customer types share a billing name, or
+   one TLD customer is split across several descriptors
+3. **Stuffing / 掺量** — a geometric amount ladder riding the same MCC as
+   legitimate traffic
+
+Descriptor defines the initial partition, while BIN country and MCC do not.
+Geometrically related currency-amount anchors inside each descriptor define
+membership. BIN country and issuing bank are reported only after membership
+is frozen.
+
+## Order that must not move
+
+Clean → descriptor partition → currency-amount pairs → same-descriptor baseline → decide → report.
+
+Comparison features must not create a cluster that amount detection did not
+find. Decision does not add evidence; it only writes the ≤3-sentence
+conclusion.