@1aboveio/skills 0.14.0 → 0.16.1

package/skills/payment/fraud-analysis/references/archetypes/first-party-fraud.md

@@ -0,0 +1,44 @@
+# Archetype: first-party fraud
+
+The genuine customer or account holder is the perpetrator or a knowing
+participant who misrepresents, manipulates, or deliberately misuses their own
+account for financial or material gain.
+
+## Label guidance
+
+Prefer confirmed investigation outcomes that establish knowing participation.
+Operational holds, rapid payout, negative balance, returns, complaints, or mule
+signals are proxies unless the business has validated them as outcomes. State
+whether the target is account misuse, collection abuse, payout abuse, false
+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.
+
+## Feature families
+
+- Account age, identity/KYC state, linked accounts, and shared devices
+- Collection-to-transfer/payout sequence, elapsed time, and value passed through
+- Fan-in, fan-out, counterparty concentration, and beneficiary reuse
+- Balance drain, return/recall history, negative exposure, and claim behavior
+- Deviation from the account's history and cross-account coordinated behavior
+
+Graph and network features must be point-in-time snapshots. Investigation
+findings and future counterparties must not leak into earlier rows.
+
+## Actions and impact
+
+Potential actions include review, reserve, delayed availability, payout hold,
+account restriction, enhanced due diligence, or rejection where authorized by
+policy. Report review workload, legitimate-customer impact, completion/release
+rate, delay, exposure, and confirmed value captured. Do not claim loss prevented
+from a proxy label alone.
+
+## Review overlay
+
+- 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.
+- Account restrictions and reporting recommendations identify policy and legal
+  dependencies.

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

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

@@ -0,0 +1,24 @@
+# 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.
+
+## Features
+
+Beneficiary novelty and age, payee verification, amount deviation, transfer
+velocity, device/session context, customer history, beneficiary/account graph,
+counterparty concentration, and prior confirmed outcomes known at the time.
+
+For APP scams, the genuine customer authorizes the push payment while deceived.
+For account takeover, technical authentication may pass without customer consent.
+
+## Actions and impact
+
+Actions: warning, payee/customer confirmation, reauthentication, cooling-off,
+manual review, hold, reject, or monitor. Measure interventions by count/value,
+completion/abandonment, delay, review workload, recalls/reimbursements, and
+confirmed fraud or scam value captured.
+
+Irreversibility and hold authority depend on rail, market, and policy; state the
+applicable assumptions.

package/skills/payment/fraud-analysis/references/contexts/card-payment.md

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

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

@@ -0,0 +1,20 @@
+# 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/payment/fraud-analysis/references/feature-engineering.md

@@ -0,0 +1,158 @@
+# Shared feature engineering
+
+Read this in Step 4 after pre-flight passes, the analysis profile is selected,
+and its packs are loaded.
+This file defines invariants. Archetype, mechanism, and context packs supply the
+actual feature families and operational constraints.
+
+The goal is a small set of interpretable, decision-time-valid inputs that can
+become rules. Build thresholds, lists, rates, and graph artifacts on train only.
+
+## 1. Declare grain and decision point
+
+Name what one scored row represents and when the rule fires. Examples include a
+login, card authorization, collection receipt, beneficiary creation, transfer
+instruction, payout request, or investigation case.
+
+A feature is usable only if its value existed at that decision point in the live
+workflow. Correlation with the eventual label is insufficient.
+
+For linked journeys, a rule may use prior event types, but never a future event:
+
+```text
+login → profile change → beneficiary creation → collection → transfer → payout
+```
+
+The position of the scored event determines what is known.
+
+## 2. Classify every field
+
+For each source and engineered field, record:
+
+1. Business meaning
+2. Event grain
+3. When it becomes known
+4. Whether it is the label or a synonym
+5. Whether it uses current, prior, or future events
+6. Whether the identity link is strong enough for the claim
+
+Place it in one list:
+
+- **Allowed now** — decision-time-valid and variable
+- **Excluded: zero variance** — baseline context, not a feature
+- **Excluded: timing** — real information available too late
+- **Excluded: leakage** — target, synonym, or post-outcome artifact
+- **Context only** — useful description but not operable in the target system
+
+Do not silently drop exclusions. Include them in analysis notes and summarize
+material exclusions in the report appendix.
+
+## 3. Shared feature families
+
+Use only families supported by the selected packs and source data:
+
+- Current-event attributes: amount, currency, channel, product, state available
+  at decision time
+- Entity history: customer, account, instrument, beneficiary, device, session,
+  IP, email, phone, merchant, or counterparty
+- Velocity: prior counts, amounts, distinct entities, and elapsed time over
+  operational windows
+- Novelty and deviation: new entity, behavior unlike the entity's prior history,
+  amount relative to prior behavior
+- Sequences: explicit prior-event patterns across the money or access journey
+- Networks: fan-in, fan-out, shared identifiers, clusters, and risky-neighbor
+  evidence from a point-in-time graph
+- Train-fit lists: entities or segments with minimum support and elevated rate
+
+## 4. Point-in-time history
+
+- Sort events deterministically by time within each identity key.
+- Use timestamps strictly before the current event. Define tie behavior.
+- Holdout rows may use train-era history that predates the row.
+- Never use the current row's outcome in its own features.
+- Graph nodes, edges, labels, and aggregates must be snapshots as of the event.
+- Outcome labels become historical evidence only after they would have been known
+  operationally, not merely after the underlying transaction occurred.
+
+Use windows operations can implement, such as 10m, 1h, 24h, or 7d. Avoid exact
+sequences and fine windows selected only because they maximize train fit.
+
+## 5. Identity-link quality
+
+Document whether keys identify a person, account, instrument, device, session,
+or merely a shared attribute. Masked identifiers, IPs, addresses, and devices may
+collide or be shared.
+
+- Do not turn a weak key into a claimed unique customer or account.
+- Do not infer knowing participation from shared infrastructure alone.
+- Distinguish deterministic links from probabilistic links.
+- Keep network-derived high-risk lists monitor-only when link quality or actor
+  attribution is weak.
+
+## 6. Labels and outcome maturity
+
+Fraud, scam, recalls, returns, disputes, reimbursements, investigations, and
+account restrictions often mature after the event.
+
+- Define when an outcome becomes observable.
+- Exclude immature recent events or treat them as unlabeled, not clean negatives.
+- Record whether the label comes from an existing outcome column or a
+  user-defined condition.
+- For an existing row-level outcome column, mapped positive values may use all
+  other mature values as negative unless an explicit pending/unknown/unlabeled
+  value exists. State this assumption and preserve those explicit states as
+  unlabeled.
+- For a user-defined positive condition, require a separate user-defined
+  negative condition. Rows outside the positive condition are not automatically
+  negative.
+- Verify positive and negative conditions are disjoint. Exclude rows matching
+  neither or both from supervised metrics and report their count.
+- Fit label-rate lists on mature train outcomes only.
+- Do not use an operational action as both label and feature.
+- Do not blend separate archetypes into a single positive label.
+
+## 7. Train-fit thresholds and lists
+
+- Propose thresholds from business meaning or train distributions.
+- Require minimum support for entity, graph, or segment lists.
+- Freeze conditions and memberships before holdout scoring.
+- Apply frozen artifacts to holdout without reranking on holdout outcomes.
+- Small-N spikes remain monitoring candidates.
+
+## 8. Rule-ready conditions
+
+Every shortlisted candidate must specify:
+
+```text
+event grain + decision point + fields + operator + threshold/list + units + window
+```
+
+Prefer:
+
+- `amount >= <currency threshold>` over “high amount”
+- `prior_attempts_1h >= 3` over “high velocity”
+- `beneficiary_age_minutes <= 30` over “new beneficiary”
+- `entity in train_fit_watchlist_v1` over a holdout-ranked list
+
+## 9. Universal do-not list
+
+- Do not use zero-variance fields as rule conditions.
+- Do not use future events, current outcomes, or investigation results.
+- Do not treat technical authentication as proof of customer consent.
+- Do not infer victim, perpetrator, mule, or facilitator role from behavior alone.
+- Do not fit thresholds, rates, graph lists, or watchlists on holdout.
+- Do not present proxy labels as confirmed fraud or loss avoided.
+- Do not invent missing fields, identity links, currencies, or event semantics.
+
+## 10. Ready-for-selection checklist
+
+- [ ] Analysis profile loaded
+- [ ] Event grain and decision point stated
+- [ ] Outcome maturity defined
+- [ ] Label provenance and positive/negative/unlabeled definitions recorded
+- [ ] Positive and negative conditions are disjoint
+- [ ] Fields classified into allowed/excluded/context-only lists
+- [ ] History and graph features are point-in-time
+- [ ] Identity-link strength documented
+- [ ] Thresholds and lists fit on train only
+- [ ] Candidates expressed as operable conditions

package/skills/payment/fraud-analysis/references/mechanisms/account-takeover.md

@@ -0,0 +1,36 @@
+# Mechanism: account takeover
+
+An external actor gains control of a genuine customer's account or authenticated
+session. This normally composes with `third-party-fraud`; if consent or knowing
+participation is unresolved, keep the archetype `unclassified`.
+
+## Key distinction
+
+Technical authentication is not customer consent. A criminal may pass password,
+MFA, device, session, or transaction authentication using compromised access.
+
+## Feature families
+
+- New device, browser, IP, ASN, geography, or session
+- Password, MFA, phone, email, recovery, or trusted-device changes
+- Failed-login bursts, credential-stuffing indicators, and impossible travel
+- Session age, authentication strength, and deviation from trusted behavior
+- New beneficiary after access changes; login-to-transfer/payout velocity
+- Shared devices, IPs, recovery identifiers, or beneficiaries across accounts
+
+Only use events before the rule's decision point. Do not use later compromise
+confirmation, customer contact, session revocation, or investigation findings.
+
+## Actions
+
+Depending on context: terminate session, require reauthentication through an
+independent channel, reset credentials, remove trusted devices, cool off new
+beneficiaries, hold/review money movement, and restrict the account where policy
+permits.
+
+## Review overlay
+
+- Authentication success is not described as genuine-customer authorization.
+- Recovery and profile-change timestamps precede the scored event.
+- Device/IP novelty uses only prior customer history.
+- Shared infrastructure such as carrier NAT is not treated as identity proof.

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

@@ -0,0 +1,45 @@
+# Report rationale (agent only)
+
+This explains the business report contract. Do not copy it into deliverables.
+
+## Why composition matters
+
+Archetype, mechanism, and context answer different questions:
+
+- Archetype identifies the genuine customer's relationship to fraud.
+- Mechanism explains compromise, deception, or deliberate abuse.
+- Context identifies the operational control point and business denominator.
+
+Keeping them independent prevents category errors such as treating account
+takeover as a peer of first-party fraud, treating every authenticated transfer as
+customer-authorized, or applying 3DS and authorization-success metrics to payout
+and collection controls.
+
+## Report choices
+
+| Choice | Reason |
+|---|---|
+| Profile before label | The same status can represent different actors and outcomes across archetypes |
+| Explicit negative class | Precision, recall, and lift are undefined or misleading when “not positive” silently mixes genuine negatives with unknown outcomes |
+| Consent separate from authentication | Compromised credentials can pass technical checks |
+| Reader order differs from workflow | Operators need decisions before methodology |
+| Standalone strategy impact | Portfolio friction and exposure determine whether rules should ship |
+| Count/rate and amount/share | Both operational volume and value matter |
+| Context-specific impact | Authorization, completion, delay, review, and exposure use different denominators |
+| Proxy and maturity disclosure | Delayed outcomes and operational actions are not confirmed fraud by default |
+| Point-in-time graphs | Future counterparties and investigations otherwise leak into earlier events |
+| No review process in report | Review metadata is not business content |
+
+## Domain examples
+
+- `third-party-fraud + card-payment` loads card/BIN/3DS and authorization-impact
+  guidance.
+- `third-party-fraud + account-takeover + bank-transfer` loads access/session,
+  beneficiary, transfer, and consent-versus-authentication guidance.
+- `first-party-fraud + payment-collection + payout` loads money-flow, graph,
+  settlement, hold, workload, delay, and exposure guidance.
+- `authorized-payment-scam + bank-transfer + app-scam` loads deception,
+  beneficiary, warnings, completion, reimbursement, and customer-impact guidance.
+
+If archetype attribution is unresolved, the report should say so and limit claims
+and actions accordingly rather than manufacturing certainty.

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. 附录
+```