@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/risk-compliance/payment-analysis/references/chargebacks.md

@@ -0,0 +1,208 @@
+# Chargeback / dispute rate (normal vs pre-dispute; Visa vs Mastercard)
+
+Topic **4.8 拒付 / 争议**. Put the Visa / Mastercard formulas as a **note
+under the monthly rate chart**. Count rates follow card-network monitoring
+programmes, **not** origination-month vintage and **not** a blended
+Visa+Mastercard ratio.
+
+Official Visa and Mastercard rulebooks are acquirer-gated. The formulas
+below are the processor restatements used in production monitoring
+(Stripe, Braintree). Caption the report as **network-style estimates
+from this extract**, not as a Visa/Mastercard identification notice.
+
+## Fraud & chargeback period for section 4.8 (default 12 months)
+
+Twelve months is the step-0 fraud & chargeback period default. When the user
+picks N months, read every "12" below as N, "preceding 11" as "preceding
+N-1", `M-11` as `M-(N-1)`, `M-12` as `M-N`, and "13" as N+1.
+
+Every report's section 4.8 covers **the report month M and the preceding 11
+calendar months**, inclusive: `M-11` through `M`. This applies to daily, weekly,
+monthly, and multi-month reports alike. Use the explicitly requested report month;
+otherwise use the month containing the main report's end date. The explicit
+report month takes precedence if those two months differ. Do not anchor to
+today, the latest dispute file, or the first available historical month.
+
+Example: an October 2026 report, including an October 1-11 report, displays
+November 2025 through October 2026. Determine month offsets with calendar
+arithmetic, not a 365-day subtraction. Record two separate times:
+
+- Event cutoff: the history cutoff defined in [event-layers.md](event-layers.md)
+  Window selection (step 4 there); this file does not redefine it. Record both
+  the requested and effective cutoff when capped. If the effective cutoff
+  precedes an explicit user-given M, raise it in the step-0 question; in a run
+  where no one can answer, keep that M, label it empty or partial, and disclose.
+  A default M never needs this: it comes from the main period, which already
+  fell back to the latest month with data. Do not invent future data.
+  Include cases by stage-opening received date and sales by transaction/capture
+  date, never after this cutoff. Label M month-to-date when not complete.
+  Establish and record the source/reporting timezone before converting timestamps
+  or assigning months. Date-only source labels may be used in their stated source
+  calendar without claiming a timezone; naive timestamps with no verified timezone
+  may likewise retain their recorded calendar labels, explicitly disclosed.
+  Do not silently normalize these to UTC. If a requested timezone conversion or
+  cross-source month/cutoff alignment cannot be established, mark the affected
+  cells unresolved. An inclusive date cutoff ends at the next local midnight,
+  using a half-open interval and calendar arithmetic that respects DST.
+  Forex's UTC Rate Date is not the reporting-timezone policy.
+- Evidence snapshot: retain source hashes, export timestamps when provided, and
+  the input-selection timestamp. Later exports may correct earlier events.
+  Use the latest verifiable correction in the supplied snapshot and disclose
+  that historical results are restated, not frozen as originally known. Do not
+  use filename ordering alone to choose a revision. If revision order or event
+  dating cannot be established, mark affected metrics unresolved and preserve
+  the conflicting evidence rather than choosing a row.
+
+This separate history applies to monthly stage counts/amounts, reason-category
+context, and network-style rates. A main-period-only stage summary may be added
+but must be labeled separately; it does not replace the 12-month history.
+
+Gather all authorized historical dispute and settlement exports for the same
+portfolio scope. Numerators require received cases in `M-11` through `M`. Visa
+sales require those same months. Mastercard's first displayed month requires
+sales from `M-12`, so its denominator inputs may span **13 calendar months**.
+Do not broaden the merchant/MID scope to obtain a denominator or infer missing
+sales from approvals. Record every historical input and its date coverage.
+
+Separate repeated export snapshots from genuine stage-opening events. Use stable
+sale/event identifiers for sales; for cases use the processor's linked case ID,
+stage-opening event ID/type, and received date. Count each distinct pre-dispute
+opening once in its received month and each formal chargeback opening once in
+its own received month. A pre-dispute escalating under the same case ID can
+therefore appear in both stage series; these stage counts are not additive unique
+case counts. A later status update, reversal, loss notice, or repeated export is
+not a new opening. Deduplicate only the same event, not all rows of a case ID.
+
+Preserve links when a processor assigns a new identifier on escalation. Use its
+dictionary and explicit linkage/revision fields, not amount, reason, or timing
+similarity, to identify events and revisions. Apply verified corrections to the
+same event under the restatement policy above. If the extract cannot distinguish
+an opening from a status snapshot, establish the stage/date or reconcile linked
+identities, keep it unclassified/unresolved and mark affected rate cells `N/A`;
+do not silently collapse a genuine opening or count an update as another case.
+Explain which cells are affected. Keep independently supported cells computable.
+
+Keep **all 12 months** on the ascending calendar-month axis and in the supporting
+table, even if only a few months have data. For each brand/stage/month, show case
+count and amount USD, rate numerator, sale denominator, denominator month,
+observed date ranges, and coverage status. Distinguish missing history from
+observed no-case months. Use `N/A` or a gap with an explanation when the rate
+cannot be drawn under the point rules below; never fabricate history or zero
+rates. Partial inputs may yield explicitly labeled extract-based estimates,
+not complete-month monitoring results; disclose missing dates and small
+denominators. A min/max event-date range does not prove continuous coverage.
+
+If historical inputs cannot be obtained, retain the full 12-month coverage table
+and state the missing layers/months. If no valid rate points remain, show the
+12-month axis as an empty rate plot with a no-data caption, not invented points.
+If the chargeback layer is absent entirely, keep a section 4.8 history-coverage
+notice and the 12-month coverage table; do not invent a case-stage breakdown.
+
+## Classify case stage first
+
+Before calculating rates, classify each row from an explicit processor or
+network case-stage/type/status field:
+
+- **Normal chargeback / dispute**: a formally opened chargeback/dispute.
+- **Pre-dispute**: explicitly identified as pre-dispute, RDR, CDRN, early
+  resolution, or the processor's equivalent pre-dispute product.
+- **Unclassified**: the extract does not reliably identify the case stage.
+
+Use the processor's data dictionary when labels are unclear. Do not infer
+pre-dispute status from reason code, amount, timing, outcome, or free-text
+description alone. Report counts and amounts for all three classes separately;
+never silently treat pre-dispute or unclassified rows as normal chargebacks.
+Unclassified cases appear in count/amount tables, not the normal or pre-dispute
+rate series; any optional all-case descriptive rate must be labeled separately.
+
+If no reliable classification field exists, report the separation as
+unavailable. An all-case Visa dispute rate may be shown as descriptive only,
+but it must not be called a normal chargeback rate or VAMP-style estimate.
+
+## When a point is drawn
+
+A monthly point for a brand and case-stage series is drawn **only if**
+
+- numerator for that specific series **received** in that calendar month > 0, and
+- denominator (sales count for that brand, month as defined below) > 0.
+
+Otherwise **omit the point**. Do not plot `0`. Do not invent a prior-month
+sale count. Keep its month label and explain the gap in the 12-month table.
+Do not connect lines across missing month points. If a series has no drawable
+points, omit its line; if no series remain, retain the empty 12-month rate plot
+and coverage table with an explicit no-data caption. Keep available case-stage
+and reason-category bars.
+
+## Formulas (count)
+
+Numerators use cases **received** in calendar month `M` (`Chargeback date`),
+`Payment method` = that brand. Do not use original transaction month. Apply
+the case-stage classification before counting.
+
+| Brand / series | Programme alignment | Rate |
+|---|---|---|
+| Visa normal chargeback | VAMP dispute/sales timing (same month) | `Normal_CB_Visa(M) / Sales_Visa(M)` |
+| Visa pre-dispute | Descriptive; excluded from VAMP | `PreDispute_Visa(M) / Sales_Visa(M)` |
+| Mastercard normal chargeback | ECP / ECM chargeback timing (lagged sales) | `Normal_CB_MC(M) / Sales_MC(M−1)` |
+
+`Sales_*` = settlement type Sale, that brand, **transaction/capture month**.
+Do not mix refunds into the denominator.
+
+Mastercard **must** use the previous calendar month’s sales. If `M−1`
+sales are missing from the extract, skip Mastercard for month `M`. Keep any
+Mastercard pre-dispute rows separate from its normal chargeback numerator; this
+skill does not calculate a Mastercard pre-dispute rate unless the user asks.
+
+## Visa notes (do not over-claim VAMP)
+
+Since 2025-04 Visa folded VDMP/VFMP into **VAMP**. Full VAMP Count is
+`opened Visa chargebacks (TC15) + reported fraud (TC40 EFW)`, same-month
+sales in the denominator. **Pre-dispute cases are not opened chargebacks and
+must be excluded from the TC15/VAMP-style numerator.** This skill's extract
+usually has chargebacks only → report **Visa normal 拒付率 = normal Visa CB
+count / Visa same-month sales**, plus **Visa pre-dispute rate = Visa
+pre-dispute count / Visa same-month sales** as a separate descriptive series.
+Do not add the two series together. Do not label the normal rate “VAMP ratio”
+unless TC40/EFW is present and the extract supports the full VAMP definition.
+
+VAMP also has volume and enumeration legs; those are out of scope here.
+
+## Mastercard notes
+
+ECP (ECM / HECM) uses **both** a count threshold and the lagged rate.
+This report draws the **rate** series only. Do not say the merchant is
+“in ECM” from the extract.
+
+EFM is a different (fraud-reason + 3DS mix) programme; do not substitute
+it for ECP.
+
+## Amount rate (optional footnote)
+
+`abs(dispute amount) / sale amount` with the **same month alignment as
+the count rate** for that brand. Keep normal and pre-dispute amounts separate.
+Secondary; the line chart is count %.
+
+## Window caveat
+
+A short extract (e.g. 22 days of August plus a handful of July sales)
+cannot produce a Mastercard lagged rate for August unless July Mastercard
+sales exist, and cannot produce Visa July if July CBs are absent. Follow
+the skip rules; do not pad. A short main report does not shorten section 4.8's
+12-month axis. List missing historical inputs and keep partial-data estimates
+distinct from complete-month programme monitoring.
+
+## Sources
+
+- Stripe, *Dispute and fraud card monitoring programs*: Visa uses
+  disputes/fraud vs **same-month** payments; Mastercard uses
+  disputes/fraud vs **previous-month** payments; both assign the CB to
+  the month it was **received**.
+  https://docs.stripe.com/disputes/monitoring-programs
+- Braintree, *Visa Acquirer Monitoring Program (VAMP)*: VAMP ratio =
+  VAMP Count / **same-month** Visa sales count
+  (example: August count / August sales).
+  https://developer.paypal.com/braintree/articles/risk-and-security/card-brand-monitoring-programs/visa-programs/visa-dispute-monitoring-program
+- Chargebacks911 primer on Mastercard ECM rate: chargebacks in the
+  **current** month / Mastercard transactions in the **previous** month
+  (April 10,000 sales and May 90 CBs → May rate 1%).
+  https://chargebacks911.com/mastercard-chargebacks/mastercard-excessive-fraud-chargeback-monitoring-programs/mastercard-ecm-program-how-to-calculate-your-mastercard-chargeback-rate/

package/skills/risk-compliance/payment-analysis/references/chinese-polish.md

@@ -0,0 +1,51 @@
+# Chinese polish guardrails
+
+The final step runs `polish-cn` (`{polish-cn baseDir}/SKILL.md`) after `editorial-review`. This
+file holds what `polish-cn` needs from this skill: the blocks, the protected terms, and the
+guardrails to send with the brief.
+
+## Blocks
+
+Polish the narrative source the renderer reads, not the rendered `.zh.md` or `.zh.html`. Write
+`blocks.json` with one block per Chinese text block (`id` = the narrative block id, `text`, `sha`),
+with the English text of the block as `en`. Apply accepted text to the narrative source, then
+re-render every Chinese artifact from it. Never send tables of facts, chart payloads, raw payment
+records, card or account identifiers, or credentials.
+
+## Protected terms
+
+Pass these with `--protect-file`, plus every term in [terminology.md](terminology.md):
+
+```text
+授权尝试
+授权成功
+授权成功率
+授权拒绝
+疑似欺诈
+拒付
+拒付率
+预争议
+结算
+退款
+USD
+```
+
+## Guardrails
+
+Send with the brief:
+
+> 这是支付业务分析报告。保持分类、分母、统计期间、汇率依据、缺失数据说明和样本量限制不变。
+> 授权拒绝不是拒付；疑似欺诈响应不是已确认损失；未观察到记录不表示没有交易。
+> 4.8 拒付部分展示欺诈与拒付期内的每个自然月（默认为报告月及此前 11 个月，以报告头注明的期间为准）；
+> 缺少数据的月份仍保留其位置，不以 0% 补齐。不得改动图表数据、表格和计算代码。
+
+## Accept
+
+- Reject a rewrite that changes a claim's strength, a classification, a denominator or the subject
+  of a number, even when `check` passes.
+- After applying, the facts, tables and chart payloads hash the same as before the polish, and the
+  English artifact is unchanged.
+- Rerun the banned-string scan in [terminology.md](terminology.md) and the report's sanity check,
+  including the three report periods and the section 4.8 window.
+- Write the `polish-cn` record (model, fallback reason, blocks applied) into the run record, never
+  into the report's data-source footer.

package/skills/risk-compliance/payment-analysis/references/event-layers.md

@@ -0,0 +1,127 @@
+# Event layers, grains, and joins
+
+## Layers
+
+| Layer | Example filename pattern | Default grain | Usual time field |
+|---|---|---|---|
+| Authorizations | `Authorizations_*authorizations.csv` | one auth attempt | `Timestamp` |
+| Settlements | `Sales-and-refunds_*settlements.csv` | one sale or refund | `Timestamp` or `Settlement date` |
+| Chargebacks | `Chargebacks_*chargebacks.csv` | one dispute | `Chargeback date`; origination via `Original transaction timestamp` |
+
+A run may use one, two, or all three layers. Name every layer used and every layer
+missing.
+
+## Portfolio constants to record
+
+When columns exist and are near-constant, state them once (do not treat as
+drivers):
+
+- MID / Gateway MID
+- MCC
+- Provider / acquirer path
+- Transaction source / entry method
+- Billing descriptor / sub merchant
+
+## Keys and joins
+
+| Join | Left | Right | Notes |
+|---|---|---|---|
+| Auth ↔ Chargeback | `Order ID` | `Original transaction order ID` | Primary for this Pazien-style extract |
+| Auth ↔ Settlement | `Order ID` | `Order ID` | May be 1:n if capture/refund splits |
+| Weak identity | masked `Account`, `IIN` | same | Collisions possible; fine for contribution tables, not unique-customer claims |
+
+Report match rates whenever a join supports a claim (“N of M chargebacks match an
+auth in file”).
+
+## Currency
+
+Reporting amounts are USD. Conversion rules: [fx.md](fx.md).
+
+1. Prefer native USD rows; convert every non-USD amount before summing.
+2. Never add USD + EUR (etc.) into one total without FX and a disclosure.
+3. Count KPIs never need FX.
+
+## Window selection
+
+The step-0 preflight fixes three periods. Set them in this order:
+
+1. Ceiling: the earliest of the user's as-of date, the execution date, and the
+   data end. The data end is the earliest last-event date among the layers a
+   period uses, so numerators and denominators share one end. Disclose each
+   layer's own last date.
+2. Main period, from the table below, capped at the ceiling. Apply the no-data
+   fallback here, before `M` exists.
+3. `M`: the user's explicit report month, otherwise the month containing the
+   main period's end date.
+4. History cutoff for the trend and fraud & chargeback periods: the main
+   period's end date when it falls in `M`, otherwise the last day of `M`;
+   capped at the ceiling. Label `M` month-to-date when this cutoff falls before
+   its last day. An explicit `M` ending before the main period (e.g. 4.8 for
+   December with a January main period) cuts history at December 31.
+
+### Main period
+
+| User ask | Main period |
+|---|---|
+| Nothing stated | this month to date: the 1st of the execution month → cutoff |
+| Full extract | min→max of chosen time field |
+| A named month | that calendar month, capped at the cutoff; label MTD if incomplete |
+| Most recent week / last 7 days | `(max_ts - 7d, max_ts]` |
+| Calendar week | dates in that Mon–Sun (or local week rule; state it) |
+| Compare recent vs prior (within the main period) | split at the same cut; show both |
+
+If the extracts have no rows in the execution month, the default becomes the
+latest calendar month with data (MTD if incomplete); say why. `M` is the month containing the
+main period's end date, or the user's explicit report month.
+
+### Trend period
+
+Default: the last 6 calendar months, `M-5` through `M` inclusive (calendar
+arithmetic, not 182 days). A user-chosen N months spans `M-(N-1)` through `M`.
+Bucket 4.2 by week; label the partial first and last weeks. Any
+month-over-month comparison uses this period. Keep every week on the axis when
+history is missing: a week with no source coverage shows no bar (not 0) and is
+listed as missing. Do not shorten the period to the data.
+
+### Fraud & chargeback period
+
+Default: the last 12 calendar months, `M-11` through `M` inclusive; a
+user-chosen N months spans `M-(N-1)` through `M`. Wherever the skill says
+"12 months" for section 4.8, it means this period. It covers section 4.8 per
+[chargebacks.md](chargebacks.md) and every fraud-over-time chart (疑似欺诈
+decline counts/rates by month). Record the separate
+anchor/as-of cutoff and historical input coverage. Gather the extra preceding
+sale month needed for Mastercard's earliest denominator; missing history does
+not shorten the display.
+
+Chargeback **programme 拒付率** uses received month (`Chargeback date`) per
+[chargebacks.md](chargebacks.md). If you also show origination-month incidence,
+label that separately so it is not mistaken for the Visa/Mastercard rate.
+Before calculating a programme-style rate, identify the processor field that
+distinguishes normal chargebacks from pre-disputes. Keep unclassified cases
+separate; pre-disputes are excluded from Visa VAMP-style metrics and reported
+as a separate Visa rate.
+
+## Decline taxonomy (auth)
+
+Map with both code and message when present (example Pazien-style):
+
+| Code | Message (typical) | Class |
+|---|---|---|
+| A001 | Approval - generic | approval |
+| D102 | Suspected fraud | hard / fraud-coded |
+| D104 | Insufficient funds | soft / funds |
+| D387 | Policy reasons | hard / policy |
+| D202 | Security code invalid | hard / data |
+| D204 | Invalid Expiration date | hard / data |
+| D210 | Do not honor | soft / issuer |
+| R014 | Invalid transaction | reject |
+
+Always recompute from the file; do not assume codes are portable across gateways.
+
+## What not to infer
+
+- BIN country ≠ shipping or billing country
+- Approval ≠ settled funds
+- Suspected-fraud decline ≠ confirmed fraud loss
+- Chargeback reason Fraud ≠ first-party vs third-party adjudication

package/skills/risk-compliance/payment-analysis/references/fx.md

@@ -0,0 +1,59 @@
+# Amount currency → USD (Forex Service)
+
+Reporting amounts are **USD**. Count KPIs never need FX.
+
+Use the Forex Service (`~/projects/forex`), not a provider SDK, not a
+spreadsheet rate, not realtime quotes for historical windows.
+
+## Which amount
+
+| Layer | Amount | Currency |
+|---|---|---|
+| Authorization | `Transaction amount` | `Transaction amount currency` |
+| Settlement | `Settlement amount` (fallback `Transaction amount`) | `Settlement amount currency` |
+| Chargeback | `Dispute amount` | `Dispute amount currency` |
+
+Ignore empty `Pre-DCC amount` (often `0` with blank currency). Do not treat BIN
+country as the transaction currency.
+
+## Rules
+
+1. If every used currency field is `USD`, keep native amounts. Write
+   `金额均为 USD`. Do **not** call Forex Service and do **not** write
+   `未做汇率折算`.
+2. If any row is not USD, convert **that row** to USD before any amount sum,
+   share, ticket size, or dual-axis amount chart.
+3. Historical / windowed reports use **daily** conversion, not realtime:
+
+   `POST {FOREX_BASE_URL}/api/v1/conversions/daily`
+
+   Body:
+
+   ```json
+   {
+     "quoteCurrency": "USD",
+     "date": "<UTC Rate Date = transaction date in the extract>",
+     "items": [{ "currency": "EUR", "amount": "100.00" }]
+   }
+   ```
+
+   Prefer one request per Rate Date: either `conversions/daily` for the day's
+   distinct currencies, or `POST /api/v1/rates/daily` then multiply locally
+   (`converted = native × rate`, decimal strings).
+4. Fail closed if a non-USD row has no daily rate. Do not drop it silently and
+   do not mix native EUR with USD in one total.
+5. Auth: `forex:read` bearer token, audience `forex-service`. Base URL default
+   `https://forex.1above.io`. Contract: `GET /integration/agent.json`.
+6. Footnote converted reports: Rate Date rule, quote USD, Forex Service daily
+   conversion (not realtime). Mark `realtimeFallback` if a current UTC day was
+   served as provisional.
+
+## Env
+
+| Variable | Role |
+|---|---|
+| `FOREX_BASE_URL` | Default `https://forex.1above.io` |
+| `FOREX_TOKEN` | Bearer with scope `forex:read` |
+
+Mint the token from Identity (`client_credentials`, audience `forex-service`,
+scope `forex:read`) as in the Forex Service integration guide.

package/skills/risk-compliance/payment-analysis/references/journey.md

@@ -0,0 +1,79 @@
+# Payment journey (Sankey)
+
+The journey is a **count** Sankey across checkpoints. Prefer ECharts (or
+equivalent). Do not mix count and amount on one Sankey.
+
+## Checkpoint order
+
+```text
+start → risk decision → 3DS → authorization → settlement
+```
+
+## Canonical state transitions
+
+Use these edge names when the underlying fields exist:
+
+| From | To |
+|---|---|
+| risk decision | accept |
+| risk review | 3DS init |
+| accept | non-3DS authorization |
+| non-3DS authorization | non-3DS authorization approved |
+| non-3DS authorization | non-3DS authorization declined |
+| 3DS init | 3DS challenge |
+| 3DS init | 3DS frictionless |
+| 3DS init | 3DS reject |
+| 3DS challenge | 3DS authenticated |
+| 3DS challenge | 3DS authentication failed |
+| 3DS frictionless | 3DS authorization |
+| 3DS authenticated | 3DS authorization |
+| 3DS authorization | 3DS authorization approved |
+| 3DS authorization | 3DS authorization declined |
+
+Settlement edges (when settlement layer present), from approved authorization
+nodes only:
+
+| From | To |
+|---|---|
+| non-3DS / 3DS authorization approved | settled sale |
+| non-3DS / 3DS authorization approved | approved not settled |
+| settled sale | refund (only if Order ID joins cleanly) |
+| settled sale | chargeback fraud / non-fraud (optional) |
+
+## Skip unavailable checkpoints
+
+If a checkpoint has no usable field in the extract, **omit its nodes and edges**.
+Do not invent risk decisions or 3DS outcomes.
+
+Examples:
+
+- `Authentication method` / 3DS result all null → skip risk decision, risk
+  review, and every 3DS node. Collapse to:
+
+  ```text
+  start → authorization → authorization approved / declined → settlement…
+  ```
+
+- Settlement file absent → stop after authorization approved/declined.
+- Refunds with Order IDs that do not join auth approvals → footnote only; do not
+  force a refund edge.
+
+Caption must list skipped checkpoints.
+
+## Mapping hints (when fields exist)
+
+| Journey node | Typical source |
+|---|---|
+| risk decision / risk review | gateway risk action, review queue, step-up flag |
+| accept | risk allow / no step-up |
+| 3DS init / challenge / frictionless / reject | 3DS status / ECI / transStatus |
+| 3DS authenticated / failed | challenge result |
+| non-3DS / 3DS authorization approved | auth response = approval |
+| non-3DS / 3DS authorization declined | auth response ≠ approval |
+| settled sale | settlement type = Sale joined on Order ID |
+
+## Anti-patterns
+
+- Drawing 3DS branches when authentication fields are empty
+- Using amount on the journey Sankey
+- Putting decline-reason fan-out on the journey (keep that in Topics charts)

package/skills/risk-compliance/payment-analysis/references/metrics.md

@@ -0,0 +1,67 @@
+# Metrics and denominators
+
+Compute with explicit denominators. Prefer count and amount side by side.
+Amounts are USD per [fx.md](fx.md) before any sum or share.
+
+## Authorization
+
+| KPI | Formula | Notes |
+|---|---|---|
+| Attempts | count of auth rows in window | |
+| Approvals | count where response = approval | |
+| Auth rate | approvals / attempts | Not capture rate |
+| Approved amount | sum(amount \| approval) | USD after [fx.md](fx.md) |
+| Declines | attempts − approvals | Or hard-only if stated |
+| Decline rate | declines / attempts | |
+| Reason share (of declines) | reason_count / declines | Default for mix tables |
+| Reason incidence (of attempts) | reason_count / attempts | Label clearly if used |
+| Country attempt share | country_attempts / attempts | |
+| Country amount share | country_attempt_amount_USD / attempt_amount_USD | Often diverges from attempt share |
+| Country auth rate | country_approvals / country_attempts | Require min-n (e.g. ≥30) for rankings |
+
+Trend grains: daily (`Timestamp` date) within the main period, and weekly
+(state week rule, e.g. W-SUN) over the trend period.
+
+Card product: `Payment method` × `Card type` when both exist.
+
+## Settlement
+
+| KPI | Formula | Notes |
+|---|---|---|
+| Sale count / amount | Settlement type = Sale | |
+| Refund count / amount | Settlement type = Refund | Show sign or absolute + label |
+| Net settled amount | sales + refunds (refunds negative) | |
+| Refund rate (count) | refunds / sales | |
+| Refund rate (amount) | abs(refund amount) / sale amount | |
+| Status mix | by Settlement status | |
+
+Do not equalize settled sales to approved auth amount without a timing caveat.
+
+## Chargebacks
+
+Monthly **拒付率** by brand is [chargebacks.md](chargebacks.md): classify normal,
+pre-dispute, and unclassified cases first; Visa uses same-month sales and
+reports pre-disputes separately; Mastercard normal chargebacks use
+previous-month sales. Section 4.8 spans the fraud & chargeback period (default
+`M-11` through `M`) regardless of the main analysis period; Mastercard may need
+`M-12` sales. Keep every month label and coverage row, skip empty rate points, and do not blend Visa+Mastercard.
+The table below is mix / match, not that programme rate.
+
+| KPI | Formula | Notes |
+|---|---|---|
+| Normal / pre-dispute / unclassified count and amount | as classified | Amounts USD after [fx.md](fx.md); use abs for magnitude if signed |
+| Reason mix | by Reason category / code | Fraud ≠ all CBs |
+| Match rate to auths | matched / CB rows | State join key |
+| Visa normal monthly 拒付率 | Normal_CB_Visa(M) / Sales_Visa(M) | Excludes pre-disputes; received month; not VAMP unless TC40 is present |
+| Visa pre-dispute rate | PreDispute_Visa(M) / Sales_Visa(M) | Separate descriptive series; excluded from VAMP-style numerator |
+| Mastercard normal monthly 拒付率 | Normal_CB_MC(M) / Sales_MC(M−1) | Excludes pre-disputes; skip M if M−1 sales missing |
+
+Lag: chargeback date is later than original auth. Programme rates use
+**received** month, not origination vintage.
+
+## Ranking and “Other”
+
+- Rank countries by attempts unless the user asks for amount.
+- Roll the long tail into `Other` after top 10–15; show Other share.
+- For decline-by-country matrices, use top countries by attempts and top reasons
+  globally; collapse remaining reasons to `Other declines`.