@1aboveio/skills 0.15.0 → 0.17.0

package/skills/payment/fraud-analysis/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: fraud-analysis
+description: >
+  Analyze tabular payment, transfer, collection, payout, account, or fraud-case
+  data (CSV, XLSX, TXT) to find interpretable features and operable risk rules.
+  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. Produces temporal holdout 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.
+---
+
+# Fraud Analysis
+
+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. Time split → 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.
+
+> 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/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 |
+
+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. Freeze time split
+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=…`, `cut=…`,
+`allowed/excluded=…`, `shortlist=…`, `N rules, holdout|in-sample`,
+`packages=…`, `report=…`, `verdict=…`.
+
+## Input
+
+CSV / XLSX / TXT; one row per event or case; optional outcome column. A dataset
+may contain more than one event type, but every scored rule needs a declared
+event grain and decision point.
+
+## Workflow
+
+Follow [references/workflow.md](references/workflow.md) for each step. The map:
+
+| Step | Do | Gate |
+|---|---|---|
+| 0 Pre-flight | Label provenance; pass / needs-user-input / descriptive-only / blocked | No supervised metrics until pass |
+| 1 Profile | Archetype + mechanism(s) + context(s) from taxonomy | Read selected packs before Step 2 |
+| 2 Label | Formalize positive / negative / unlabeled | Both classes defined before scoring |
+| 3 Time split | Freeze train/holdout before features | No random shuffle as headline |
+| 4 Features | Engineer candidates at decision time | Train-only thresholds |
+| 5 Shortlist | Lift / support / stability / operability | Train only |
+| 6 Score | occurrence → precision → recall on holdout | Headline = holdout |
+| 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; headline window identified |
+| Strategy coverage | triggered count + rate and amount + share, with currency |
+| 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.

package/skills/payment/fraud-analysis/evals/evals.json

@@ -0,0 +1,40 @@
+{
+  "skill_name": "fraud-analysis",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Analyze transfers.csv. The transactions passed login and MFA, but customers later confirmed they did not initiate them. Most transfers followed a password reset and new beneficiary setup. Find rules we can apply before transfer execution.",
+      "expected_output": "Routes to third-party fraud with account-takeover mechanism and bank-transfer context; separates technical authentication from customer consent; excludes later customer confirmation from pre-transfer features; proposes point-in-time access, beneficiary, and transfer features."
+    },
+    {
+      "id": 2,
+      "prompt": "Analyze collections_and_payouts.xlsx for customers who knowingly receive funds from many unrelated payers and rapidly cash out to linked beneficiaries. Confirmed investigation outcomes identify participating account holders.",
+      "expected_output": "Routes to first-party fraud with payment-collection and payout contexts; uses confirmed knowing participation as the label; engineers point-in-time fan-in, fan-out, collection-to-payout, account, device, and graph features; reports hold/review workload, delay, legitimate-customer impact, and exposure."
+    },
+    {
+      "id": 3,
+      "prompt": "Analyze bank_transfers.csv for APP scams. Customers themselves sent the payments after impersonation calls. We have later scam claims, reimbursement decisions, beneficiary data, warning interactions, and transfer timestamps.",
+      "expected_output": "Routes to authorized payment scam with APP subtype and bank-transfer context; treats customers as deceived victims; distinguishes claims and reimbursement decisions from decision-time features; evaluates warnings, confirmation, review, delay, completion, and reimbursement impact."
+    },
+    {
+      "id": 4,
+      "prompt": "Review card_auths.csv and propose pre-authorization rules for confirmed stolen-card transactions. It includes BIN, token, amount, CVV response, AVS response, issuer decline code, 3DS result, and chargeback outcome.",
+      "expected_output": "Routes to third-party fraud and card-payment; preserves card/BIN/history feature guidance; excludes current CVV, AVS, authorization response, 3DS result, and chargeback outcome at pre-auth; evaluates block, 3DS, or monitor actions with correct authorization denominators."
+    },
+    {
+      "id": 5,
+      "prompt": "Analyze suspicious payout accounts. Some may be knowing mules, some may be scam victims, and some may have been taken over. The file has behavior flags but no completed investigations or customer-consent evidence.",
+      "expected_output": "Keeps archetype unclassified rather than forcing mule, scam, or ATO attribution; treats behavior flags as proxy signals; avoids a blended confirmed-fraud label; limits severe actions and clearly states attribution and evidence gaps."
+    },
+    {
+      "id": 6,
+      "prompt": "Use outcome.csv where the existing case_result column has CONFIRMED_FRAUD, LEGITIMATE, and PENDING. Treat CONFIRMED_FRAUD as positive and analyze the rules.",
+      "expected_output": "Records file-column provenance; maps CONFIRMED_FRAUD to positive, LEGITIMATE to negative, and PENDING to unlabeled rather than negative; reports all counts and computes the base rate over labeled mature rows."
+    },
+    {
+      "id": 7,
+      "prompt": "For transfers.csv, define positives as accounts with at least three payouts within one hour after receiving funds. Find first-party fraud rules.",
+      "expected_output": "Pre-flight recognizes a user-defined positive condition and asks the user to define the negative condition before profile selection or supervised analysis; does not treat every other account as negative; leaves unmatched rows unlabeled."
+    }
+  ]
+}

package/skills/payment/fraud-analysis/references/archetypes/authorized-payment-scam.md

@@ -0,0 +1,41 @@
+# Archetype: authorized payment scam
+
+The genuine customer consents to a payment but is deceived about the recipient
+or purpose. The customer is the victim and is not knowingly party to the fraud.
+
+Use subtype `app-scam` only for an authorized push payment, normally a bank
+transfer. Record the scam subtype when supported, such as impersonation,
+purchase, investment, romance, or invoice redirection; do not infer it from
+amount or beneficiary shape alone.
+
+## Label guidance
+
+Prefer adjudicated scam outcomes. Customer reports, recalls, warnings ignored,
+beneficiary risk, and reimbursement decisions can be useful but may be proxies
+or policy outcomes rather than ground truth. Distinguish scams from civil
+disputes and first-party participation.
+
+## Feature families
+
+- New beneficiary, beneficiary risk, payee-name mismatch, and counterparty graph
+- Unusual amount, frequency, payment purpose, and deviation from customer history
+- Session/payment journey, warning interaction, confirmation responses, and
+  contact-channel changes available before execution
+- Urgency patterns, repeated limit-sized payments, and rapid beneficiary changes
+- Prior complaints or confirmed beneficiary outcomes known before the payment
+
+## Actions and impact
+
+Potential actions include contextual warning, payee confirmation, customer
+confirmation, cooling-off delay, manual review, transfer hold, or reject where
+policy permits. Measure warning/review/hold volume and value, completion and
+abandonment, review workload, delay, reimbursement exposure, and confirmed scam
+value captured. Do not optimize only for authorization success.
+
+## Review overlay
+
+- Genuine customer consent and deception are both supported.
+- The customer is not knowingly participating; otherwise route to first-party.
+- APP terminology is used only for push payments.
+- Post-payment reports, recalls, reimbursements, and investigations do not leak.
+- Warnings and holds account for vulnerable-customer and policy considerations.

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.