@1aboveio/skills 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,119 @@
+# Report template
+
+Save:
+
+```text
+reports/payment-analysis/<scope>_overview.md
+reports/payment-analysis/<scope>_overview.zh.md
+reports/payment-analysis/<scope>_overview.zh.html   # preferred when charts
+```
+
+Follow [visualization.md](visualization.md), [journey.md](journey.md),
+[terminology.md](terminology.md), and [fx.md](fx.md) for amount currency. Omit
+topic sections whose layer is missing, except section 4.8: retain its full-period
+coverage notice/table when chargeback history is unavailable.
+No Markdown bold in report body. After writing, grep banned strings in
+terminology.md.
+
+## Required structure
+
+English Markdown headings on the left; Chinese HTML / `.zh.md` on the right.
+
+```markdown
+# Payment Overview — <main period>     # 支付业务概览 — <报告期>
+
+## 1. Executive summary                 # 1. 执行摘要
+## 2. Top statistics                    # 2. 核心指标
+## 3. Payment journey (Sankey)          # 3. 支付旅程（Sankey）
+## 4. Topics                            # 4. 专题
+### 4.1 Overall transaction volume      # 4.1 整体交易量
+### 4.2 Weekly trend                   # 4.2 周趋势
+### 4.3 Authorization rate              # 4.3 授权成功率
+### 4.4 Contribution by BIN country     # 4.4 BIN 国家贡献
+### 4.5 Decline by reason code          # 4.5 授权拒绝原因贡献
+### 4.6 Decline by BIN country          # 4.6 各国授权拒绝结构
+### 4.7 Settlements (when present)      # 4.7 结算
+### 4.8 Chargebacks                     # 4.8 拒付（欺诈与拒付期）
+## 5. Operational impact                # 5. 运营影响
+## 6. Appendix                          # 6. 附录
+```
+
+Under the title, state the three step-0 periods and the cutoff: main period,
+trend period, fraud & chargeback period (Chinese: 报告期、趋势期、欺诈与拒付期、截至).
+Mark any period taken by default as `default`.
+
+HTML uses the Chinese headings. KPI labels, legends, and Sankey node names use
+the glossary in terminology.md (`授权尝试`, `授权成功`, `授权拒绝`,
+`发卡行国家`, `差错`, `产品服务质量`, `Do not honor`).
+
+## Chapter requirements
+
+### 1. Executive summary / 执行摘要
+
+≤5 numbered findings: volume, trend, auth rate, country concentration, main
+decline or settlement/CB driver. Name the period in any finding that is not
+from the main period (e.g. 趋势期内、欺诈与拒付期内).
+
+### 2. Top statistics / 核心指标
+
+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: 授权尝试, 授权成功, 授权成功率, 授权成功金额,
+已结算交易笔数, 已结算金额, 退款, 净结算, 发卡行国家.
+
+### 3. Payment journey (Sankey) / 支付旅程
+
+Count Sankey per [journey.md](journey.md). Caption lists skipped checkpoints
+(e.g. risk decision / 3DS when authentication fields are empty).
+
+Collapsed nodes when 3DS/risk are absent:
+
+`开始 → 授权 → 授权成功 / 授权拒绝 → 已结算销售 / 授权成功未结算`
+
+### 4. Topics / 专题
+
+Each topic: short lede + chart(s) + supporting table.
+
+| Topic | Minimum viz |
+|---|---|
+| 4.1 Volume | count + amount bars (dual axis) |
+| 4.2 Weekly trend | weekly count + amount bars; auth-rate line; spans the trend period (default `M-5`–`M`) |
+| 4.3 Auth rate | rate line by day (main period) and/or segment |
+| 4.4 BIN country | count + amount bars dual axis; rate line |
+| 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 | 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.
+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
+gap reasons. Mastercard may need sales from `M-12`. Label any extra main-period
+case summary separately. If history is unavailable, preserve the full-period
+coverage table and explain what is missing rather than shrinking the window.
+
+### 5. Operational impact / 运营影响
+
+Numbered operational takeaways. Do not title this 运营含义. Do not invent
+supervised fraud rules. Choose from
+[auth-rate-actions.md](auth-rate-actions.md) only when the extract supports
+the trigger (SCA → 3DS; high 疑似欺诈 country → 风控拦截 or 3DS; 软性拒绝 →
+retry).
+
+### 6. Appendix / 附录
+
+Definitions (from terminology.md) and caveats (FX per [fx.md](fx.md),
+issuer country ≠ ship-to, auth rate ≠ capture, journey skips,
+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).
+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
+alone does not complete this step.

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

@@ -0,0 +1,95 @@
+# Terminology
+
+Use these terms consistently in payment-analysis reports. Read this file before
+writing English or Chinese copy. After writing, run the proofread step in
+`SKILL.md`.
+
+## Canonical glossary
+
+| English | Chinese | Do not write |
+|---|---|---|
+| Attempt | 授权尝试 | 单独的「尝试」；交易；conversion |
+| Approval | 授权成功 | 批准；成功（易与结算混淆） |
+| Auth rate | 授权成功率 | 转化率；单独的「成功率」（首次出现时） |
+| Decline | 授权拒绝 | 全部叫欺诈 |
+| Hard / soft / reject | 硬性拒绝 / 软性拒绝 / 风控拦截 | hard 拦截（指拒绝类型时） |
+| Reason / reason code | 拒绝原因 / 原因码 | |
+| Insufficient funds | 余额不足 | 余额 |
+| Suspected fraud | 疑似欺诈 | 已确认欺诈；正文里写 D102（表内 Pazien 代码可保留） |
+| Invalid expiration date | 有效期无效 | |
+| Security code invalid | 安全码无效 | |
+| Policy reasons | 政策原因 | |
+| Do not honor | Do not honor | 拒绝承兑 |
+| BIN / IIN | BIN / IIN | |
+| BIN country | 发卡行国家 / BIN 国家 | 客户国家；收货国；发卡国 |
+| Settlement | 结算 | 清算（清算指卡组织与机构之间的清分，不指向商户结算） |
+| Sale / Refund | 销售 / 退款 | 把销售金额写成结算金额 |
+| Settled transaction count | 已结算交易笔数 | 已清算交易笔数 |
+| Settled amount | 已结算金额 | 已清算金额 |
+| Chargeback / dispute | 拒付 / 争议 | 与结算混用；退单（仅银联语境使用） |
+| Normal chargeback / dispute | 正常拒付 / 正常争议 | 与预争议合并 |
+| Pre-dispute | 预争议 | 计入 VAMP；与正常拒付合并 |
+| Clerical | 差错 | 文书；文书错误 |
+| Quality | 产品服务质量 | 质量；质量争议 |
+| Incidence | 发生率（必须写出分母） | |
+| GMV (loose) | 销售金额合计（说明是否含退款） | |
+| Weekly trend | 周趋势 | 周环比（除非单元格是环比百分比） |
+| Operational impact | 运营影响 | 运营含义 |
+| Ticket size | 客单价 | |
+| Debit / credit | 借记卡 / 贷记卡 | 借记；贷记 |
+| Payment journey | 支付旅程 | 支付旅程 Sankey；Sankey 旅程（标题/结构行） |
+| This analysis window (main period) | 当前报告期内 / 当前分析时段内 | 本窗口 |
+| Main period | 报告期 | 分析窗口（作期间名时） |
+| Trend period | 趋势期 | |
+| Fraud & chargeback period | 欺诈与拒付期 | |
+| Month to date (MTD) | 本月至今（MTD） | 本月（月份未结束时） |
+| As of / cutoff | 截至 | |
+| SCA | SCA | 强客户认证（可在首次括注后只用 SCA） |
+| Authentication / 3DS | 持卡人身份验证（3DS） | 鉴权；把 3DS 叫转化 |
+| 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 | 授权尝试笔数多但金额小 | 走廊；笔数负担型走廊 |
+
+Keep proper nouns in source form when useful: Visa, MasterCard, BIN, 3DS,
+Sankey (in chart captions only), Order ID, MCC, Worldpay, Pazien, MID.
+Do not use Pazien codes (e.g. D102) in prose; use 疑似欺诈 / suspected fraud.
+Tables may still show the code column.
+
+## Axis and UI exceptions
+
+- Rate axis may say `成功率 %` if the legend or lede already says 授权成功率.
+  Amount axes still use the full metric plus currency
+  ([visualization.md](visualization.md)).
+- Week-over-week *percentage* columns may say 笔数周环比 / 金额周环比.
+- Product rankings that exclude tiny samples: write
+  `在授权尝试超过 50 笔的卡种里` (or the n actually used), never
+  `有规模的最弱卡种` or `弱卡种`.
+- If every amount is USD, write `金额均为 USD`. Do not add `未做汇率折算`.
+  Only mention missing FX conversion when mixed currencies were actually summed
+  or dropped.
+- Chart amount fields append the currency: `授权拒绝金额 USD`.
+- HTML footer: data-source filenames only. No skill name, no Chart.js / ECharts.
+- Do not call issuer country “customer country”.
+- Do not call auth rate “conversion” unless contrasting checkout vs issuer
+  response, and then say so.
+
+## Banned strings (grep after writing)
+
+Chinese: `走廊`, `杠杆`, `弱转化`, `转化率`, `赋能`, `抓手`, `闭环`, `打法`,
+`运营含义`, `本窗口`, `弱卡种`, `有规模的最弱`, `强客户认证`, `拒绝承兑`,
+`文书错误`, `质量争议`, `发卡国`
+
+English: `auth drag`, `conversion problem`, `count-heavy`, `amount-light`,
+`Protect US amount`, `Unlike currencies`
+
+If a hit is a legitimate exception (e.g. 周环比 as a table header for WoW %,
+or D102 in a reason-code table), leave it and do not expand the ban.
+
+## Proofread
+
+1. Apply the glossary to headings, KPI labels, chart legends, Sankey skip
+   chips, and body copy.
+2. Grep the report files for the banned strings.
+3. Replace hits using this table. Do not change numbers, formulas, or file
+   paths.

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

@@ -0,0 +1,56 @@
+# Visualization rules
+
+Preferred deliverable: self-contained HTML with Chart.js (KPI charts) and
+ECharts (Sankey). Markdown tables remain required beside charts.
+
+## Mark encoding
+
+| Metric kind | Chart mark | Notes |
+|---|---|---|
+| Count | Bar | Vertical or horizontal |
+| Amount | Bar | Never encode amount as a line |
+| Rate | Line | Percent on its own axis |
+
+## Multi-metric charts
+
+1. Count and amount in the same chart → both are **bars** on **different axes**
+   (left = count, right = amount).
+2. Rate with count and/or amount → rate is a **line** on a dedicated % axis.
+3. Rate alone → line chart (points allowed). No bars for a lone rate series.
+4. Composition of one total → doughnut or stacked bars; not for time trends.
+
+## Axis hygiene
+
+- Label every axis with the full metric name. Amount axes/legends include
+  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.
+- Sort categories by a stated order (usually attempts desc).
+
+## Required charts (HTML)
+
+1. Payment journey Sankey — see [journey.md](journey.md)
+2. Volume trend (weekly): count bar + amount bar (dual axis) + auth-rate line,
+   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)
+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
+   the report month, regardless of the main report window. Preserve missing
+   months as gaps; never connect a line across a missing point. Show
+   Visa normal, Visa pre-dispute, and Mastercard normal separately when supported,
+   plus the complete coverage table per [chargebacks.md](chargebacks.md).
+   If no rate points can be drawn, retain an empty full-period plot with a no-data
+   caption; absent case data is not a zero rate.
+
+## Anti-patterns
+
+- Line for amount or count
+- Bar for a standalone rate series
+- Count and amount on one axis without dual-axis scaling
+- Mixing native EUR (etc.) with USD in one amount series; convert first ([fx.md](fx.md))
+- Plotting a 0% chargeback-rate point for a brand-month with no CBs ([chargebacks.md](chargebacks.md))
+- Inventing Sankey checkpoints not present in the data

package/skills/risk-compliance/payment-analysis/release-check.mjs

@@ -0,0 +1,93 @@
+#!/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 } 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 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/report-writing/LICENSE

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

package/skills/risk-compliance/report-writing/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: report-writing
+description: "Convert compliance audit findings into audience-formatted reports. Four styles: VARS Review Report (Visa's official 2025 template, required verbatim for VARS engagements), Audit Report (compliance team), External Assessment (regulators/external auditors), Management Report (board/C-suite). Use whenever audit output needs to become a deliverable, even just 'write up the findings'."
+release-version: 0.36.0
+---
+**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
+# Report Writing
+
+Generate compliance reports from structured audit findings. Four report styles target
+different audiences — same data, different depth and tone.
+
+## Input Format
+
+Structured findings in Markdown with per-item:
+- **Status:** Pass / Fail / Partial / N/A
+- **Severity:** Critical / Major / Minor / Observation
+- **Category:** e.g., Access Control, Data Protection, Incident Response
+- **Observations:** What was found
+- **Evidence:** Logs, configs, screenshots, code references
+- **Recommendations:** Suggested remediation
+
+If the input deviates, normalize it to the above structure before generating the report.
+
+### VARS-specific input requirement
+
+The VARS Review Report must be generated from the **full** per-control assessment —
+typically the `tracker.md` produced by the `compliance-audit` skill running against the
+VARS checklist (`skills/compliance/compliance-audit/references/vars-checklist.md`, or a
+parsed equivalent from `reg-parser`). Do **not** start a VARS report from a summary,
+verbal findings, or a partial sub-domain review — Visa's report aggregates a complete
+control-by-control assessment, and Section 5 of the deliverable explicitly references
+the *VARS Control Testing and Remediation Tracking* spreadsheet (which is the same
+tracker, in Visa's Excel format).
+
+If the user asks for a VARS report and you don't see a complete tracker covering all
+nine sub-domains, **stop and ask** for it — or offer to run `compliance-audit` first.
+A VARS report without the underlying control-level evidence is not a deliverable Visa
+will accept.
+
+## Report Style Selection
+
+| Style | Audience | When to use |
+|---|---|---|
+| **VARS Review Report** | Visa, acquirer leadership | Visa Acceptance Risk Standards engagements — uses Visa's official 2025 template |
+| **Audit Report** | Compliance team, internal auditors | Day-to-day remediation tracking, technical deep-dives |
+| **External Assessment** | Regulators, external auditors, certification bodies | Formal submissions, certification audits, regulatory filings |
+| **Management Report** | C-suite, board, leadership | Quarterly reviews, risk committee briefings, budget justification |
+
+Select the style based on the stated audience or purpose. If unclear, ask. Default to
+Audit Report when the requestor is technical. **If the framework is VARS / Visa
+Acceptance Risk Standards, always use the VARS Review Report style** — Visa requires
+its template verbatim.
+
+## Workflow
+
+### 1. Ingest Findings
+
+1. Read the audit findings file (Markdown). For VARS, this is the `compliance-audit`
+   tracker produced against the VARS checklist — it must cover all nine sub-domains.
+2. Parse each finding into: ID, title, category, status, severity, observations, evidence, recommendations.
+3. Validate completeness — flag any finding missing severity or status. For VARS,
+   additionally verify every sub-domain is represented; if any are missing, stop and
+   surface the gap to the user before drafting.
+
+### 2. Select Style
+
+Confirm the target style with the user or infer from context:
+- "VARS" / "Visa Acceptance Risk Standards" / "for Visa" → **VARS Review Report**
+- "for the regulator" → External Assessment
+- "for the board" / "executive summary" → Management Report
+- "full technical report" / default → Audit Report
+
+### 3. Generate Report
+
+**House style.** Use the nearest `WRITING.md`: start in the findings file's folder (pasted text: the output
+folder, else the working directory), then parents up to the repository root; never the home
+directory or above. Rate every issue from the evidence first; the style changes
+wording, never a rating, a finding or which issues appear. Then write the prose in its voice,
+language, terms, sentences and presentation. Keep the template structure, severity and rating scales
+(including Status values such as Pass / Fail / Partial), finding IDs and every input count; its
+terms apply to prose, not rating values. The request beats WRITING.md, which beats this skill's
+wording. Never edit WRITING.md. Bilingual: `write-doc`'s bilingual mode. No WRITING.md: write as
+below.
+
+The VARS Review Report ignores WRITING.md entirely: Visa's template wording and structure stay
+verbatim.
+
+Follow the style-specific template. Reference files provide the full structure:
+
+- **VARS Review Report:** Read `references/vars-report-template.md` (Visa's official 2025 template)
+- **Audit Report:** Read `references/audit-report-template.md`
+- **External Assessment:** Read `references/external-assessment-template.md`
+- **Management Report:** Read `references/management-report-template.md`
+
+### 4. Review and Finalize
+
+1. Verify coverage:
+   - Audit Report: every finding from the input has its own section.
+   - External Assessment: every finding is mapped to a regulatory requirement.
+   - Management Report / VARS: findings are aggregated by category/sub-domain with no category dropped.
+2. Confirm severity counts match the input data. For VARS: Section 3.d is **executive**
+   (a headline plus a 2–3 sentence business posture per sub-domain, no operational
+   detail); Section 4 is **department-manager** detail, with "Compliance Status" carrying
+   the tracker's Control Effectiveness Rating (Satisfactory / Improvement Recommended /
+   Unsatisfactory / N/A; worst rating across the row) and "Findings and Comments" written
+   as an inline observed → finding → comments narrative in the report's own words (no
+   source-document/clause/sample citations — those stay in the tracker) with the Actions
+   Required / Recommendations reproduced verbatim. When the ATPA archetype is in scope,
+   confirm all TPA controls are consolidated into a single "Third Party Agent" row rather
+   than scattered across the AACQ sub-domains.
+3. Check that no placeholder text remains (e.g. `{{...}}`, `____`, `MM/YEAR`).
+4. Output as Markdown. If DOCX is requested (the VARS deliverable is typically distributed as
+   DOCX to match Visa's template), **do not rely on a plain `pandoc` Markdown→DOCX conversion
+   for the Section 4 table** — pandoc collapses the `<br>` line breaks inside the wide
+   Findings-and-Comments cells, so the enumerated Actions Required / Recommendations items run
+   together and appear to be missing. Instead render the DOCX so each cell's `<br>`-separated
+   lines become **separate paragraphs** (e.g. build it with `python-docx`, or post-process the
+   pandoc output). In Section 4 specifically:
+   - split every `<br>` into its own paragraph in the cell, so each Actions Required /
+     Recommendations item is on its own visible line;
+   - render `**…**` labels (`Actions Required:`, `Recommendations:`) as real **bold**, not
+     literal asterisks;
+   - shade the **Compliance Status** cell by rating (Satisfactory = green, Improvement
+     Recommended = amber, Unsatisfactory = red, N/A = grey);
+   - set the page to **landscape** to give the table room.
+   For PDF, the same line-break requirement applies.
+
+---
+
+## Style Summaries
+
+### VARS Review Report
+
+Visa's official 2025 template, used verbatim. Six fixed sections with mandated
+boilerplate (Purpose paragraph, reliance statement, recommendation summary stem) and
+nine fixed sub-domains in canonical order — plus a consolidated **Third Party Agent**
+row when the ATPA archetype is in scope. Detailed per-control findings live in the
+companion *VARS Control Testing and Remediation Tracking* Excel — the report itself
+aggregates one row per sub-domain. The two summary layers serve different audiences:
+**Section 3.d is executive** (business posture, 2–3 sentences per sub-domain) and
+**Section 4 is for department managers / control owners** (an inline observed → finding
+→ comments narrative in the report's own words, with verbatim Actions Required /
+Recommendations and no duplication of the tracker's evidence citations).
+
+**Key sections:** Cover, Document History, Distribution List, Executive Summary
+(Purpose / Background / VARS Control Assessment / Summary of Findings / Recommendation
+Summary), Observations Overview (sub-domain table), Detailed Information (pointer to
+Excel tracker), Next Steps.
+
+**Tone:** Formal, third-person, Visa-facing. Preserve the boilerplate paragraphs
+verbatim — paraphrasing breaks reviewer expectations.
+
+### Audit Report
+
+Full technical detail. Every finding gets its own section with evidence, root cause analysis,
+remediation steps, priority, and suggested timeline. Appendices contain raw evidence.
+
+**Key sections:**
+1. Report metadata (scope, period, assessor, framework)
+2. Executive summary (pass/fail counts)
+3. Findings (one per item — full detail)
+4. Remediation plan (prioritized)
+5. Appendices (evidence, methodology, glossary)
+
+**Tone:** Technical, precise, neutral. Use passive voice sparingly. Reference specific
+controls, configurations, and code paths.
+
+### External Assessment
+
+Formal language suitable for regulatory submission. Organized by regulatory requirement,
+not by internal finding ID. Includes gap analysis matrix and attestation-ready statements.
+
+**Key sections:**
+1. Cover page and scope statement
+2. Assessment methodology
+3. Compliance status by requirement (article/section mapping)
+4. Gap analysis matrix (requirement × status × severity)
+5. Remediation roadmap
+6. Attestation statement
+7. Appendices (evidence index, assessor qualifications)
+
+**Tone:** Formal, objective, structured. Reference regulation articles explicitly
+(e.g., "Article 32(1)(a) of Regulation (EU) 2016/679"). Avoid colloquial language.
+
+### Management Report
+
+Concise, business-oriented. Leads with a one-page executive summary. Uses visual
+indicators (counts, heatmap descriptions) rather than technical evidence.
+
+**Key sections:**
+1. Executive summary (1 page max — overall posture, key risks, headline numbers)
+2. Risk heatmap (critical/major/minor counts by category)
+3. Business impact analysis (what gaps mean operationally and financially)
+4. Recommended actions with effort estimates (cost, time, owner)
+5. Progress since last assessment (if prior data available)
+6. Appendix (methodology note, detailed data reference)
+
+**Tone:** Business language, action-oriented. Quantify impact where possible.
+Avoid jargon — explain technical concepts in business terms.
+
+---
+
+## Output Conventions
+
+- **File naming:** `{style}-{framework}-{YYYY-MM-DD}.md`
+  - Example: `audit-report-SOC2-2026-03-30.md`
+  - VARS example: `vars-review-report-{acquirer}-2026-03-30.md`
+- **Severity color coding** (for Markdown rendering):
+  - 🔴 Critical | 🟠 Major | 🟡 Minor | 🔵 Observation
+- **Finding IDs:** Preserve original IDs from the input. If absent, assign sequential IDs: `F-001`, `F-002`, etc.
+- **Cross-references:** Link findings to remediation items and evidence appendices by ID.
+
+## Edge Cases
+
+- **No critical findings:** Lead the executive summary with overall compliance posture, not absence of criticals.
+- **Mixed frameworks:** If findings span multiple frameworks (e.g., SOC 2 + PCI DSS), organize by framework first, then by requirement.
+- **Incomplete evidence:** Flag as "Evidence Pending" — do not omit the finding.
+- **Prior assessment data unavailable:** Omit the "Progress" section in Management Report; note "Baseline assessment — no prior data" in methodology.
+- **VARS sub-domain with no findings:** Still include the row in Section 4 and the bullet in Section 3.d — Compliance Status "Satisfactory", Findings and Comments an inline observed-then-finding narrative closing with "No remediation required." (matching the tracker's Satisfactory Issue Description) — Visa expects all nine sub-domains to appear (plus the Third Party Agent row when ATPA is in scope).
+- **VARS legacy numbering:** The official 2025 template skips index 9 in the Section 4 table (Regulatory Risk is labelled #10). The `references/vars-report-template.md` uses sequential 1–9; switch to legacy numbering only if the Visa engagement lead asks.