@1aboveio/skills 0.15.0 → 0.17.0

package/skills/payment/fraud-analysis/references/report-template.md

@@ -0,0 +1,190 @@
+# Business report contract
+
+Read this in Step 8 with the selected profile packs and
+[terminology.md](terminology.md). This file owns common reader order and metric
+presentation. Profile packs own domain-specific actions, sections, denominators,
+and impact measures.
+
+## Required chapter order
+
+1. 执行摘要
+2. 抽样、分析画像与标签定义
+3. 规则发现
+4. 策略整体影响
+5. 特征
+6. 附录
+
+Do not title chapters as analysis steps. Keep review details out of the report.
+
+## 1. 执行摘要
+
+Use no more than five top-level findings:
+
+1. Analysis profile, sample span, and positive-label baseline
+2. Adopted rule classes and domain-appropriate actions
+3. Adopted strategy package impact
+4. Material attribution or validation limitation, only when decision-critical
+
+For strategy impact, report triggered count/rate and amount/share, followed by
+precision and recall. Add the selected contexts' main customer, operations,
+conversion, delay, exposure, or loss measure.
+
+Nested numbered lists use three-space indentation and `1.`, `2.`, `3.` markers.
+Do not use Markdown bold markers in the report body.
+
+## 2. 抽样、分析画像与标签定义
+
+### 2.1 样本范围
+
+Data source, event grains, time span, currencies, and portfolio constants.
+
+### 2.2 分析画像与归因
+
+Use a compact table:
+
+| Field | Value |
+|---|---|
+| 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 |
+| Mechanism | e.g. Account takeover |
+| Context | Card payment / Collection / Bank transfer / Payout |
+| Attribution confidence | Confirmed / Probable / Proxy / Unknown |
+| Decision point | Exact operational point |
+
+Explain unresolved attribution. Do not imply consent from authentication.
+
+### 2.3 标签定义
+
+State label provenance (`file-column` or `user-defined`), confirmed versus proxy,
+and maturity window. Define and count all three populations:
+
+| Population | Required content |
+|---|---|
+| Positive | Exact values/conditions and count |
+| Negative | Exact values/conditions and count |
+| Unlabeled | Pending, immature, unknown, overlapping, or out-of-scope conditions and count |
+
+Report the positive base rate among labeled rows and its denominator. If an
+existing outcome column supplies the positive label, disclose the assumption
+that its other mature, non-explicitly-unlabeled values are negative. If the user
+defined the positive condition, show the separately supplied negative condition.
+Separate labels for separate archetypes.
+
+### 2.4 时间切分
+
+State cut and train/holdout sizes, or state that metrics are in-sample and
+unvalidated. Name the decision point again in one line.
+
+## 3. 规则发现
+
+### 3.1 规则清单与验证集指标
+
+Suggested columns:
+
+```text
+规则类 | 事件与决策时点 | 条件 | 触发率 | 精准率 | 召回率 | lift | 建议动作
+```
+
+- Group conditions into a few operational rule classes.
+- State explicit windows, units, currency, and frozen-list versions.
+- Use actions supplied by selected context packs.
+- List rules once. Multi-rule unions belong to strategy packages in chapter 4.
+
+### 3.2 稳定性与归因
+
+Report temporal instability, small support, weak identity links, proxy outcomes,
+and actor-attribution uncertainty that change action severity.
+
+### 3.3 可落地运营建议
+
+Describe the default package and optional higher-coverage package. Identify
+policy, legal, rail, and operational dependencies for severe interventions.
+
+## 4. 策略整体影响
+
+This is always a standalone chapter.
+
+### 4.1 触发覆盖与标签效果
+
+For every package/action row, report in this order:
+
+1. Triggered count and rate
+2. Triggered amount and amount share, with currency
+3. Precision
+4. Recall
+
+Suggested columns:
+
+```text
+方案 | 动作 | 触发笔数 | 触发率 | 金额 | 金额占比 | 精准率 | 召回率
+```
+
+For mixed currencies without FX conversion, do not sum unlike currencies; show
+separate currency rows or explicitly label any supplied reporting currency.
+
+### 4.2 Domain impact
+
+Use only measures required by selected context packs:
+
+| Context | Typical measures |
+|---|---|
+| Card payment | 3DS/block coverage, authorization success, approval count |
+| Collection | availability delay, return/loss exposure, accepted value |
+| Bank transfer | completion/abandonment, warning/review load, delay, reimbursement exposure |
+| Payout | completion/release, hold duration, review load, exposure |
+
+Separate observed measures from scenario estimates. State every scenario
+assumption and denominator. Do not claim loss prevented from proxy labels.
+
+### 4.3 方案比较（optional）
+
+Compare one recommended and one higher-coverage package under identical
+assumptions. Keep stricter non-default actions visibly separate.
+
+## 5. 特征
+
+### 5.1 入选短名单
+### 5.2 候选特征集
+### 5.3 训练拟合的观察名单或图谱特征（when applicable）
+
+Keep this shorter than rule findings. Name point-in-time construction and weak
+links where material.
+
+## 6. 附录
+
+### A. 决策时点与字段排除
+### B. 标签成熟度、时间切分与训练指标
+### C. 仅描述性信号与未入选候选
+### D. 假设、限制与政策依赖
+
+## Skeleton
+
+```markdown
+# 风险规则分析 — <scope>
+
+数据源：`…`
+分析画像：<archetype> / <mechanism> / <contexts>
+决策时点：<event and point>
+
+## 1. 执行摘要
+## 2. 抽样、分析画像与标签定义
+### 2.1 样本范围
+### 2.2 分析画像与归因
+### 2.3 标签定义
+### 2.4 时间切分
+## 3. 规则发现
+### 3.1 规则清单与验证集指标
+### 3.2 稳定性与归因
+### 3.3 可落地运营建议
+## 4. 策略整体影响
+### 4.1 触发覆盖与标签效果
+### 4.2 <selected context impact>
+### 4.3 方案比较
+## 5. 特征
+### 5.1 入选短名单
+### 5.2 候选特征集
+### 5.3 观察名单或图谱特征
+## 6. 附录
+```

package/skills/payment/fraud-analysis/references/review-checklist.md

@@ -0,0 +1,175 @@
+# Independent review checklist
+
+Use after the report is written. Review the common contract below plus every
+selected archetype, mechanism, and context pack. Do not re-mine features unless
+a fatal issue requires a user-approved restart.
+
+## Inputs
+
+- Draft report and source paths
+- Analysis profile, event grain, and decision point
+- Label definition, maturity window, and attribution confidence
+- Time cut and train/holdout sizes, or explicit in-sample status
+- Allowed and excluded fields
+- Rule definitions and metrics with evaluation window
+- Strategy actions, impact measures, denominators, and assumptions
+- Selected profile pack paths
+
+## Verdicts and severity
+
+| Verdict | Meaning |
+|---|---|
+| PASS | Common and profile checks clear |
+| PASS_WITH_FLAGS | Valid with residual monitoring or judgment issues |
+| NEEDS_CHANGES | Mechanical or substantive issues require repair |
+| BLOCKED | Label, attribution, timing, or data foundation is unusable |
+
+| Severity | Response |
+|---|---|
+| mechanical | Auto-fix and recheck |
+| judgment | Surface; do not silently change attribution or action |
+| fatal | Stop and ask the user |
+
+## Common method checks
+
+### Pre-flight
+
+- [ ] Pre-flight status passed before supervised analysis began
+- [ ] Input readability, row grain, time field, and label provenance were checked
+- [ ] File-column positives map remaining mature rows to negative only after
+  preserving explicit missing/pending/unknown/unlabeled states
+- [ ] User-defined positives received an explicit user-defined negative condition
+  during pre-flight; `NOT positive` was not silently assumed
+- [ ] Both/neither/immature rows are unlabeled, or their absence is demonstrated
+- [ ] Descriptive-only analysis is clearly separated from supervised metrics when
+  pre-flight could not establish both classes
+
+### Analysis profile and attribution
+
+- [ ] Exactly one primary archetype, or separate analyses for multiple archetypes
+- [ ] Customer role, consent, technical authentication, mechanism, context,
+  attribution confidence, event grain, and decision point are stated
+- [ ] Technical authentication is not used as proof of genuine-customer consent
+- [ ] First-party means knowing participation; authorized-payment scam means a
+  deceived victim; third-party means absent genuine-customer consent
+- [ ] APP terminology is limited to authorized push payments
+- [ ] Unresolved victim/participant attribution remains unclassified
+
+### Label and maturity
+
+- [ ] Label provenance is stated as file-column or user-defined
+- [ ] Exact positive, negative, and unlabeled definitions and counts are stated
+- [ ] Existing outcome-column labels disclose the assumption used to map other
+  mature values to negative and preserve explicit pending/unknown states
+- [ ] User-defined positive labels have a separately user-defined negative class;
+  all other rows are not automatically treated as negative
+- [ ] Positive and negative conditions are disjoint; neither/both rows are unlabeled
+- [ ] Confirmed versus proxy status is honest
+- [ ] Positive base rate is factual and uses labeled rows as denominator
+- [ ] Outcome maturity window is defined; immature rows are not clean negatives
+- [ ] Separate archetypes are not blended into one target
+- [ ] Label, synonyms, actions, and later investigation outcomes are excluded
+
+### Temporal validation
+
+- [ ] Earlier train and later holdout cut is stated, or metrics are unvalidated
+- [ ] No random split is presented as temporal validation
+- [ ] Headline metrics come from the claimed window
+- [ ] Thresholds, rate lists, graph lists, and watchlists are fit on train only
+- [ ] Holdout rows may use only history known before each row
+
+### Decision-time validity
+
+- [ ] Every rule field exists at the stated decision point
+- [ ] Current response, settlement, return, recall, dispute, reimbursement,
+  restriction, and investigation fields do not leak backward
+- [ ] History uses prior events and defines timestamp ties
+- [ ] Graph features are point-in-time snapshots
+- [ ] Zero-variance, timing, leakage, and context-only exclusions are listed
+- [ ] Weak entity links are not presented as unique identities
+
+### Metrics and actions
+
+- [ ] Rule metrics use occurrence → precision → recall
+- [ ] Count metrics remain present when value metrics are added
+- [ ] Small-N, unstable, or attribution-uncertain segments are monitored or dropped
+- [ ] Actions come from selected contexts and match precision/evidence severity
+- [ ] Holds, freezes, rejects, restrictions, and reporting state policy/legal
+  dependencies where applicable
+
+## Common report checks
+
+- [ ] Reader order is executive summary → sample/profile/label → rules →
+  strategy impact → features → appendix
+- [ ] Analysis profile and attribution table appears near the start
+- [ ] Strategy impact is a standalone chapter
+- [ ] Every package/action has triggered count/rate and amount/share with currency,
+  followed by precision and recall
+- [ ] Mixed currencies are not summed without documented FX conversion
+- [ ] Domain impact measures and denominators come from selected context packs
+- [ ] Observed results are distinct from scenario estimates
+- [ ] Proxy labels are not translated into measured loss prevented
+- [ ] Executive summary has no more than five top-level findings
+- [ ] No Markdown bold markers or review-process details in the report
+- [ ] Fixed terminology is consistent with `terminology.md`
+- [ ] Banned strings in `terminology.md` have no unexplained hits
+
+## Required profile overlays
+
+Read and check each selected pack. At minimum:
+
+### Third-party fraud
+
+- Unauthorized outcome is supported; not every decline/dispute is fraud.
+- Behavioral deviation uses the genuine customer's prior history.
+
+### First-party fraud
+
+- Evidence supports knowing participation, not merely unusual behavior.
+- Mule/facilitator attribution is not inferred from money flow alone.
+- Restrictions and reporting identify policy/legal dependencies.
+
+### Authorized payment scam
+
+- Consent and deception are both supported.
+- Civil dispute and knowing participation are not mislabeled as scams.
+- Warnings/holds include customer and vulnerability impact.
+
+### Account takeover
+
+- Authentication success is separate from customer consent.
+- Profile/recovery changes and device novelty are point-in-time.
+- Shared IP/device infrastructure is not identity proof.
+
+### Card payment
+
+- Current CVV, AVS, authorization response, and 3DS result respect timing.
+- BIN lists are train-fit; issuer name is live-operable if used.
+- 3DS failures are outside subsequent authorization denominator.
+
+### Collection, transfer, and payout
+
+- Settlement, reversibility, completion, return, and recall timing are correct.
+- Sequence and graph features are point-in-time.
+- Completion, abandonment, delay, workload, and exposure denominators are stated.
+
+## Finding format
+
+```text
+- severity: mechanical | judgment | fatal
+- axis: profile | label | time | decision-time | metrics | actions | report | claims
+- item: <short title>
+- evidence: <specific report location or missing artifact>
+- required_fix: <concrete repair or ask user>
+```
+
+End with:
+
+```text
+VERDICT: PASS | PASS_WITH_FLAGS | NEEDS_CHANGES | BLOCKED
+REVIEWER_MODEL: <id or fallback note>
+AXES: method=…; profile=…; presentation=…
+```
+
+After mechanical fixes, recheck all mechanical items and ensure the repair did
+not alter attribution, introduce leakage, or change action severity silently.

package/skills/payment/fraud-analysis/references/taxonomy.md

@@ -0,0 +1,79 @@
+# Fraud analysis taxonomy
+
+Read this before defining a label. The dimensions are independent: an archetype
+describes the genuine customer's relationship to the fraud, a mechanism explains
+how it happened, and a context identifies where a control operates.
+
+## Archetype router
+
+| Customer consent | Customer participation | Deceived about recipient or purpose | Archetype |
+|---|---|---|---|
+| absent | no | no / unknown | `third-party-fraud` |
+| present | knowing | no | `first-party-fraud` |
+| present | no | yes | `authorized-payment-scam` |
+| disputed / unknown | unknown | unknown | `unclassified` |
+
+Ask:
+
+1. Did the genuine customer consent to this transaction?
+2. Did the customer knowingly participate in the abuse?
+3. Was the customer deceived about the recipient or payment purpose?
+
+Authorization language is overloaded. Record both:
+
+- **Customer consent** — whether the genuine customer intended the transaction.
+- **Technical authentication** — whether credentials, device, session, MFA, or
+  payment authentication passed.
+
+A technically authenticated transaction can still be unauthorized by the
+genuine customer after account takeover.
+
+## Archetypes
+
+### Third-party fraud
+
+An external actor uses another person's account, credentials, instrument, or
+identity without genuine-customer consent. Examples: stolen card, stolen token,
+credential theft, account takeover.
+
+### First-party fraud
+
+The genuine customer or account holder is the perpetrator or a knowing
+participant and misrepresents, manipulates, or deliberately misuses their own
+account for gain. Examples: deliberate collection abuse, false non-receipt or
+refund claims, knowing mule activity, deliberate payout abuse.
+
+Do not call this `first-party scam`: scam usually implies a deceived victim.
+
+### Authorized payment scam
+
+The genuine customer authorizes a payment but is deceived about its recipient or
+purpose. The customer is the victim, not a knowing participant.
+
+`APP scam` is a subtype for a victim-deceived push payment, normally in a bank
+transfer context. Do not apply APP terminology to all authorized payment scams.
+
+### Unclassified
+
+Use when consent, deception, or knowing participation cannot yet be established.
+Analyze observable risk signals, but do not claim archetype-specific loss or use
+the unresolved class as confirmed ground truth.
+
+## Mechanisms and contexts
+
+Mechanisms may include `account-takeover`, stolen payment credential, social
+engineering, synthetic identity, or deliberate account misuse. Add a mechanism
+pack only when its data and controls require specialized guidance.
+
+Supported contexts are `card-payment`, `payment-collection`, `bank-transfer`,
+and `payout`. Select all relevant contexts for linked money-flow analysis, but
+name the event grain and decision point for every rule.
+
+## Mixed cases
+
+- Separate confirmed archetypes into separate targets and metrics.
+- A mule may be a knowing participant (first-party fraud), a coerced or deceived
+  victim (authorized payment scam or unclassified), or an account-takeover victim
+  (third-party fraud). Do not infer the role from rapid movement alone.
+- A customer claim is evidence, not automatic proof of consent or attribution.
+- Civil disputes and service dissatisfaction are not automatically fraud.

package/skills/payment/fraud-analysis/references/terminology.md

@@ -0,0 +1,108 @@
+# Terminology and plain language
+
+Use fixed terms consistently in business reports. Selected profile packs may add
+domain terms but must not replace common metric definitions. Read this file
+before writing. After writing, run the proofread in `SKILL.md` step 8.
+
+## Analysis terms
+
+| English | Chinese | Do not write |
+|---|---|---|
+| archetype | 欺诈类型 / 分析类型 | |
+| mechanism | 作案机制 | |
+| context | 业务场景 | |
+| customer consent | 客户真实授权 / 客户同意 | 用技术认证代替真实授权 |
+| technical authentication | 技术认证 | 当成持卡人同意的证据 |
+| label | 标签 | |
+| label provenance | 标签来源 | |
+| positive class | 正样本 | 正例 |
+| negative class | 负样本 | |
+| unlabeled | 未标注样本 | |
+| proxy label | 近似标签 | 代理标签 |
+| confirmed outcome | 已确认结果 | |
+| base rate | 正样本基线率 | |
+| occurrence | 触发率 | |
+| precision | 精准率 | 精确率（作指标名时） |
+| recall | 召回率 | |
+| lift | 首次写「相对基线倍数（lift）」 | 只写英文且从不解释 |
+| train set | 训练集 | |
+| holdout | 留出集（holdout） | 与「验证集」来回换；正文首次后可简称留出集 |
+| zero-variance | 零方差字段 | |
+| condition | 条件 | 谓词（对业务读者） |
+| outcome maturity | 标签成熟度 | |
+| attribution confidence | 归因置信度 | |
+| attempt | 授权尝试 | |
+| auth rate | 授权成功率 | 转化率；3DS 转化（指授权成功率时） |
+| hard decline | 硬性拒绝（hard decline） | hard 拦截（指拒绝类型时） |
+| chargeback | 拒付（chargeback） | 与清算混用；正文首次后可简称拒付 |
+| insufficient funds | 余额不足 | 余额 |
+| clerical | 文书错误 | 文书 |
+| quality | 质量争议 | 质量 |
+| weak identity | 弱身份线索 | 弱身份键；永久黑箱 |
+| point-in-time | 截至授权时点 | 不经解释的 point-in-time |
+| headline metrics | 主指标 | 不经解释的 headline |
+| before / after (strategy) | 策略前 / 策略后 | after 分母（单独出现） |
+| false hit on good traffic | 误伤 | |
+
+Keep proper nouns: Visa Debit, MasterCard Prepaid, D102, BIN, IIN, PAN, MID,
+MCC, Worldpay, Pazien, Order ID, 3DS, Timestamp.
+
+## Archetypes
+
+| ID | English | Chinese guidance |
+|---|---|---|
+| `third-party-fraud` | Third-party fraud | 第三方欺诈；客户未真实授权 |
+| `first-party-fraud` | First-party fraud | 第一方欺诈；客户本人实施或知情参与 |
+| `authorized-payment-scam` | Authorized payment scam | 授权付款诈骗；客户受骗后真实授权 |
+| `unclassified` | Unclassified | 待归因；不强行归类 |
+| `app-scam` | APP scam | 授权推送付款诈骗，仅用于 push payment |
+| `account-takeover` | Account takeover (ATO) | 账户接管；机制，不是独立欺诈类型 |
+
+Avoid `first-party scam`: it confuses knowing participation with victim
+deception. Do not translate technical authentication as proof of customer
+consent.
+
+## Actions
+
+Use only actions that exist in the selected context:
+
+| English | Chinese |
+|---|---|
+| block / reject | 拦截 / 拒绝 |
+| require 3DS | 要求 3DS |
+| reauthenticate | 要求重新认证 |
+| warn / confirm | 风险提示 / 要求确认 |
+| manual review | 人工审核 |
+| delay / cooling-off | 延迟处理 / 冷静期 |
+| hold | 暂缓 / 冻结处理（按实际政策） |
+| restrict account | 限制账户（按实际政策） |
+| monitor | 仅监控 |
+
+Do not use `冻结` casually when the implemented action is only a review hold.
+State policy or legal dependencies for severe actions.
+
+## Presentation contract
+
+- No Markdown `**bold**` or `__bold__` in report body.
+- Metrics use occurrence → precision → recall.
+- Strategy coverage pairs count/rate and amount/share; money has currency.
+- AND joins co-required conditions; `+` joins package components.
+- Headings and tables provide structure; avoid agent/process language.
+- Keep reviewer verdict, model, and repair logs out of the report.
+- Prefer 留出集 after the first gloss `留出集（holdout）`. Do not bounce
+  between 验证集 and holdout in the same report unless quoting a column name.
+
+## Banned strings (grep after writing)
+
+Chinese: `正例`, `代理标签`, `精确率`, `转化率`, `3DS 转化`, `弱身份键`,
+`永久黑箱`, `方案侧证据`, `偏热`, `变冷`, `赋能`, `抓手`, `闭环`
+
+English leftovers in Chinese reports: `headline`, `uplift` without a Chinese
+gloss, `after 分母`, `hard 拦截` (when meaning decline class), `point-in-time`
+without 截至授权时点.
+
+## Proofread
+
+1. Apply this glossary to headings, tables, and body.
+2. Grep the report for banned strings.
+3. Fix language only. Do not change numbers, BIN lists, thresholds, or paths.