@1aboveio/skills 0.19.2 → 0.19.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1aboveio/skills",
-  "version": "0.19.2",
+  "version": "0.19.3",
   "description": "Install the 1AboveIO first-party skill groups through the native Skills CLI.",
   "license": "MIT",
   "type": "module",

package/runtime/skills/distribution/generated/recipes.json

@@ -8,7 +8,7 @@
       "id": "first-party",
       "type": "first-party",
       "package": "@1aboveio/skills",
-      "version": "0.19.2",
+      "version": "0.19.3",
       "updatePolicy": "pinned-npm-version",
       "members": [
         {
@@ -208,7 +208,7 @@
             "sourceId": "first-party",
             "sourceType": "first-party",
             "package": "@1aboveio/skills",
-            "version": "0.19.2",
+            "version": "0.19.3",
             "installPath": null,
             "members": [
               "harness-runtime",
@@ -244,7 +244,7 @@
             "sourceId": "first-party",
             "sourceType": "first-party",
             "package": "@1aboveio/skills",
-            "version": "0.19.2",
+            "version": "0.19.3",
             "installPath": null,
             "members": [
               "harness-runtime",
@@ -290,7 +290,7 @@
             "sourceId": "first-party",
             "sourceType": "first-party",
             "package": "@1aboveio/skills",
-            "version": "0.19.2",
+            "version": "0.19.3",
             "installPath": null,
             "members": [
               "harness-runtime",
@@ -323,7 +323,7 @@
             "sourceId": "first-party",
             "sourceType": "first-party",
             "package": "@1aboveio/skills",
-            "version": "0.19.2",
+            "version": "0.19.3",
             "installPath": null,
             "members": [
               "harness-runtime",
@@ -366,7 +366,7 @@
             "sourceId": "first-party",
             "sourceType": "first-party",
             "package": "@1aboveio/skills",
-            "version": "0.19.2",
+            "version": "0.19.3",
             "installPath": null,
             "members": [
               "harness-runtime",
@@ -394,7 +394,7 @@
             "sourceId": "first-party",
             "sourceType": "first-party",
             "package": "@1aboveio/skills",
-            "version": "0.19.2",
+            "version": "0.19.3",
             "installPath": null,
             "members": [
               "harness-runtime",
@@ -432,7 +432,7 @@
             "sourceId": "first-party",
             "sourceType": "first-party",
             "package": "@1aboveio/skills",
-            "version": "0.19.2",
+            "version": "0.19.3",
             "installPath": null,
             "members": [
               "harness-runtime",
@@ -460,7 +460,7 @@
             "sourceId": "first-party",
             "sourceType": "first-party",
             "package": "@1aboveio/skills",
-            "version": "0.19.2",
+            "version": "0.19.3",
             "installPath": null,
             "members": [
               "harness-runtime",
@@ -498,7 +498,7 @@
             "sourceId": "first-party",
             "sourceType": "first-party",
             "package": "@1aboveio/skills",
-            "version": "0.19.2",
+            "version": "0.19.3",
             "installPath": null,
             "members": [
               "harness-runtime",
@@ -526,7 +526,7 @@
             "sourceId": "first-party",
             "sourceType": "first-party",
             "package": "@1aboveio/skills",
-            "version": "0.19.2",
+            "version": "0.19.3",
             "installPath": null,
             "members": [
               "harness-runtime",
@@ -564,7 +564,7 @@
             "sourceId": "first-party",
             "sourceType": "first-party",
             "package": "@1aboveio/skills",
-            "version": "0.19.2",
+            "version": "0.19.3",
             "installPath": null,
             "members": [
               "harness-runtime",
@@ -596,7 +596,7 @@
             "sourceId": "first-party",
             "sourceType": "first-party",
             "package": "@1aboveio/skills",
-            "version": "0.19.2",
+            "version": "0.19.3",
             "installPath": null,
             "members": [
               "harness-runtime",
@@ -636,7 +636,7 @@
             "sourceId": "first-party",
             "sourceType": "first-party",
             "package": "@1aboveio/skills",
-            "version": "0.19.2",
+            "version": "0.19.3",
             "installPath": null,
             "members": [
               "harness-runtime"
@@ -662,7 +662,7 @@
             "sourceId": "first-party",
             "sourceType": "first-party",
             "package": "@1aboveio/skills",
-            "version": "0.19.2",
+            "version": "0.19.3",
             "installPath": null,
             "members": [
               "harness-runtime"
@@ -694,7 +694,7 @@
           "sourceId": "first-party",
           "sourceType": "first-party",
           "package": "@1aboveio/skills",
-          "version": "0.19.2",
+          "version": "0.19.3",
           "installPath": null,
           "members": [
             "harness-runtime",
@@ -749,7 +749,7 @@
           "sourceId": "first-party",
           "sourceType": "first-party",
           "package": "@1aboveio/skills",
-          "version": "0.19.2",
+          "version": "0.19.3",
           "installPath": null,
           "members": [
             "harness-runtime",

package/runtime/skills/engineering/engineering-runtime/scripts/workflow-policy.mjs

@@ -119,7 +119,7 @@ export const WORKFLOW_TRUSTED_SOURCES = deepFreeze({
     id: 'first-party',
     type: 'first-party',
     package: '@1aboveio/skills',
-    version: '0.19.2',
+    version: '0.19.3',
   },
   matt: {
     id: 'matt-pocock',

package/skills/engineering/engineering-runtime/coherence/workflow.json

@@ -383,7 +383,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.19.3"
       },
       "contentDigest": "eff6c7b5931bce5b2265a619bccddd371a89df6ce7bc2edc74f11d00060a71dd",
       "digestExcludes": []
@@ -396,7 +396,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.19.3"
       },
       "contentDigest": "d97abeff7bdc5ae2e4be2f631d09dba46d4753ce1e67334793364329af59f066",
       "digestExcludes": []
@@ -409,7 +409,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.19.3"
       },
       "contentDigest": "00cfdd3e5bfbc3e37b1369ad93aae91161e671829760a8867ea9be25047ba461",
       "digestExcludes": []
@@ -422,7 +422,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.19.3"
       },
       "contentDigest": "58b0556228a9271cf9e33727a05fc08a4fdfd29512ec0936b169f0a55d60e6ef",
       "digestExcludes": []
@@ -435,7 +435,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.19.3"
       },
       "contentDigest": "4664873230f22de2fcf46b7b529570cfedabdc850620031d8f96baf89fcdc5b4",
       "digestExcludes": []
@@ -448,9 +448,9 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.19.3"
       },
-      "contentDigest": "a2df894683012581ce57e92d6e2dacd7eb377e4a0547a98acaea04878ef6aa3a",
+      "contentDigest": "3016f025b4acf3b7f61628ff3043ca55e680d0fabc7cf9fb4b4c46424d9b22ed",
       "digestExcludes": []
     },
     {
@@ -461,7 +461,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.19.3"
       },
       "contentDigest": "01c192d8b4fd416af4ea02e8000e5fce0cee723a6ac2f8c0c48372087e1a262e",
       "digestExcludes": []
@@ -474,7 +474,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.19.3"
       },
       "contentDigest": "ffba0c83491676794c74721f4c6dbae430f5bc186e5a55f0764e29eaeb13829b",
       "digestExcludes": []
@@ -487,7 +487,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.19.3"
       },
       "contentDigest": "f048fd00c69f2dc666fc7a3096cfeee6dfba73933bfb69602f3f0e26159798cc",
       "digestExcludes": []
@@ -500,7 +500,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.19.3"
       },
       "contentDigest": "90a7c4e1ad6da1e632ea2c5259e4967ffebb84353adccbca8dfc5d6bc50b60c1",
       "digestExcludes": []
@@ -513,15 +513,15 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.19.3"
       },
-      "contentDigest": "ab98e937973720aedf6f79a63e99650fe3488f4f798d46ed3ae606f0b12a2a41",
+      "contentDigest": "6ef7cf062d899835774d3010dbba511587b0d60835447417d4b74a5afe25b184",
       "digestExcludes": [
         "coherence/workflow.json"
       ]
     }
   ],
-  "releaseIdentity": "0fb67095c481e3a37f57b149e3557c5e450fa93fa3077888ab1eb2bf1ac3d196",
+  "releaseIdentity": "63593db8810d932c5774b375f3403578b821c9df6ca6e8a866f12f2b8fc4fd47",
   "lifecycleAuthority": "native-skills-cli",
   "repairRecipe": {
     "id": "engineering-workflow-dependency-first",
@@ -579,7 +579,7 @@
         "sourceId": "first-party",
         "sourceType": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2",
+        "version": "0.19.3",
         "installPath": null,
         "members": [
           "harness-runtime",
@@ -597,7 +597,7 @@
         "commands": [
           {
             "transport": "npm",
-            "command": "npx @1aboveio/skills@0.19.2 install --group engineering-workflow --yes"
+            "command": "npx @1aboveio/skills@0.19.3 install --group engineering-workflow --yes"
           }
         ],
         "onFailure": {

package/skills/engineering/engineering-runtime/scripts/workflow-policy.mjs

@@ -119,7 +119,7 @@ export const WORKFLOW_TRUSTED_SOURCES = deepFreeze({
     id: 'first-party',
     type: 'first-party',
     package: '@1aboveio/skills',
-    version: '0.19.2',
+    version: '0.19.3',
   },
   matt: {
     id: 'matt-pocock',

package/skills/engineering/resolve-issues/generated/workflow-repair-policy.json

@@ -237,7 +237,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.19.3"
       }
     },
     {
@@ -248,7 +248,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.19.3"
       }
     },
     {
@@ -259,7 +259,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.19.3"
       }
     },
     {
@@ -270,7 +270,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.19.3"
       }
     },
     {
@@ -281,7 +281,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.19.3"
       }
     },
     {
@@ -292,7 +292,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.19.3"
       }
     },
     {
@@ -303,7 +303,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.19.3"
       }
     },
     {
@@ -314,7 +314,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.19.3"
       }
     },
     {
@@ -325,7 +325,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.19.3"
       }
     },
     {
@@ -336,7 +336,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.19.3"
       }
     },
     {
@@ -347,7 +347,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.19.3"
       }
     }
   ],
@@ -468,7 +468,7 @@
         "sourceId": "first-party",
         "sourceType": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2",
+        "version": "0.19.3",
         "installPath": null,
         "members": [
           "harness-runtime",
@@ -486,7 +486,7 @@
         "commands": [
           {
             "transport": "npm",
-            "command": "npx @1aboveio/skills@0.19.2 install --group engineering-workflow --yes"
+            "command": "npx @1aboveio/skills@0.19.3 install --group engineering-workflow --yes"
           }
         ],
         "onFailure": {

package/skills/engineering/resolve-issues/scripts/run-state.mjs

@@ -3412,7 +3412,7 @@ export const WORKFLOW_PREFLIGHT_COMMANDS = Object.freeze([
 
 const WORKFLOW_VERIFIER_URL = new URL('../../engineering-runtime/scripts/workflow-coherence.mjs', import.meta.url)
 const WORKFLOW_FALLBACK_POLICY_URL = new URL('../generated/workflow-repair-policy.json', import.meta.url)
-export const WORKFLOW_TRUSTED_FALLBACK_POLICY_SHA256 = '8fb804c3034b780877774f6228166716ee98d1b39986adac397ac33c0feebfb5'
+export const WORKFLOW_TRUSTED_FALLBACK_POLICY_SHA256 = 'b3ae9760db370098e3737c7b23bcfd5e03d61e30586857858826b6875e3b4a2f'
 const WORKFLOW_REPAIR_RECIPE_REFERENCE = Object.freeze({
   id: 'engineering-workflow-dependency-first',
   generatedFrom: 'skills/distribution/generated/recipes.json',

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

@@ -5,9 +5,10 @@ description: >
   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,
+  (Forex Service daily conversion). Chargebacks separate normal and
+  pre-dispute cases; Visa pre-disputes are excluded from VAMP-style metrics
+  and calculated separately, while Mastercard 拒付率 is 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
@@ -57,7 +58,8 @@ 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).
+Visa pre-disputes excluded from the normal/VAMP-style numerator and calculated
+separately, skip empty brand-months, no blended Visa+Mastercard ratio).
 
 ### 3 — Journey Sankey
 
@@ -98,6 +100,8 @@ Do not change numbers, joins, or chart data.
 - [ ] Amount axes/legends include currency (`授权尝试金额 USD`, …)
 - [ ] No supervised fraud-rule metrics
 - [ ] Non-USD amounts converted per fx.md; all-USD books say 金额均为 USD
+- [ ] Normal chargebacks, pre-disputes, and unclassified cases are distinct
+- [ ] Visa pre-disputes are excluded from VAMP-style metrics and calculated separately
 - [ ] 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

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

@@ -1,4 +1,4 @@
-# Chargeback / dispute rate (Visa vs Mastercard)
+# 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
@@ -10,43 +10,67 @@ 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.
 
+## 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.
+
+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 card brand is drawn **only if**
+A monthly point for a brand and case-stage series is drawn **only if**
 
-- numerator (chargebacks **received** that calendar month for that brand) > 0, and
+- 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. If a brand has no drawable points, omit the series. If no
-series remain, omit the rate chart (keep the reason-category bars if CBs
-exist).
+sale count. If a series has no drawable points, omit it. If no series remain,
+omit the rate chart (keep case-stage and reason-category bars if cases exist).
 
 ## Formulas (count)
 
-Numerator for both brands: chargebacks **received** in calendar month `M`
-(`Chargeback date`), `Payment method` = that brand. Not original
-transaction month. Inquiries / RDR-cleared cases are not in this extract;
-count every CB row.
+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 | Programme (current) | Rate |
+| Brand / series | Programme alignment | Rate |
 |---|---|---|
-| Visa | VAMP dispute/sales count (same month) | `CB_Visa(M) / Sales_Visa(M)` |
-| Mastercard | ECP / ECM chargeback rate (lagged sales) | `CB_MC(M) / Sales_MC(M−1)` |
+| 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`.
+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. This skill’s extract usually has chargebacks
-only → report **Visa 拒付率 = Visa CB count / Visa same-month sales**.
-Do not label it “VAMP ratio” unless TC40/EFW is in the file.
+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.
 
@@ -62,7 +86,8 @@ it for ECP.
 ## Amount rate (optional footnote)
 
 `abs(dispute amount) / sale amount` with the **same month alignment as
-the count rate** for that brand. Secondary; the line chart is count %.
+the count rate** for that brand. Keep normal and pre-dispute amounts separate.
+Secondary; the line chart is count %.
 
 ## Window caveat
 

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

@@ -53,6 +53,10 @@ Reporting amounts are USD. Conversion rules: [fx.md](fx.md).
 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)
 

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

@@ -38,18 +38,20 @@ Do not equalize settled sales to approved auth amount without a timing caveat.
 
 ## Chargebacks
 
-Monthly **拒付率** by brand is [chargebacks.md](chargebacks.md): Visa
-same-month sales, Mastercard previous-month sales, skip empty brand-months,
-no blended Visa+Mastercard ratio. The table below is mix / match, not that
-programme rate.
+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. Skip empty brand-months and do not blend Visa+Mastercard.
+The table below is mix / match, not that programme rate.
 
 | KPI | Formula | Notes |
 |---|---|---|
-| CB count / dispute amount | as filed | Amounts USD after [fx.md](fx.md); use abs for magnitude if signed |
+| 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 monthly 拒付率 | CB_Visa(M) / Sales_Visa(M) | Received month; not VAMP unless TC40 in file |
-| Mastercard monthly 拒付率 | CB_MC(M) / Sales_MC(M−1) | Skip M if M−1 sales missing |
+| 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.

package/skills/payment/payment-analysis/references/report-template.md

@@ -54,8 +54,8 @@ KPI cards / table from auth + settlement: attempts, approvals, auth rate,
 attempt amount, approved amount, sale count/amount, refund count/amount, net
 settled, distinct PAN/BIN/countries, portfolio constants (MID, MCC, provider).
 
-Chinese labels: 授权尝试, 授权成功, 授权成功率, 授权成功金额, 清算销售, 退款,
-净清算, 发卡行国家.
+Chinese labels: 授权尝试, 授权成功, 授权成功率, 授权成功金额,
+已清算交易笔数, 已清算金额, 退款, 净清算, 发卡行国家.
 
 ### 3. Payment journey (Sankey) / 支付旅程
 
@@ -79,7 +79,7 @@ Each topic: short lede + chart(s) + supporting table.
 | 4.5 Decline reason | count bars |
 | 4.6 Decline by country | stacked count bars |
 | 4.7 Settlements | sale/refund amount bars; country contribution dual axis |
-| 4.8 Chargebacks | reason-category bars; Visa / Mastercard monthly 拒付率 line per [chargebacks.md](chargebacks.md) (note under the rate chart; skip empty brand-months) |
+| 4.8 Chargebacks | normal vs pre-dispute counts/amounts; reason-category bars; Visa normal 拒付率 and separate Visa pre-dispute-rate series; Mastercard normal monthly 拒付率 per [chargebacks.md](chargebacks.md) (note under the rate chart; skip empty brand-months) |
 
 Use both authorization and settlement data when both files are present.
 

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

@@ -24,7 +24,11 @@ writing English or Chinese copy. After writing, run the proofread step in
 | BIN country | 发卡行国家 / BIN 国家 | 客户国家；收货国；发卡国 |
 | Settlement | 清算 | |
 | Sale / Refund | 销售 / 退款 | 把销售金额写成清算金额 |
+| Settled transaction count | 已清算交易笔数 | 清算销售 |
+| Settled amount | 已清算金额 | 清算销售金额 |
 | Chargeback / dispute | 拒付 / 争议 | 与清算混用 |
+| Normal chargeback / dispute | 正常拒付 / 正常争议 | 与预争议合并 |
+| Pre-dispute | 预争议 | 计入 VAMP；与正常拒付合并 |
 | Clerical | 差错 | 文书；文书错误 |
 | Quality | 产品服务质量 | 质量；质量争议 |
 | Incidence | 发生率（必须写出分母） | |
@@ -37,7 +41,8 @@ writing English or Chinese copy. After writing, run the proofread step in
 | This analysis window | 当前分析时段内 | 本窗口 |
 | SCA | SCA | 强客户认证（可在首次括注后只用 SCA） |
 | Authentication / 3DS | 鉴权 / 认证 / 3DS | 把 3DS 叫转化 |
-| Visa / Mastercard 拒付率 | Visa / Mastercard 拒付率 | VAMP ratio（无 TC40 时）；ECM（从本抽取断言商户在项目中） |
+| Visa normal 拒付率 / Visa pre-dispute rate | Visa 正常拒付率 / Visa 预争议率 | 合并二者；把预争议计入 VAMP；VAMP ratio（无 TC40 时） |
+| Mastercard normal 拒付率 | Mastercard 正常拒付率 | ECM（从本抽取断言商户在项目中） |
 | Amounts in USD | 金额均为 USD | 未做汇率折算（当全部已是 USD） |
 | Count-heavy / amount-light | 授权尝试笔数多但金额小 | 走廊；笔数负担型走廊 |
 

package/skills/payment/payment-analysis/references/visualization.md

@@ -22,7 +22,7 @@ ECharts (Sankey). Markdown tables remain required beside charts.
 ## Axis hygiene
 
 - Label every axis with the full metric name. Amount axes/legends include
-  currency (`授权尝试金额 USD`, `授权拒绝金额 USD`, `清算销售金额 USD`,
+  currency (`授权尝试金额 USD`, `授权拒绝金额 USD`, `已清算金额 USD`,
   `拒付金额 USD`). Do not use bare `笔数` / `金额` / `%`.
 - Only one axis draws the main grid on dual-axis charts.
 - Stacked bars = mix within a group (e.g. decline reasons by country), never rate.