@1aboveio/skills 1.0.9 → 1.0.11

package/skills/risk-compliance/fraud-detection/references/workflow.md

@@ -0,0 +1,216 @@
+# 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 discovery.
+Read [entities.md](entities.md) and [enrichment.md](enrichment.md). Record the
+transaction ID, retry/duplicate/lifecycle policy, decision point, timestamp and
+timezone, available ordering/arrival evidence, entity keys, original currency,
+conversion currency, and enrichment availability. Do not invent missing inputs.
+Missing prerequisites block affected features, not unrelated discovery. 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,
+  request a negative definition before computing metrics that require it. Do not
+  infer `NOT positive` as negative. Continue rapid discovery with other rows
+  unlabeled if no negative definition is available.
+- Rows matching neither class, both classes, explicit unknown states, or an
+  immature outcome window are unlabeled.
+- If classes are incomplete, continue descriptive discovery and report observed
+  known-fraud hits and transaction reach. Mark unsupported metrics unavailable.
+
+Label completeness is a metric gate, not a prerequisite for discovering rules.
+`descriptive-only` permits profile selection, transaction feature engineering,
+and candidate rules without precision, lift, or claims of future performance.
+Recall may be reported only against a defined, labeled positive population, with
+its scope explicit; fraud-only samples do not establish portfolio recall.
+Profile clarification may be grouped with missing label or attribution questions.
+
+## 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: transaction
+analysis_track: real-time | post-transaction-review
+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 known class definitions. Request missing definitions only for
+  metrics that need them; discovery may continue with unlabeled transactions.
+- Validate the pre-flight mapping against observed rows and record the resulting
+  positive, negative, and unlabeled counts.
+- If the mapping is contradictory, clarify it before using affected labels.
+  Missing negatives do not stop transaction-level candidate discovery.
+- 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.
+- Compute precision, false-positive rates, and lift only with a justified labeled
+  negative population. State labeled-hit coverage separately from all-hit reach.
+  Unlabeled transactions can contribute eligible velocity history.
+
+## 3 — Declare evidence basis
+
+- Default to rapid discovery on recent transactions. No train/test/holdout split
+  is required. Record discovery and scoring windows, observation cutoff, sample
+  coverage, and whether rules were selected on the same transactions scored.
+- Recent observed evidence supports known-fraud hits and transaction reach.
+  Retrospective labels support sample metrics only where class definitions and
+  maturity justify them. Neither establishes future performance.
+- Optional subsequent monitoring or temporal validation measures transactions
+  after rule definitions and reference lists were fixed. If used, freeze the
+  discovery/scoring boundary and do not tune on the claimed validation outcomes.
+- Decision-time correctness remains mandatory regardless of validation choice.
+  History/reference artifacts must have been available at each scored decision;
+  current transaction inputs are included by default, not current outcomes.
+- Without usable timestamps, omit rolling/sequence features; continue with
+  available attributes and state that real-time historical replay is unproven.
+
+## 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.
+- Record the discovery population for thresholds and candidate lists. Keep
+  encoding, outcome-rate, graph, and watchlist inputs causal at decision time;
+  later discoveries can define prospective rules, not rewrite earlier features.
+- Read [feature-sql.md](feature-sql.md) for mismatch, frequency encoding, and
+  count/sum/distinct velocities. Use standard windows and include current.
+- Keep completed entity/period aggregates in post-transaction review. Read the
+  selected profile's expert patterns as hypotheses, with benign explanations.
+- Prefer interpretable conditions with explicit units and windows.
+- Do not invent columns, identity links, consent, intent, or actor attribution.
+
+## 5 — Select shortlist
+
+Use observed support, known-fraud hits, transaction reach, operability, and
+meaningful interactions. Add precision/lift and temporal stability only when
+supported. Keep tiny or attribution-uncertain spikes for monitoring. Do not wait
+for a complete mechanism diagnosis before expressing a useful candidate rule.
+
+## 6 — Score rules
+
+State explicit conditions, transaction grain, units, windows, and decision point.
+Retain `(transaction_id, rule_id)` hits for every matching rule. Present:
+
+**occurrence → precision → recall**, with unsupported metrics unavailable.
+
+Name the scoring population, discovery overlap, and outcome cutoff. Define
+precision over labeled hits and disclose unlabeled hits separately; do not imply
+that partial-label precision describes all triggered transactions. Define recall
+over the stated known-positive population. Report known-fraud hits without
+claiming precision when negatives are unavailable. Amount metrics supplement,
+not replace, counts. Same-sample metrics describe observations, not validation.
+
+## 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.
+- Compute package unions by transaction ID, never by summing per-rule hits.
+  Show overlap and incremental coverage relative to the named base package.
+  For action-level totals, declare precedence when several actions match.
+- For each package compute triggered count/rate and amount/share, then supported
+  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), selected profile packs, and
+`{house-style baseDir}/references/analytical-reporting.md` and its required references.
+Use `{write-report baseDir}/SKILL.md` with frozen results for this stage, without
+rerunning discovery. If a required skill or reference is unavailable, report the blocker.
+
+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 where supported. 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-detection/<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), selected packs, and
+`{house-style baseDir}/references/analytical-reporting.md` and its required references.
+Give these to the reviewer for the report review.
+
+This independent domain review checks the selected packs and methods; it is not a second
+generic editorial pass. Reuse the writer's recorded editorial findings and checked version.
+Additional domain findings return to the writer for affected passages and any needed recheck,
+without repeating completed review or optional polish solely because this stage was reached.
+
+- 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/risk-compliance/fraud-detection/release-check.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WEEK_MS = 7 * DAY_MS;
+const here = dirname(fileURLToPath(import.meta.url));
+
+function readJson(path, fallback = {}) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
+}
+
+function frontmatterValue(text, key) {
+  const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
+  const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
+  return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
+}
+
+function repositoryOf(source) {
+  const value = String(source ?? '').trim();
+  const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
+  return match?.[1] ?? null;
+}
+
+function stableVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function newer(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return false;
+}
+
+function writeCache(path, value) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value));
+  } catch { /* A read-only cache must not block skill use. */ }
+}
+
+function main(now = Date.now()) {
+  if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
+  const bundle = readJson(join(resolve(here, '../../..'), 'package.json'));
+  if (bundle.name === '@1aboveio/skills' && bundle.nativeCodex?.schemaVersion === 1) return;
+  const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
+  const name = frontmatterValue(skill, 'name');
+  const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
+  if (!name || !localVersion) return;
+
+  const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
+  const entry = lock.skills?.[name];
+  const repository = repositoryOf(entry?.sourceUrl || entry?.source);
+  if (!repository) return;
+
+  const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
+  const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
+  const all = readJson(cachePath);
+  const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
+
+  if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
+    const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1500,
+    });
+    cache.lastCheck = now;
+    if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
+    else delete cache.latestTag;
+    all[repository] = cache;
+    writeCache(cachePath, all);
+  }
+
+  const latestVersion = stableVersion(cache.latestTag);
+  if (!latestVersion || !newer(latestVersion, localVersion)) return;
+  if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
+
+  cache.notifiedTag = cache.latestTag;
+  cache.notifiedAt = now;
+  all[repository] = cache;
+  writeCache(cachePath, all);
+  const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
+  process.stdout.write(
+    `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
+      + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
+      + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
+  );
+}
+
+try { main(); } catch { /* Update checks are advisory and always fail silent. */ }

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

@@ -12,9 +12,9 @@ description: >
   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 (fraud-analysis) or TLD / MCC-miscoding
+  fraud rule discovery (fraud-detection) or TLD / MCC-miscoding
   clusters (tld-detection).
-release-version: 0.44.0
+release-version: 0.45.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Payment Analysis
@@ -33,7 +33,7 @@ optional topic fuel, not required for the journey core.
 
 **Produce:** Markdown + preferred Chinese/bilingual HTML under
 `reports/payment-analysis/`.  
-**Do not produce:** supervised precision/recall packages (`fraud-analysis`) or TLD clusters (`tld-detection`).
+**Do not produce:** fraud detection rule packages (`fraud-detection`) or TLD clusters (`tld-detection`).
 
 Read the playbook for the step you are on. Paths under `references/` are
 relative to this skill.
@@ -101,6 +101,16 @@ when authentication fields are empty; caption the skips.
 
 ### 4 — Write outputs
 
+Read `{house-style baseDir}/references/analytical-reporting.md` and its required
+references. Use `{write-report baseDir}/SKILL.md` for this report stage; if a
+required skill or reference is unavailable, report the blocker rather than claim
+the report stage is complete. Pass the domain template and frozen results; do not
+rerun the analysis. Pass the selected review mode, this template, required artifacts and,
+for Chinese delivery, the required `polish-cn` pass and its guardrails. `write-report`
+coordinates draft, editorial review, fixes, selected polish and regenerated-output checks.
+This workflow retains domain validation and delivery; steps 5-7 verify and reuse those
+results rather than scheduling a second writing pipeline.
+
 Structure and chapter minima:
 [report-template.md](references/report-template.md). Chart marks:
 [visualization.md](references/visualization.md). English/Chinese terms:
@@ -114,8 +124,13 @@ 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.
+HTML is preferred when there are charts; it is not mandatory solely because it is
+preferred. The applicable topic charts and supporting tables in the domain template
+are required in the chosen format, including English-only output. A small sample
+limits the conclusions; it does not turn a chart requirement into prose or a table.
+For unavailable dimensions, follow the template's omission and coverage rules rather
+than inventing series. Glossary applies to headings, KPI labels, legends, and Sankey
+skip chips.
 
 ### 5 — Language proofread
 
@@ -128,9 +143,11 @@ Do not change numbers, joins, or chart data.
 - [ ] Main, trend, and fraud & chargeback periods and the cutoff are stated in the report header
 - [ ] Trend charts span the trend period; fraud/chargeback charts span their period
 - [ ] Structure is summary → top stats → Sankey → topics → 运营影响
+- [ ] Each applicable chart and supporting table in report-template.md exists at a recorded output location; unavailable dimensions follow its omission/coverage rules
 - [ ] 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
+- [ ] Open the saved charts in an available renderer and check representative plotted values against their labeled scales and supporting tables, including rate-axis positions and clipped dates; record any unverified rendering as incomplete
 - [ ] Amount axes/legends include currency (`授权尝试金额 USD`, …)
 - [ ] No supervised fraud-rule metrics
 - [ ] Non-USD amounts converted per fx.md; all-USD books say 金额均为 USD
@@ -143,25 +160,27 @@ Do not change numbers, joins, or chart data.
 
 ### 7 — Editorial review and Chinese polish (required)
 
-After the sanity check, run `editorial-review` (`{editorial-review baseDir}/SKILL.md`)
-on the report's narrative source, naming
-[report-template.md](references/report-template.md) as its template, then rerun the
-sanity check. Then run `polish-cn` (`{polish-cn baseDir}/SKILL.md`) on the Chinese
-prose with the blocks, protected terms and guardrails in
-[chinese-polish.md](references/chinese-polish.md). Record the model that ran and any fallback in the run record, not the report's
-data-source footer. Only language may change in the polish. Re-render every
-Chinese artifact from the polished source and rerun the glossary and
-fact-preservation checks before delivery.
+Verify the writing stage returned the reviewed path/version, findings/fixes and open issues,
+covering this template, required analytical rules and domain checks. A read of the review
+instructions alone does not complete it. Resume a missing stage through `write-report`;
+reuse a completed pass rather than starting another `editorial-review` or polish call.
+
+Chinese delivery still requires `polish-cn` with the blocks, protected terms and guardrails in
+[chinese-polish.md](references/chinese-polish.md); fast mode does not waive this domain requirement.
+The writer records the actual model or permitted fallback outside the report, applies only
+wording changes to the narrative source, regenerates Chinese outputs and reruns glossary and
+fact-preservation checks. Verify that result here, rerun the applicable sanity checks and
+report any incomplete required stage before delivery. English-only delivery needs no Chinese polish.
 
-## Boundary with fraud-analysis and tld-detection
+## Boundary with fraud-detection and tld-detection
 
 | 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` |
+| Transaction-level fraud rule discovery and evidence-qualified metrics, 3DS/block **packages** | `fraud-detection` |
 | Potential TLD clusters, currency-amount-pair ladders, MCC miscoding, stuffing | `tld-detection` |
 
-Routing 3DS / 风控拦截 / retry from this extract is not a fraud-analysis rule
+Routing 3DS / 风控拦截 / retry from this extract is not a fraud-detection rule
 package.
 
 ## Reference index

package/skills/risk-compliance/payment-analysis/references/auth-rate-actions.md

@@ -2,7 +2,7 @@
 
 Use this list when writing **运营影响**. Pick only items the extract
 supports. Do not dump the whole list. These are routing / retry operations,
-not a `fraud-analysis` rule package (no precision/recall, no “loss saved”).
+not a `fraud-detection` rule package (no precision/recall, no “loss saved”).
 
 Auth rate = 授权成功 / 授权尝试. BIN country = 发卡行国家.
 
@@ -25,6 +25,6 @@ report (country, share, 软性拒绝 count). Example shapes:
 
 ## Out of scope
 
-- Supervised thresholds, holdout, 3DS/block “packages” → `fraud-analysis`
+- Fraud detection thresholds and 3DS/block “packages” → `fraud-detection`
 - Inventing retry counts or expected auth-rate lift
 - Mixing portfolio and merchant grains in one file

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

@@ -88,6 +88,12 @@ Each topic: short lede + chart(s) + supporting table.
 | 4.8 Chargebacks | every month of the fraud & chargeback period (default 12) including the report month: monthly normal/pre-dispute/unclassified counts and amounts; reason-category bars; Visa normal 拒付率, separate Visa pre-dispute-rate series, and Mastercard normal monthly 拒付率 per [chargebacks.md](chargebacks.md); preserve all month labels/table rows, leave missing points as gaps, put formulas/coverage caveats under the rate chart |
 
 Use both authorization and settlement data when both files are present.
+For 4.5, keep the decline-count chart when declines exist but their reasons are missing.
+Group those records as `Reason unknown` (`拒绝原因未知`); a generic `Declined` status is
+not a specific reason. If every decline lacks a reason, show one unknown-reason bar with
+the observed count and a matching table row. If only some lack reasons, retain the unknown
+group beside the recorded categories so the counts reconcile. This is a coverage group,
+not evidence of a cause or a retry/risk action.
 Section 4.8 always uses the fraud & chargeback period (default `M-11` through
 `M`), independently of the main analysis period. The supporting table includes every month, cases/amounts by
 stage, each rate's numerator and denominator, denominator month, coverage, and
@@ -111,8 +117,10 @@ chargeback rates are network-style estimates).
 
 ## Final Chinese language pass
 
-After factual validation, run `editorial-review`, then `polish-cn` for the final
-Chinese polish per [chinese-polish.md](chinese-polish.md).
+Pass this template and the required Chinese polish guardrails in
+[chinese-polish.md](chinese-polish.md) to `write-report`. The writer runs editorial review,
+fixes and the required polish after factual validation; this domain workflow reuses the
+completed passes rather than invoking them again.
 Synchronize accepted language across the Chinese artifacts being delivered,
 without adding a format requirement or changing facts/chart data. If both Chinese
 Markdown and HTML are delivered, use the same accepted wording. A glossary grep

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

@@ -28,6 +28,14 @@ ECharts (Sankey). Markdown tables remain required beside charts.
 - Stacked bars = mix within a group (e.g. decline reasons by country), never rate.
 - Sort categories by a stated order (usually attempts desc).
 
+Check the saved, rendered charts before delivery, not just their file existence or labels.
+Use the project's chart library for scales and axes when available. If a dependency is missing,
+choose an available chart tool or report the blocker; do not replace a quantitative plot with
+an uncalibrated schematic. Check representative marks against labeled tick positions and the
+supporting table. A caption that lists the correct figures does not repair a wrong position or
+an absent scale. One supported rate point may stand alone in a line series; do not extend it
+across weeks without coverage just to draw a segment.
+
 ## Required charts (HTML)
 
 1. Payment journey Sankey — see [journey.md](journey.md)
@@ -35,7 +43,9 @@ ECharts (Sankey). Markdown tables remain required beside charts.
    spanning the trend period (default last 6 months, `M-5`–`M`)
 3. Authorization rate by segment (card product and/or country): rate as line
 4. BIN-country contribution: count bar + amount bar (dual axis)
-5. Decline by reason: count bars (+ amount bars/dual axis if shown)
+5. Decline by reason: count bars (+ amount bars/dual axis if shown). Missing reasons use an
+   explicit `Reason unknown` group, including one bar for all declines when no reasons exist;
+   see [report-template.md](report-template.md). Do not infer a reason from a generic status.
 6. Decline mix by BIN country: stacked count bars
 7. Section 4.8 monthly dispute-rate lines: an ascending calendar-month axis
    covering the fraud & chargeback period (default 12 months) and ending in

package/skills/risk-compliance/portfolio-payment-analysis/LICENSE

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