@1aboveio/skills 0.14.0 → 0.16.1

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

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

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

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

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

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

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

@@ -0,0 +1,175 @@
+# Fraud-analysis workflow (steps 0–9)
+
+Called from [SKILL.md](../SKILL.md). Paths below are relative to the skill root.
+
+## 0 — Pre-flight
+
+Inspect the input, requested target, and label provenance before planning a
+supervised analysis. Record:
+
+```yaml
+label_provenance: file-column | user-defined | absent
+positive_definition: ""
+negative_definition: ""
+unlabeled_definition: ""
+preflight_status: pass | needs-user-input | descriptive-only | blocked
+```
+
+- Confirm the file is readable and identify its row grain, candidate time field,
+  outcome/label fields, and requested positive definition.
+- When the positive label comes from an existing row-level outcome column, map
+  its positive value(s). Assume the rest of the mature analysis population is
+  negative, except explicit missing, pending, unknown, or unlabeled states.
+  State this assumption and show the observed values to the user when ambiguous.
+- When the user defines the positive label as a condition or derived rule,
+  require the user to define the negative condition during pre-flight. Do not
+  infer `NOT positive` as negative. Ask one focused clarification and set status
+  to `needs-user-input` until answered.
+- Rows matching neither class, both classes, explicit unknown states, or an
+  immature outcome window are unlabeled.
+- If no usable positive and negative definitions exist, offer descriptive
+  segmentation without precision/recall, or block supervised analysis.
+
+Do not proceed to the supervised workflow until pre-flight passes. A
+`descriptive-only` analysis may select a profile and explore segments, but it
+must not compute precision, recall, lift, or supervised strategy performance.
+Profile clarification may be grouped into the same user question when both
+label and attribution inputs are missing.
+
+## 1 — Select analysis profile
+
+Read [taxonomy.md](taxonomy.md). Record:
+
+```yaml
+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
+mechanisms: []
+contexts: []
+subtype: null
+attribution_confidence: confirmed | probable | proxy | unknown
+event_grain: ""
+decision_point: ""
+```
+
+- Select exactly one primary archetype. Select one or more mechanisms and
+  contexts when the data supports them.
+- Customer consent and technical authentication are separate facts. Passed
+  login, MFA, or session checks do not prove genuine-customer consent.
+- `APP scam` is a subtype of `authorized-payment-scam` in a `bank-transfer`
+  context; it is not a synonym for first-party fraud.
+- If victimization versus knowing participation is unresolved, use
+  `unclassified`. Do not silently force attribution.
+- If multiple archetypes are confirmed, run separate labels, rules, metrics,
+  and impact sections. Never blend them into one positive class.
+
+Read the selected archetype, mechanism, and context references before Step 2.
+
+## 2 — Formalize label
+
+- One primary label per archetype analysis. Confirmed outcomes are ground truth;
+  proxies must be identified as proxies.
+- Carry forward the pre-flight provenance and class definitions; do not discover
+  the negative class here.
+- Validate the pre-flight mapping against observed rows and record the resulting
+  positive, negative, and unlabeled counts.
+- If the mapping is incomplete or contradictory, return to pre-flight with
+  `needs-user-input`; do not ask for or invent a negative class in this step.
+- Derive labels only from supplied data and documented business meaning. Positive
+  and negative conditions must be disjoint. Rows matching neither, both, or an
+  immature/pending state are unlabeled and excluded from supervised metrics.
+- Record positive definition/count, negative definition/count, unlabeled
+  definition/count, base rate among labeled rows, maturity window, exclusions,
+  and attribution confidence.
+- Exclude the label, synonyms, investigations, recalls, disputes, or other later
+  outcomes from features when unavailable at the selected decision point.
+- For delayed outcomes, ensure enough observation time or mark recent rows as
+  immature rather than negative.
+- Do not continue to precision, recall, or supervised rule scoring until both
+  positive and negative classes are defined.
+
+## 3 — Freeze temporal validation
+
+- Freeze the cut before feature work. Train is earlier; holdout is later.
+- Do not random-shuffle rows or use random k-fold as headline validation.
+- History and graph snapshots contain prior events only.
+- No time column means full-sample descriptive analysis; mark metrics
+  **unvalidated**.
+
+## 4 — Engineer candidates
+
+Read [feature-engineering.md](feature-engineering.md) and all selected
+profile packs.
+
+- Declare event grain and decision point before assessing columns.
+- Classify fields as allowed now, excluded for zero variance, excluded for
+  timing, excluded for leakage, or context-only.
+- Build thresholds, rate lists, graph lists, and watchlists on train only.
+- Prefer interpretable conditions with explicit units and windows.
+- Do not invent columns, identity links, consent, intent, or actor attribution.
+
+## 5 — Select shortlist
+
+Use train only: lift, support, stability, operability, and meaningful
+interactions. Keep tiny or attribution-uncertain spikes for monitoring.
+
+## 6 — Score rules
+
+State explicit conditions, event grain, units, windows, and decision point.
+Headline holdout metrics use this order:
+
+**occurrence → precision → recall**
+
+Train metrics are debugging evidence only. If outcomes are value-bearing, also
+measure captured positive amount without replacing count-based metrics.
+
+## 7 — Map actions and packages
+
+Use actions from the selected context packs; there is no universal 3DS action.
+
+| Metric and evidence profile | Shared guidance |
+|---|---|
+| High precision, stable, severe impact | Consider the context's strongest preventive action |
+| Higher recall, moderate precision | Add verification, review, warning, hold, or friction |
+| Weak, unstable, small-N, uncertain attribution | Monitor or investigate |
+
+- Legal, regulatory, policy, and operational authority constrain account holds,
+  freezes, rejects, beneficiary blocks, and reporting.
+- Keep individual rules separate from multi-rule **strategy packages**.
+- Freeze default and comparison packages before report writing.
+- For each package compute triggered count/rate and amount/share, then precision
+  and recall, plus the context-specific customer, operations, conversion, delay,
+  and loss measures required by its pack.
+
+## 8 — Write business report
+
+Read [report-template.md](report-template.md),
+[terminology.md](terminology.md), and selected profile packs.
+
+Use reader order:
+
+执行摘要 → 抽样、分析画像与标签 → 规则发现 → 策略整体影响 → 特征 → 附录
+
+- Include the analysis profile and actor attribution near the start.
+- Report only domain-appropriate actions, denominators, and impact KPIs.
+- Strategy impact always includes count/rate and amount/share, then precision
+  and recall. Add only the selected contexts' required impact measures.
+- Do not present scenario estimates or proxy-label value as measured loss saved.
+- Save to a path such as `reports/fraud-analysis/<scope>.md`.
+- Before finishing: grep the report for banned strings in
+  [terminology.md](terminology.md) and fix language only (not numbers,
+  BIN lists, or thresholds).
+
+## 9 — Independent review
+
+Read [review-checklist.md](review-checklist.md) and selected packs.
+
+- Review the common method and presentation contract.
+- Apply checks from every selected archetype, mechanism, and context pack.
+- Auto-fix mechanical issues only. Do not silently change attribution, label,
+  customer role, or action severity.
+- Prefer a fresh independent reviewer. If unavailable, use a fresh same-session
+  checklist and disclose that only in the chat delivery note.
+- Deliver the business report plus a short note with verdict, fixes, and open
+  judgment issues. Keep review process details out of the report.

package/skills/payment/payment-analysis/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO

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

@@ -0,0 +1,127 @@
+---
+name: payment-analysis
+description: >
+  Produce a visualized payment overview from authorization + settlement
+  extracts (optional chargebacks): executive summary, top statistics, payment
+  journey Sankey, and topics (volume, WoW trend, auth rate, BIN-country
+  contribution, decline-by-reason, decline-by-country). Amounts report in USD
+  (Forex Service daily conversion). Chargebacks use Visa same-month and
+  Mastercard lagged 拒付率. 运营影响 is 3DS / 风控拦截 / soft-decline retry
+  only. Use whenever the user asks for payment overview, auth-rate analysis,
+  decline mix, BIN/issuer-country contribution, settlement GMV, payment journey,
+  Sankey funnel, FX-to-USD, chargeback rate, 运营影响, or "business analysis of
+  transactions" — even if they do not say payment-analysis. Do NOT use for
+  supervised fraud-rule mining (that is fraud-analysis).
+---
+
+# Payment Analysis
+
+Descriptive payment-funnel analytics with charts. Explains what happened in the
+book. Does not invent fraud rules or claim loss saved.
+
+Use authorization **and** settlement when both files exist. Chargebacks are
+optional topic fuel, not required for the journey core.
+
+| Layer | Typical file | Row grain |
+|---|---|---|
+| Authorizations | `Authorizations_*.csv` | one auth attempt |
+| Settlements | `Sales-and-refunds_*settlements*.csv` | one sale or refund |
+| Chargebacks | `Chargebacks_*.csv` | one dispute (optional) |
+
+**Produce:** Markdown + preferred Chinese/bilingual HTML under
+`reports/payment-analysis/`.  
+**Do not produce:** supervised precision/recall packages (`fraud-analysis`).
+
+Read the playbook for the step you are on. Paths under `references/` are
+relative to this skill.
+
+## Workflow
+
+Follow these steps in order.
+
+### 0 — Pre-flight
+
+Read [event-layers.md](references/event-layers.md). Record layers present and
+missing, paths, time fields, currencies, and which journey checkpoints have
+usable columns. Amount reporting is USD: read [fx.md](references/fx.md) before
+any amount KPI (all-USD books still write `金额均为 USD` and do not call Forex).
+
+### 1 — Window and segments
+
+Freeze the analysis window (defaults in event-layers.md). Segment by BIN
+country, card product, response message/code, settlement type when present.
+
+### 2 — KPIs
+
+Compute auth + settlement metrics from [metrics.md](references/metrics.md).
+Convert non-USD amounts per [fx.md](references/fx.md) before any sum or share.
+If chargebacks are present, monthly 拒付率 follows
+[chargebacks.md](references/chargebacks.md) (Visa same-month, Mastercard lagged,
+skip empty brand-months, no blended Visa+Mastercard ratio).
+
+### 3 — Journey Sankey
+
+Build **count** flows with [journey.md](references/journey.md). Join sales to
+approved auths on `Order ID`. Footnote unjoined refunds. Skip risk/3DS nodes
+when authentication fields are empty; caption the skips.
+
+### 4 — Write outputs
+
+Structure and chapter minima:
+[report-template.md](references/report-template.md). Chart marks:
+[visualization.md](references/visualization.md). English/Chinese terms:
+[terminology.md](references/terminology.md). 运营影响 only from
+[auth-rate-actions.md](references/auth-rate-actions.md) when the extract
+supports the trigger.
+
+```text
+reports/payment-analysis/<scope>_overview.md
+reports/payment-analysis/<scope>_overview.zh.md
+reports/payment-analysis/<scope>_overview.zh.html
+```
+
+HTML is preferred when there are charts. Glossary applies to headings, KPI
+labels, legends, and Sankey skip chips.
+
+### 5 — Language proofread
+
+Grep every report file for the banned strings in
+[terminology.md](references/terminology.md). Replace hits using that table.
+Do not change numbers, joins, or chart data.
+
+### 6 — Sanity check
+
+- [ ] Structure is summary → top stats → Sankey → topics → 运营影响
+- [ ] Auth + settlement both used when both files exist
+- [ ] Sankey skips unavailable risk/3DS checkpoints and says so
+- [ ] Count/amount are bars; rate is a line; dual axes when combined
+- [ ] Amount axes/legends include currency (`授权尝试金额 USD`, …)
+- [ ] No supervised fraud-rule metrics
+- [ ] Non-USD amounts converted per fx.md; all-USD books say 金额均为 USD
+- [ ] Chargeback monthly rates skip empty brand-months; no blended Visa+MC ratio
+- [ ] 运营影响 only from auth-rate-actions.md when triggered
+- [ ] Language matches terminology.md; banned strings have no unexplained hits
+
+## Boundary with fraud-analysis
+
+| Need | Skill |
+|---|---|
+| Volume, journey Sankey, auth rate, decline mix, settlement overview, 运营影响 routing | `payment-analysis` |
+| Proxy/confirmed fraud labels, holdout precision/recall, 3DS/block **packages** | `fraud-analysis` |
+
+Routing 3DS / 风控拦截 / retry from this extract is not a fraud-analysis rule
+package.
+
+## Reference index
+
+| Need | Read |
+|---|---|
+| Grains, joins, windows | [event-layers.md](references/event-layers.md) |
+| USD conversion | [fx.md](references/fx.md) |
+| KPI formulas | [metrics.md](references/metrics.md) |
+| Visa / Mastercard 拒付率 | [chargebacks.md](references/chargebacks.md) |
+| Sankey checkpoints | [journey.md](references/journey.md) |
+| Chart marks | [visualization.md](references/visualization.md) |
+| Report chapters | [report-template.md](references/report-template.md) |
+| 运营影响 | [auth-rate-actions.md](references/auth-rate-actions.md) |
+| Language / banned strings | [terminology.md](references/terminology.md) |