@1aboveio/risk-compliance-skills 0.1.9 → 0.1.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/README.md +3 -2
  2. package/package.json +5 -3
  3. package/skills/compliance-audit/SKILL.md +4 -8
  4. package/skills/compliance-audit/references/audience-and-reports.md +12 -0
  5. package/skills/contract-compare/SKILL.md +17 -1
  6. package/skills/contract-review/SKILL.md +6 -1
  7. package/skills/contract-review/references/report-stage.md +17 -0
  8. package/skills/doc-authenticity/SKILL.md +11 -1
  9. package/skills/fraud-detection/SKILL.md +148 -0
  10. package/skills/{fraud-analysis → fraud-detection}/references/archetypes/first-party-fraud.md +3 -2
  11. package/skills/fraud-detection/references/archetypes/third-party-fraud.md +47 -0
  12. package/skills/fraud-detection/references/collection-payout-features.md +151 -0
  13. package/skills/{fraud-analysis → fraud-detection}/references/contexts/bank-transfer.md +4 -3
  14. package/skills/fraud-detection/references/contexts/card-payment.md +70 -0
  15. package/skills/fraud-detection/references/contexts/payment-collection.md +34 -0
  16. package/skills/fraud-detection/references/contexts/payout.md +34 -0
  17. package/skills/fraud-detection/references/enrichment.md +74 -0
  18. package/skills/fraud-detection/references/entities.md +48 -0
  19. package/skills/{fraud-analysis → fraud-detection}/references/feature-engineering.md +69 -33
  20. package/skills/fraud-detection/references/feature-sql.md +150 -0
  21. package/skills/{fraud-analysis → fraud-detection}/references/report-rationale.md +4 -2
  22. package/skills/{fraud-analysis → fraud-detection}/references/report-template.md +45 -23
  23. package/skills/{fraud-analysis → fraud-detection}/references/review-checklist.md +60 -20
  24. package/skills/fraud-detection/references/workflow.md +216 -0
  25. package/skills/payment-analysis/SKILL.md +36 -17
  26. package/skills/payment-analysis/references/auth-rate-actions.md +2 -2
  27. package/skills/payment-analysis/references/report-template.md +10 -2
  28. package/skills/payment-analysis/references/visualization.md +11 -1
  29. package/skills/portfolio-payment-analysis/LICENSE +3 -0
  30. package/skills/portfolio-payment-analysis/SKILL.md +170 -0
  31. package/skills/portfolio-payment-analysis/references/identity-and-reconciliation.md +46 -0
  32. package/skills/portfolio-payment-analysis/references/metrics-and-reporting.md +170 -0
  33. package/skills/portfolio-payment-analysis/references/risk-history.md +89 -0
  34. package/skills/portfolio-payment-analysis/release-check.mjs +95 -0
  35. package/skills/portfolio-payment-analysis/scripts/analyze.py +636 -0
  36. package/skills/portfolio-payment-analysis/scripts/build_report.py +386 -0
  37. package/skills/portfolio-payment-analysis/scripts/comparison_charts.py +425 -0
  38. package/skills/portfolio-payment-analysis/scripts/csv_export.py +52 -0
  39. package/skills/portfolio-payment-analysis/scripts/render.py +160 -0
  40. package/skills/portfolio-payment-analysis/scripts/risk_history.py +435 -0
  41. package/skills/similar-domain/SKILL.md +9 -4
  42. package/skills/tld-detection/SKILL.md +124 -239
  43. package/skills/tld-detection/agents/openai.yaml +1 -1
  44. package/skills/tld-detection/references/clean.md +18 -51
  45. package/skills/tld-detection/references/fx-conversion.md +56 -219
  46. package/skills/tld-detection/references/metric-contract.md +109 -0
  47. package/skills/tld-detection/references/pattern.md +99 -0
  48. package/skills/tld-detection/references/report-template.md +49 -272
  49. package/skills/tld-detection/scripts/detect_ladders.py +46 -13
  50. package/skills/tld-detection/scripts/detect_patterns.py +346 -0
  51. package/skills/tld-detection/scripts/detect_streams.py +51 -19
  52. package/skills/tld-detection/scripts/profile_groups.py +109 -0
  53. package/skills/tld-detection/scripts/render_charts.py +218 -0
  54. package/skills/tld-detection/scripts/tld_common.py +243 -0
  55. package/skills/fraud-analysis/SKILL.md +0 -114
  56. package/skills/fraud-analysis/references/archetypes/third-party-fraud.md +0 -27
  57. package/skills/fraud-analysis/references/contexts/card-payment.md +0 -30
  58. package/skills/fraud-analysis/references/contexts/payment-collection.md +0 -20
  59. package/skills/fraud-analysis/references/contexts/payout.md +0 -20
  60. package/skills/fraud-analysis/references/workflow.md +0 -175
  61. package/skills/tld-detection/references/chinese-polish.md +0 -55
  62. package/skills/tld-detection/references/clustering.md +0 -235
  63. package/skills/tld-detection/references/decision.md +0 -189
  64. package/skills/tld-detection/references/streams.md +0 -141
  65. package/skills/tld-detection/references/terminology.md +0 -95
  66. package/skills/tld-detection/references/workflow.md +0 -95
  67. /package/skills/{fraud-analysis → fraud-detection}/LICENSE +0 -0
  68. /package/skills/{fraud-analysis → fraud-detection}/references/archetypes/authorized-payment-scam.md +0 -0
  69. /package/skills/{fraud-analysis → fraud-detection}/references/mechanisms/account-takeover.md +0 -0
  70. /package/skills/{fraud-analysis → fraud-detection}/references/taxonomy.md +0 -0
  71. /package/skills/{fraud-analysis → fraud-detection}/references/terminology.md +0 -0
  72. /package/skills/{fraud-analysis → fraud-detection}/release-check.mjs +0 -0
package/README.md CHANGED
@@ -11,7 +11,7 @@ pi install npm:@1aboveio/core-skills
11
11
  pi install npm:@1aboveio/risk-compliance-skills
12
12
  ```
13
13
 
14
- This package uses doc-to-md, editorial-review, house-style, polish-cn from `@1aboveio/core-skills`; Pi warns at startup if it is missing.
14
+ This package uses doc-to-md, editorial-review, house-style, polish-cn, terminology, write-report from `@1aboveio/core-skills`; Pi warns at startup if it is missing.
15
15
 
16
16
  ## Skills
17
17
 
@@ -19,8 +19,9 @@ This package uses doc-to-md, editorial-review, house-style, polish-cn from `@1ab
19
19
  - `contract-compare`
20
20
  - `contract-review`
21
21
  - `doc-authenticity`
22
- - `fraud-analysis`
22
+ - `fraud-detection`
23
23
  - `payment-analysis`
24
+ - `portfolio-payment-analysis`
24
25
  - `similar-domain`
25
26
  - `tld-detection`
26
27
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@1aboveio/risk-compliance-skills",
3
- "version": "0.1.9",
3
+ "version": "0.1.11",
4
4
  "description": "Compliance audits, contract review, payment and fraud analysis.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -34,9 +34,11 @@
34
34
  "doc-to-md",
35
35
  "editorial-review",
36
36
  "house-style",
37
- "polish-cn"
37
+ "polish-cn",
38
+ "terminology",
39
+ "write-report"
38
40
  ],
39
- "digest": "70fed43fda7c72625770e42f699ee65405c17ea4d81c9c4cc669f337c34a3e0b"
41
+ "digest": "9fde367ae831bacd609e01cb1bd4824c1e48c45b626f73ef24e3ed1f39133b49"
40
42
  },
41
43
  "publishConfig": {
42
44
  "registry": "https://registry.npmjs.org/",
@@ -2,7 +2,7 @@
2
2
  name: compliance-audit
3
3
  version: 2.9.0
4
4
  description: "Audit operations against financial-compliance checklists (AML/KYC, VARS, PCI-DSS, TPA oversight, onboarding, transaction monitoring). Produces tracker.md (with a tracker.xlsx export) and phase-trail.md with layered validation; cites evidence by original filename. Input: reg-parser or the built-in VARS checklist."
5
- release-version: 0.44.0
5
+ release-version: 0.45.0
6
6
  ---
7
7
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
8
8
  # Compliance Audit
@@ -12,13 +12,9 @@ keyed by control item that the client can update through remediation —
12
12
  alongside a phase trail companion file (work product) that preserves what each
13
13
  phase saw before the tracker was finalised.
14
14
 
15
- ## Audience
16
-
17
- The user is a **compliance auditor or analyst** working in regulated financial
18
- services — payments, banking, fintech, insurance. They audit against financial
19
- regulatory frameworks: AML regulations, KYC requirements, financial reporting
20
- standards, local financial authority rules, and card-scheme standards such as
21
- VARS.
15
+ Read [audience and report handoff](references/audience-and-reports.md) before starting;
16
+ it defines the auditor audience and the optional report-writing handoff without replacing
17
+ this assessment or its validation.
22
18
 
23
19
  ## Audit Workflow
24
20
 
@@ -0,0 +1,12 @@
1
+ # Audience and report handoff
2
+
3
+ The user is a **compliance auditor or analyst** working in regulated financial
4
+ services -- payments, banking, fintech, insurance. They audit against financial
5
+ regulatory frameworks: AML regulations, KYC requirements, financial reporting
6
+ standards, local financial authority rules, and card-scheme standards such as
7
+ VARS.
8
+
9
+ When the user also requests an analytical report, hand the validated tracker and phase trail
10
+ to `write-report` when installed. Its compliance branch owns audit, external, management and
11
+ VARS report writing; it does not replace this assessment or its validation. Without that skill,
12
+ deliver the audit artifacts and state that the report-writing stage remains outstanding.
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: contract-compare
3
3
  description: "Compare two or more contracts side-by-side for structured diff, gap analysis, and benchmarking. Use when: comparing contracts or agreements, contract diff, compare terms, vendor-vs-vendor, compare our template vs theirs, compliance gap between contracts. NOT for single-contract risk review — use contract-review for that."
4
- release-version: 0.44.0
4
+ release-version: 0.45.0
5
5
  ---
6
6
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
7
  # Contract Compare
@@ -97,6 +97,22 @@ Wait for all dimension subagents to return.
97
97
 
98
98
  ## Step 4: Build Comparison Report
99
99
 
100
+ Required report-stage resource: the installed `house-style` skill. This skill remains available
101
+ as an ungrouped native selection; native Skills CLI does not install dependencies automatically.
102
+ Select `house-style` with `contract-compare`, or install the Core and Risk & Compliance npm packages.
103
+ Resolve its installed base directory, not a repository-only `skills/writing/` path.
104
+
105
+ Before drafting or substantively reviewing an analytical report, read
106
+ `{house-style baseDir}/references/analytical-reporting.md`,
107
+ `{house-style baseDir}/references/analytical-writing-patterns.md`, and
108
+ `{house-style baseDir}/references/definitions-and-metrics.md` directly. Follow their
109
+ loading and delegation instructions; report a missing or unreadable reference as a
110
+ blocker rather than claiming the report stage is complete. Apply them within the
111
+ requested scope, including a chat-only response; do not create a report for an
112
+ audit-only or narrower request. Preserve the selected dimensions, clause evidence,
113
+ assessments, legal caveats, optional mandate tracing, and the required report format.
114
+ Generic editorial checks do not replace specialist legal review.
115
+
100
116
  **House style.** Use the nearest `WRITING.md`: start in the first contract's folder (pasted text: the output
101
117
  folder, else the working directory), then parents up to the repository root; never the home
102
118
  directory or above. Rate every issue from the evidence first; the style changes
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: contract-review
3
3
  description: "Review contracts for legal, commercial, and compliance risks via convert → chunk review → merge → validate (+ optional mandate preprocessing). Use for reviewing, auditing, or checking any contract, agreement, NDA, MSA, or SLA; input a file path (PDF/DOCX/TXT) or pasted text."
4
- release-version: 0.44.0
4
+ release-version: 0.45.0
5
5
  ---
6
6
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
7
  # Contract Review
@@ -106,6 +106,10 @@ Start all chunk subagents in parallel and wait for all to complete.
106
106
 
107
107
  ## Step 3: Merge Results
108
108
 
109
+ Before drafting or substantively reviewing the report, read and follow
110
+ [the analytical report-stage instructions](references/report-stage.md), including all three
111
+ required `house-style` references and their loading/delegation rules. Preserve Step 4 validation.
112
+
109
113
  **House style.** Use the nearest `WRITING.md`: start in the contract file's folder (pasted text: the output
110
114
  folder, else the working directory), then parents up to the repository root; never the home
111
115
  directory or above. Rate every issue from the evidence first: the style changes wording, never a rating,
@@ -182,6 +186,7 @@ Substitute `{contract-review baseDir}` and `{reg-parser baseDir}` as in Step 2:
182
186
  You are validating a contract review report for completeness and consistency.
183
187
 
184
188
  Load the review criteria from: {contract-review baseDir}/references/review-criteria.md
189
+ Load the analytical reporting instructions from: {house-style baseDir}/references/analytical-reporting.md, {house-style baseDir}/references/analytical-writing-patterns.md, and {house-style baseDir}/references/definitions-and-metrics.md
185
190
  Load any preprocessed mandate files from: {reg-parser baseDir}/references/mandates/ (read all .md files present)
186
191
  Use mandate files to verify P10 annotations ([Mandated]/[Permitted]/[Counterparty-Added]) are accurate.
187
192
 
@@ -0,0 +1,17 @@
1
+ # Analytical report stage
2
+
3
+ Required report-stage resource: the installed `house-style` skill. This skill remains available
4
+ as an ungrouped native selection; native Skills CLI does not install dependencies automatically.
5
+ Select `house-style` with `contract-review`, or install the Core and Risk & Compliance npm packages.
6
+ Resolve its installed base directory, not a repository-only `skills/writing/` path.
7
+
8
+ Before drafting or substantively reviewing an analytical report, read
9
+ `{house-style baseDir}/references/analytical-reporting.md`,
10
+ `{house-style baseDir}/references/analytical-writing-patterns.md`, and
11
+ `{house-style baseDir}/references/definitions-and-metrics.md` directly. Follow their
12
+ loading and delegation instructions; report a missing or unreadable reference as a
13
+ blocker rather than claiming the report stage is complete. Apply them within the
14
+ requested scope, including a chat-only response; do not create a report for an
15
+ audit-only or narrower request. Preserve this skill's review criteria, evidence,
16
+ severity ratings, mandated layout, and Step 4 specialist validation. Generic editorial
17
+ checks do not replace legal validation.
@@ -3,7 +3,7 @@ name: doc-authenticity
3
3
  version: 0.4.1
4
4
  description: "Screen PDF documents and raster images for fabrication, tampering, Photoshop or other image-editor use, and content validity. Detects file type, runs format-specific authenticity forensics, classifies bank statements, conversation logs, invoices, agreements, and other documents, then applies type-specific validity checks. Produces separate authenticity (NO_EVIDENCE_OF_MODIFICATION / SUSPICIOUS / LIKELY_MODIFIED / INCONCLUSIVE) and validity (VALID / INVALID / INCONCLUSIVE) verdicts. Use whenever a user asks whether a document, screenshot, scan, statement, invoice, contract, chat log, receipt, or payment evidence is genuine, original, edited, Photoshopped, manipulated, fake, or valid."
5
5
  disable-model-invocation: true
6
- release-version: 0.44.0
6
+ release-version: 0.45.0
7
7
  ---
8
8
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
9
9
  # Document and Image Authenticity
@@ -117,6 +117,16 @@ future specialized profile is added.
117
117
 
118
118
  ### 5. Verdict and report
119
119
 
120
+ Before drafting or substantively reviewing an analytical report, read
121
+ `{house-style baseDir}/references/analytical-reporting.md`,
122
+ `{house-style baseDir}/references/analytical-writing-patterns.md`, and
123
+ `{house-style baseDir}/references/definitions-and-metrics.md` directly. Follow their
124
+ loading and delegation instructions; report a missing or unreadable reference as a
125
+ blocker rather than claiming the report stage is complete. Apply them within the
126
+ requested scope, including a chat-only response; do not create a report for an
127
+ audit-only or narrower request. Preserve forensic and validity methods, evidence,
128
+ independent verdicts, required checks, report layout, schema, and validation.
129
+
120
130
  Read `references/verdict-and-report.md`. Apply its rubrics independently to:
121
131
 
122
132
  - authenticity: `NO_EVIDENCE_OF_MODIFICATION | SUSPICIOUS | LIKELY_MODIFIED | INCONCLUSIVE`
@@ -0,0 +1,148 @@
1
+ ---
2
+ name: fraud-detection
3
+ description: >
4
+ Rapidly discover interpretable transaction-level fraud detection rules from
5
+ tabular payment, transfer, collection, payout, account, or fraud-case data
6
+ (CSV, XLSX, TXT).
7
+ Supports third-party fraud (including stolen credentials and account takeover),
8
+ first-party fraud or deliberate account abuse, and authorized payment scams
9
+ (including APP scams), across card payments, collections, bank transfers, and
10
+ payouts. Supports rapid rule discovery, evidence-qualified metrics,
11
+ domain-appropriate actions, strategy
12
+ impact, and a business report. Use for fraud, scam, mule, account-takeover,
13
+ chargeback, dispute, transfer, collection, or payout risk analysis even when the
14
+ user does not name this skill.
15
+ release-version: 0.45.0
16
+ ---
17
+ **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
18
+ # Fraud Detection
19
+
20
+ Analyze fraud through composable dimensions rather than treating every case as
21
+ card fraud:
22
+
23
+ - **Archetype** — the genuine customer's relationship to the fraud
24
+ - **Mechanism** — how compromise, deception, or abuse occurred
25
+ - **Context** — the product or money-movement surface where a rule fires
26
+
27
+ Run this **10-step** loop:
28
+
29
+ 0. Pre-flight → 1. Profile → 2. Label → 3. Evidence basis → 4. Engineer features →
30
+ 5. Shortlist → 6. Score rules → 7. Map actions + packages → 8. Write report →
31
+ 9. Review
32
+
33
+ **Produce:** operable rules and portfolio impact in a business report.
34
+ **Do not produce:** a black-box model as the main answer. Design and evaluate
35
+ rules; do not deploy or operate a live detection engine.
36
+
37
+ ## Foundational contract
38
+
39
+ - Score one transaction at a declared decision point; retain every applicable
40
+ rule hit. A transaction may trigger zero, one, or several rules.
41
+ - Real-time features combine the current transaction with history available to
42
+ the detector. Include the current transaction in velocity by default.
43
+ - Transaction-triggered rolling aggregates are real-time features. Completed
44
+ entity/period summaries are post-transaction review, not real-time rules.
45
+ - Discover rules rapidly from recent transactions without requiring a
46
+ train/test/holdout split. State the evidence and limits of each metric.
47
+ - Keep the core generic. Load selected domain references for expert candidate
48
+ patterns, not universal diagnoses, mandatory features, or thresholds.
49
+
50
+ > Paths under `references/` are relative to this skill directory. Step detail:
51
+ > [references/workflow.md](references/workflow.md).
52
+
53
+ ## Required references
54
+
55
+ | File | When |
56
+ |---|---|
57
+ | [references/workflow.md](references/workflow.md) | Every step — full procedure |
58
+ | [references/taxonomy.md](references/taxonomy.md) | Step 1; select archetype, mechanism, and context |
59
+ | [references/entities.md](references/entities.md) | Pre-flight and Step 4; entity definitions and matching |
60
+ | [references/enrichment.md](references/enrichment.md) | Pre-flight and Step 4; BIN, IP, FX, phone, bank-account, and ID-document readiness |
61
+ | [references/feature-sql.md](references/feature-sql.md) | Step 4; executable SQL and standard rolling windows |
62
+ | [references/feature-engineering.md](references/feature-engineering.md) | Step 4; shared decision-time rules |
63
+ | [references/report-template.md](references/report-template.md) | Step 8; common report contract and overlay selection |
64
+ | [references/terminology.md](references/terminology.md) | Step 8; fixed terms and language proofread |
65
+ | [references/review-checklist.md](references/review-checklist.md) | Step 9; common and selected-profile checks |
66
+
67
+ After Step 1, read only the selected profile references:
68
+
69
+ | Dimension | References |
70
+ |---|---|
71
+ | Archetype | `references/archetypes/<archetype>.md` |
72
+ | Mechanism | `references/mechanisms/<mechanism>.md` when present |
73
+ | Context | `references/contexts/<context>.md` for every selected context |
74
+
75
+ Read [references/collection-payout-features.md](references/collection-payout-features.md)
76
+ for collection/payout features and review: event sequences, FIFO fund lots, and
77
+ counterparty velocity. This is domain guidance across archetypes, not evidence
78
+ that every rapid flow is knowing abuse.
79
+
80
+ Current packs: archetypes `third-party-fraud`, `first-party-fraud`,
81
+ `authorized-payment-scam`; mechanism `account-takeover`; contexts
82
+ `card-payment`, `payment-collection`, `bank-transfer`, `payout`.
83
+
84
+ ## Progress
85
+
86
+ Track a task plan. One item is `in_progress` at a time.
87
+
88
+ 1. Pass pre-flight
89
+ 2. Select analysis profile
90
+ 3. Formalize label
91
+ 4. Declare discovery and scoring evidence
92
+ 5. Engineer candidate features
93
+ 6. Select shortlist
94
+ 7. Score candidate rules
95
+ 8. Map actions and packages
96
+ 9. Write business report and proofread language
97
+ 10. Independent review
98
+
99
+ Suggested notes: `preflight=…`, `profile=…`, `label=…`, `evidence=…`,
100
+ `allowed/excluded=…`, `shortlist=…`, `N rules, recent|retrospective|subsequent`,
101
+ `packages=…`, `report=…`, `verdict=…`.
102
+
103
+ ## Input
104
+
105
+ CSV / XLSX / TXT; optional outcome column. Input may contain transaction,
106
+ event, or case records, but real-time rule scoring is always transaction-level.
107
+ Resolve transaction identity, retries, duplicates, and lifecycle updates first.
108
+ Other events can supply context; entity/case summaries belong to review.
109
+
110
+ ## Workflow
111
+
112
+ Follow [references/workflow.md](references/workflow.md) for each step. The map:
113
+
114
+ | Step | Do | Gate |
115
+ |---|---|---|
116
+ | 0 Pre-flight | Transaction, entity, enrichment, and label readiness | Missing inputs block affected features or metrics, not all discovery |
117
+ | 1 Profile | Archetype + mechanism(s) + context(s) from taxonomy | Read selected packs before Step 2 |
118
+ | 2 Label | Formalize known positives / negatives / unlabeled | Do not invent negative labels or unsupported metrics |
119
+ | 3 Evidence | Declare discovery/scoring windows and selection overlap | Temporal validation is optional |
120
+ | 4 Features | Engineer transaction-triggered candidates | Current transaction included; no future information |
121
+ | 5 Shortlist | Support / known fraud caught / reach / operability | Explain hypotheses and benign alternatives |
122
+ | 6 Score | occurrence → precision → recall when supported | Name evidence basis and denominators |
123
+ | 7 Actions | Map to context packs + strategy packages | Freeze packages before report |
124
+ | 8 Report | Business report per template; grep terminology banned strings | No review process in the file |
125
+ | 9 Review | Checklist + selected packs | Prefer fresh independent reviewer |
126
+
127
+ ## Output contract
128
+
129
+ | Item | Requirement |
130
+ |---|---|
131
+ | Analysis profile | Archetype, role, consent, technical authentication, mechanism, context, confidence, grain, decision point |
132
+ | Rule metrics | occurrence → precision → recall where supported; discovery/scoring windows and same-sample selection disclosed |
133
+ | Strategy coverage | Union of triggered transactions: count + rate and amount + share, with currency; overlap and incremental coverage |
134
+ | Domain impact | Measures and denominators from selected context packs only |
135
+ | Uncertainty | Proxy labels, immature outcomes, weak identity links, and unresolved attribution stated |
136
+ | Report file | Business content only; no reviewer model, verdict, or repair log |
137
+
138
+ Steps 0–7 are analysis and its entry gate. Step 8 writes the report. Step 9
139
+ reviews it.
140
+
141
+ For step 8, read `{house-style baseDir}/references/analytical-reporting.md` and its
142
+ required references, then use `{write-report baseDir}/SKILL.md`, passing this skill's
143
+ report template, selected context packs, frozen results and required output artifacts.
144
+ Keep all domain metrics, uncertainty disclosures and step 9 checks; report writing does
145
+ not rerun rule discovery or replace the domain review. If a required skill or reference
146
+ is unavailable, report the blocker instead of claiming the report stage is complete.
147
+ For step 9, give the independent reviewer the shared analytical entrypoint and its
148
+ required references as well as the domain checklist and selected packs.
@@ -14,7 +14,7 @@ claim, knowing mule activity, or another subtype.
14
14
 
15
15
  Do not classify a deceived, coerced, compromised, or merely unusual customer as
16
16
  first-party fraud without evidence of participation. Outcome maturity may extend
17
- beyond transaction settlement and must be reflected in the split.
17
+ beyond transaction settlement and must be reflected in label eligibility.
18
18
 
19
19
  ## Feature families
20
20
 
@@ -39,6 +39,7 @@ from a proxy label alone.
39
39
 
40
40
  - Evidence supports knowing participation rather than victimization.
41
41
  - Mule status is not inferred from transaction shape alone.
42
- - Graph features and linked-entity lists are train-fit and point-in-time.
42
+ - Graph features and linked-entity lists declare their discovery evidence and
43
+ are available at the scored decision.
43
44
  - Account restrictions and reporting recommendations identify policy and legal
44
45
  dependencies.
@@ -0,0 +1,47 @@
1
+ # Archetype: third-party fraud
2
+
3
+ The genuine customer did not consent; an external actor used the customer's
4
+ identity, account, credentials, token, or payment instrument.
5
+
6
+ ## Label guidance
7
+
8
+ Prefer confirmed unauthorized-fraud outcomes. Chargebacks, customer claims,
9
+ issuer codes, account compromise flags, and manual decisions may be proxies;
10
+ state their scope and maturity. Do not treat every decline or dispute as fraud.
11
+
12
+ ## Useful evidence
13
+
14
+ - Instrument, account, customer, device, IP, email, phone, and session history
15
+ - Deviation from the genuine customer's prior behavior
16
+ - New or shared identifiers, credential failures, and compromise events
17
+ - Transaction velocity, retries, beneficiary novelty, and location changes
18
+
19
+ Use only evidence available at the selected decision point. A current response,
20
+ claim, chargeback, or investigation outcome is not a pre-decision feature.
21
+
22
+ ## Velocity-pattern catalog
23
+
24
+ These are hypotheses for transaction-triggered aggregates, not diagnoses, mandatory
25
+ Cartesian combinations or prescribed thresholds. Use only available normalized
26
+ identifiers and the decision-time windows in [feature engineering](../feature-engineering.md);
27
+ include the current transaction. Examine support and benign alternatives before action.
28
+ [Entities](../entities.md) explains weak linkage; [feature SQL](../feature-sql.md)
29
+ shows the eligibility and null rules.
30
+
31
+ | Candidate | What it may suggest | Benign alternatives |
32
+ |---|---|---|
33
+ | One email with multiple distinct PANs | Stolen-card use or card testing | Family purchases, shared mailbox, card replacement |
34
+ | One device fingerprint with multiple distinct PANs | Concentrated stolen-card use or card testing | Shared household device, merchant terminal, fingerprint collision |
35
+ | One IP with multiple distinct emails | Coordinated activity | NAT, workplace, VPN, public Wi-Fi |
36
+ | Same PAN, amount and currency repeated | Split payments, repeated charges, or testing | Customer retry, network timeout, recurring purchases; splitting can also use differing amounts |
37
+ | One PAN with multiple distinct names, with name role explicit | Card testing or identity variation | Authorized users, cardholder name variants, gifts or different shipping recipients |
38
+
39
+ A completed-period entity review can investigate these patterns retrospectively,
40
+ but cannot be substituted for the per-transaction features available at a decision.
41
+
42
+ ## Actions and review
43
+
44
+ Actions depend on context: block or authenticate a card payment; terminate or
45
+ reauthenticate a compromised session; hold/review a transfer or payout; restrict
46
+ an account where policy permits. Review that technical authentication is not
47
+ used as proof of genuine-customer consent.
@@ -0,0 +1,151 @@
1
+ # Collection and payout feature candidates
2
+
3
+ Use at Steps 4 and 9 with the selected context packs and the shared feature,
4
+ entity, enrichment, and review references. These are hypotheses, not diagnoses,
5
+ mandatory features, thresholds, or evidence of a person's role. They apply across
6
+ supported archetypes; retain the selected profile and its attribution confidence.
7
+
8
+ ## Decision-time sequence
9
+
10
+ Score the current collection or payout transaction at its declared real-time
11
+ decision point. Include current in eligible transaction counts and sums. Use only
12
+ prior events and attributes available then, plus current attributes; never use
13
+ current or later outcomes. An example journey is payer receipt → funds available →
14
+ beneficiary setup → payout request. At receipt, a later payout, its completion,
15
+ or its outcome cannot be a feature. At payout, prior known receipts and beneficiary
16
+ setup may be features. Record the event timestamp, availability time, order,
17
+ source, identity links and their confidence. Late-arriving records cannot rewrite
18
+ what the earlier scorer knew. Deduplicate lifecycle updates and duplicate deliveries;
19
+ count retries according to the declared transaction-identity policy.
20
+
21
+ Candidates include time since last available receipt, receipt-to-payout sequences,
22
+ new beneficiary followed by a payout, and number of prior receipts before current.
23
+ Fast movement may also reflect scheduled supplier payments, payroll, or a merchant
24
+ settling its sales. A sequence alone does not establish intent or participation.
25
+
26
+ ## FIFO funding attribution
27
+
28
+ FIFO is an accounting attribution convention for candidate features, not a trace
29
+ of actual money or proof of common ownership or intent. Scope lots to the
30
+ balance-owning ledger account and currency. Use the availability timestamp of
31
+ each eligible incoming receipt, then the actual deterministic order known to the
32
+ ledger for ties. Never pool currencies or invent a tie-break order. If account,
33
+ currency, available balance, receipt availability, or order is unknown, ask for
34
+ the missing semantics and mark affected features unavailable.
35
+
36
+ Reconstruct the state known immediately before the current payout debit, including
37
+ prior committed debits and existing reservations. For the current payout, propose
38
+ an allocation oldest available lot first, consuming partial lots and as many lots
39
+ as needed. This is a preview: do not debit the candidate first and then allocate
40
+ it again. For a release of an existing reservation, include its own reserved lots
41
+ in the preview without allocating them a second time; exclude other reservations.
42
+ Commit or release allocations only according to declared ledger lifecycle rules.
43
+ Rejected or failed attempts before any reservation/debit consume no funds. A
44
+ failure after a committed debit does not restore its lots: keep them consumed
45
+ until an explicit reversal/return entry makes funds available under the declared
46
+ policy. Restore reservations only when the ledger releases them; failure alone
47
+ is not a release. Pending reservations cannot fund another payout. Ask which
48
+ statuses reserve, debit, fail, and release, and when;
49
+ if undefined, leave affected features unavailable rather than guessing. Reconcile
50
+ retries and duplicate events against the same reservation/debit.
51
+
52
+ Reconcile opening balance and known available lots to the ledger. Do not truncate
53
+ FIFO state to a rolling velocity window: old unspent lots can still fund current
54
+ payouts. Carry forward reconciled remaining lots or disclose missing history.
55
+ Report unmatched
56
+ opening balance and unknown or truncated history separately; do not invent source
57
+ lots or treat unknown funding as zero. If ledger balance and reconstructable lots
58
+ differ, expose both the matched and unmatched amounts and ask how the difference
59
+ should be handled. An insufficient balance or incomplete history is not evidence
60
+ of fraud. FX, fees, reversals and refunds require explicit point-in-time ledger
61
+ entries and allocation semantics; do not assume ordinary inflows or rewrite a
62
+ past decision using later corrections. Do not silently convert or pool currencies.
63
+
64
+ For current payout amount `P > 0`, let `a_i` be each proposed matched amount,
65
+ `age_i` the elapsed time from lot availability to the decision, and `M = Σa_i`.
66
+ Report `M`, `P - M` as unmatched, and `M / P` as attribution coverage. Define:
67
+
68
+ - Matched weighted fund age: `Σ(a_i × age_i) / M` when `M > 0`; otherwise unknown.
69
+ Label it matched-only and report coverage alongside it.
70
+ - Recent funds share for a declared elapsed window: `Σ(a_i for lots available
71
+ in (t − window, t]) / P`. Report coverage; unmatched is unknown, not known old
72
+ funding. With incomplete attribution, this is the known recent share, not the
73
+ full share.
74
+ - Distinct known funding counterparties among matched lots: count non-null,
75
+ normalized payer keys; report matched amount with known payer divided by `P`,
76
+ plus unknown-payer and unmatched amounts. A missing key is not a counterparty.
77
+ State entity type, role, linkage method and confidence; do not infer a person
78
+ from an account key or pool nulls.
79
+
80
+ ### Worked example
81
+
82
+ At payout decision time `t`, one USD ledger account has two available receipts:
83
+ A: $60 available 10 hours ago from known payer X; B: $50 available 2 hours ago
84
+ with unknown payer. No other balance or reservations exist. A $90 payout previews
85
+ $60 from A and $30 from B, leaving $20 of B. The $110 opening amount equals
86
+ $90 allocated plus $20 remaining. Matched coverage is $90/$90 = 100%; weighted
87
+ fund age is `(60 × 10 + 30 × 2) / 90 = 7.33 hours`. For a 6-hour window,
88
+ recent share is $30/$90 = 33.33%. Distinct known payers = 1; known-payer coverage
89
+ is $60/$90 = 66.67%, and $30 has unknown payer. These are proposed allocations,
90
+ not proof of where the payout's money went.
91
+
92
+ If a separate $130 candidate is scored against the same $110 pre-debit balance,
93
+ FIFO matches $60 + $50 = $110 and leaves $20 unmatched: coverage is 84.62%.
94
+ The known recent share is $50/$130 = 38.46%, not $50/$110. Weighted age of the
95
+ matched portion is `(60 × 10 + 50 × 2) / 110 = 6.36 hours`; known-payer coverage
96
+ is $60/$130 = 46.15%. Report the $20 shortfall and do not infer a funding source
97
+ or a payout outcome. If a reservation or an unknown opening balance exists, the
98
+ example's inputs and results change according to the declared ledger semantics.
99
+
100
+ ### Lifecycle example
101
+
102
+ Given $100 available in one ledger account/currency, reserving $70 leaves $30
103
+ spendable and $70 reserved. Committing that debit leaves $30 spendable, $0
104
+ reserved, and $70 consumed. A later payout-failed notification without a return
105
+ entry leaves those amounts unchanged; another $40 request has a $10 shortfall.
106
+ If the ledger later posts a $70 return as available, spendable balance becomes
107
+ $100. Whether returned funds restore original lot age or create a new available
108
+ lot is a declared ledger policy, not inferred from the failure notification.
109
+ Before the return, conservation is $100 = $30 remaining + $70 consumed; after
110
+ it, account reconciliation is $100 original + $70 returned − $70 debited = $100.
111
+ Do not both undo consumption and add the same return as a second credit.
112
+
113
+ ## Counterparty velocity
114
+
115
+ Choose only useful combinations of direction, entity type and window. Name the
116
+ balance-owning account, inbound payer or outbound beneficiary, and whether each
117
+ key is an account, person, business, instrument or other declared type. Keep
118
+ inbound and outbound roles separate, and disclose deterministic versus probabilistic
119
+ links and confidence. Unknown identifiers are not pooled or counted as distinct.
120
+
121
+ For each direction, distinguish (1) transaction count and same-currency amount
122
+ sum for the same account–counterparty pair from (2) distinct inbound payers or
123
+ distinct outbound beneficiaries per balance-owning account. Include the current
124
+ transaction in eligible counts, sums and distinct values when its key is known.
125
+ Missing keys yield unknown for the affected pair feature; report missing-key
126
+ coverage for distinct counts. Missing amount or currency makes the affected sum
127
+ unknown; do not silently omit it or sum currencies. Follow the shared as-of
128
+ availability and tie-order rules and `(t − window, t]` boundaries.
129
+
130
+ - `counterparty_pair_txn_count_<window>`: count on the declared account/payer
131
+ or account/beneficiary pair, with direction encoded in the specification.
132
+ - `account_inbound_payer_distinct_count_<window>` and
133
+ `account_outbound_beneficiary_distinct_count_<window>`: distinct role-specific
134
+ keys for the same balance-owning account. Record entity type in the spec.
135
+
136
+ The standard windows are 1m, 5m, 15m, 30m, 1h, 2h, 6h, 24h, 2d, 7d,
137
+ 14d, 21d and 30d; a day is 86,400 seconds. For example, a high count for one
138
+ account–payer pair differs from many distinct payers; a marketplace may naturally
139
+ have both many payers and many beneficiaries. Frequent payments to one beneficiary
140
+ may be routine supplier settlement. Treat these as candidates with benign
141
+ alternatives, not proof of fraud or a customer role.
142
+
143
+ ## Step 9 checks
144
+
145
+ Check that sequence inputs were known at the decision, current is counted once,
146
+ and no later outcome leaks into an earlier score. Check account/currency scope,
147
+ actual lot order, pre-debit preview, partial allocations, reservation lifecycle,
148
+ conservation, unknown history and coverage, and explicit nonordinary ledger
149
+ semantics. Check pair versus distinct direction, entity linkage confidence and
150
+ benign alternatives. Escalate undefined business or ledger semantics rather than
151
+ inventing a policy; independent review remains owned by the reviewer.
@@ -1,8 +1,9 @@
1
1
  # Context: bank transfer
2
2
 
3
- Typical grains are beneficiary creation, transfer instruction, transfer
4
- execution, recall, or case. Decision points may be beneficiary setup,
5
- pre-execution, or post-transfer investigation.
3
+ Score one transfer transaction, normally at instruction or pre-execution.
4
+ Beneficiary creation supplies prior context; recall and case records supply
5
+ outcomes or post-transaction review. Do not score beneficiary creation as a
6
+ transaction.
6
7
 
7
8
  ## Features
8
9
 
@@ -0,0 +1,70 @@
1
+ # Context: card payment
2
+
3
+ Score one payment transaction, normally at pre-authorization. Authorization
4
+ attempts need a retry policy; clearing and dispute records supply lifecycle
5
+ context or post-transaction review, not additional scored copies.
6
+
7
+ ## Reported-fraud labels
8
+
9
+ For reported-fraud rule analysis, combine available network/acquirer fraud reports
10
+ (such as Worldpay DART/340FRD) with fraud-category disputes, including pre-dispute
11
+ resolution records. A transaction is positive if either source reports it. Do not
12
+ restrict fraud labels to financially settled or first-chargeback stages. This
13
+ label is reported fraud, not necessarily independently confirmed fraud or loss.
14
+ An explicit task-specific label definition overrides this default.
15
+
16
+ - Identify fraud from documented category/reason mappings, not the mere presence
17
+ of a dispute or a pre-dispute stage. Non-fraud quality, service and clerical
18
+ disputes are not positive solely because they appear in the dispute file.
19
+ - Link each source to a unique transaction using corroborated references and
20
+ original transaction attributes. Preserve unmatched/ambiguous records and
21
+ conflicting evidence instead of forcing a match.
22
+ - Union positives by transaction ID. Repeated reports, multiple dispute stages,
23
+ and DART/dispute overlap contribute one positive transaction, not extra cases.
24
+ - Retain evidence provenance and lifecycle. A later reversal or recovery does not
25
+ erase an earlier fraud allegation from a reported-fraud label; do not call its
26
+ disputed amount a confirmed or unrecovered loss.
27
+ - Report DART-only, dispute-only, overlap and union counts in each scoring window,
28
+ plus pre-dispute/stage coverage. A transaction may appear in several stage
29
+ subsets, so do not sum those subsets as unique fraud transactions.
30
+ - Network-metric exclusions (for example excluding certain pre-disputes from a
31
+ scheme monitoring ratio) do not define the fraud-detection positive class.
32
+ Keep regulatory/scheme ratio calculations separate from rule labels.
33
+ - Absence from both feeds remains unlabeled unless a justified negative
34
+ definition exists. Delayed reports affect capture completeness, not whether an
35
+ already observed fraud pre-dispute qualifies as positive.
36
+ - These later reports supply evaluation labels only. Historical fraud evidence
37
+ can enter a real-time feature only after it became available to the detector;
38
+ never leak the current transaction's future dispute into its own features.
39
+
40
+ ## Features
41
+
42
+ Amount and currency, network, card type, token/PAN-derived identity, BIN, country,
43
+ channel, entry method, MCC, merchant, device, customer history, and prior-event
44
+ velocity. A masked PAN may be a weak identity key.
45
+
46
+ CVV, AVS, authorization response, and 3DS result are same-response or later
47
+ fields unless the chosen decision point explicitly occurs after them. Issuing
48
+ bank name may be derived; prefer BIN for pre-authorization lists.
49
+
50
+ Record discovery evidence and versions for BIN, country, merchant, and other
51
+ lists. Reference rates must have been available at the scored decision; newly
52
+ discovered lists are prospective candidates. Tiny lists remain monitor-only.
53
+
54
+ ## Actions and impact
55
+
56
+ Actions: block, require 3DS/additional authentication, route, manual review, or
57
+ monitor. For 3DS scenarios, failed authentication does not enter the subsequent
58
+ authorization denominator. Report authorization success and absolute approval
59
+ change only when measured or under explicit pass/conversion assumptions.
60
+
61
+ ## Review overlay
62
+
63
+ - Available DART/network fraud reports and fraud disputes are unioned by
64
+ transaction, including fraud pre-disputes, with source overlap disclosed.
65
+ - Non-fraud disputes are not positive; lifecycle reversals are not confused with
66
+ absence of an allegation or confirmed loss.
67
+ - Current CVV/AVS/auth response/3DS result respects decision timing.
68
+ - BIN lists declare discovery evidence and causal availability; issuer names
69
+ are operable only if available live.
70
+ - 3DS and authorization denominators are explicit.