@1aboveio/skills 0.20.2 → 0.20.3

package/skills/compliance/compliance-audit/SKILL.md

@@ -0,0 +1,466 @@
+---
+name: compliance-audit
+version: 2.8.3
+description: "Audit operations against a financial-compliance checklist (AML/KYC, VARS, PCI-DSS scope, TPA oversight, onboarding/transaction monitoring). Produces a control-item assessment tracker + phase trail, with layered validation (schema, citation grounding, adversarial subagents) before sign-off. Input: a checklist MD from reg-parser or the built-in VARS checklist; output: tracker.md + phase-trail.md."
+---
+
+# Compliance Audit
+
+Guide an auditor/analyst through examining operations, processes, and controls
+against a compliance checklist. Produce an assessment tracker — a worksheet
+keyed by control item that the client can update through remediation —
+alongside a phase trail companion file (work product) that preserves what each
+phase saw before the tracker was finalised.
+
+## Audience
+
+The user is a **compliance auditor or analyst** working in regulated financial
+services — payments, banking, fintech, insurance. They audit against financial
+regulatory frameworks: AML regulations, KYC requirements, financial reporting
+standards, local financial authority rules, and card-scheme standards such as
+VARS.
+
+## Audit Workflow
+
+The pipeline is eleven steps in three phases:
+
+| Phase | Steps | Purpose |
+|---|---|---|
+| **Setup** | 0–4 | Preprocess evidence, load checklist, scope, plan phases, map evidence to controls |
+| **Review** | 5–7 | Run review phases (document / onsite / sample), synthesize tracker rows |
+| **Sign-off** | 8–10 | Produce deliverables; run layered validation (deterministic + LLM judge + adversarial challenger); normalize formatting before reviewer sign-off |
+
+For large audits the **chunked** path (Step 6 onward) parallelises across control groups via subagents; the unchunked path (Step 5) is sequential. Pick based on size — VARS (45 controls) and similar always benefit from chunking.
+
+### Step 0: Preprocess Evidence Documents (if needed)
+
+If evidence files are in binary formats (PDF, DOCX, PPTX, XLSX, images), spawn a subagent to convert them to markdown before the audit begins.
+
+- **Model:** **Small / fast tier.** This is mechanical doc conversion. Capability above the small tier is wasted here.
+- **Task prompt:**
+
+```text
+Convert all documents in <evidence-dir>/ to markdown using the doc-to-md skill.
+Run: python3 {doc-to-md baseDir}/scripts/convert.py <evidence-dir>/ <evidence-md-dir>/
+Report which files succeeded and which failed (if any).
+```
+
+Wait for the subagent to complete before proceeding. Skip this step if evidence is already in text/markdown format.
+
+### Step 1: Load the Checklist
+
+1. Read the compliance checklist file provided by the user.
+2. Parse control IDs, control titles, archetypes / categories, severity, requirement text, and control criteria.
+3. Confirm the checklist loaded correctly — list the control groups and total controls in scope.
+
+If no checklist is provided, ask the user for the path to their checklist file.
+
+### Step 2: Scope the Audit
+
+Determine scope with the user:
+
+- **Full audit** — all controls in the checklist.
+- **Targeted audit** — specific archetypes, categories, or control IDs only.
+
+Confirm scope before proceeding. Record scope in the tracker metadata header.
+
+### Step 3: Establish the Phase Plan
+
+The audit runs through up to three review phases on the same control set, plus a synthesis step that produces the tracker:
+
+1. `document_review` (phase)
+2. `onsite_review` (phase)
+3. `sample_test` (phase)
+4. tracker synthesis (Step 7) — consolidates whichever phases ran into `tracker.md`
+
+Phases are **optional and additive** — many engagements stop after `document_review` (a gap analysis) or skip `onsite_review` for remote audits. Confirm with the user which phases are in scope and record the chosen subset under `Audit Phases Completed` in the tracker header. The tracker rating is always produced as the synthesis of whichever phases ran.
+
+Rules:
+
+- Each phase updates the same `Control ID` records in `phase-trail.md` rather than creating disconnected findings.
+- The tracker (`tracker.md`) is the consolidated deliverable after the completed phases.
+- `Control Effectiveness Rating` (VARS) or `Effectiveness` (generic) is required because it drives the tracker rating.
+- `Recommended Action Ref` is optional. If a co-located best-practice repository keyed by `Control ID` exists, point to it (e.g. `best-practice://AACQ.C14.1`); otherwise inline a one-line remediation pointer or omit. Do not invent links to repositories that do not exist.
+
+### Step 4: Evidence Mapping
+
+Map evidence to controls or logical control groups before reviewing:
+
+```text
+AACQ.C1.1   risk-appetite-policy.md, board-minutes.md
+AACQ.C5.1   underwriting-policy.md, onboarding-procedure.md
+ATPA.C8.1   monitoring-rules.md, alert-log-sample.md
+```
+
+Only the mapped evidence for a control or control group should be passed into that review pass.
+
+### Step 5: Run the Audit Phase
+
+For each phase in scope, review the controls and record phase-specific observations into `phase-trail.md` using the appropriate schema:
+
+- **VARS audits:** `references/vars-findings-schema.md` (Visa-canonical tracker + per-mandatory-item granularity).
+- **All other audits:** `references/findings-schema.md` (generic per-Control-ID tracker).
+
+`phase-trail.md` is the audit work product across all phases. The tracker (`tracker.md`) is produced from it in Step 7.
+
+Step 5 is the **non-chunked** path; for large audits skip to Step 6. Each phase below appends a phase block per `Control ID` to `phase-trail.md` using Variant A in the chosen schema.
+
+#### Phase 5A: Document Review
+
+Input: policy documents, procedures, agreements, governance materials, system descriptions.
+
+Record `document_review` observations per `Control ID`.
+
+#### Phase 5B: Onsite Review
+
+Input: interview records, walkthrough notes, live demonstrations, operating context.
+
+Record `onsite_review` observations per `Control ID` and note whether onsite work confirms, weakens, or strengthens document-review conclusions.
+
+#### Phase 5C: Sample Test
+
+Input: sample evidence such as merchant files, alerts, case logs, transactions, approvals, reports, screenshots.
+
+Record `sample_test` observations per `Control ID` and capture concrete evidence of operating effectiveness.
+
+### Step 6: Chunked Workflow for Large Audits
+
+When the checklist or evidence is large, the **main agent orchestrates** and **spawns one subagent per control group / category** for each phase. Phase outputs are kept in per-group files and consumed directly by Step 7 — there is no merge step in between.
+
+#### Step A: Prepare a bounded prompt
+
+Before spawning, group controls into logical chunks and attach only the relevant evidence. Extract only the rows for the chunk's `Control ID`s from the checklist — never paste the full checklist into a subagent prompt. The full checklist can be hundreds of KB and bloats every subagent's context.
+
+```text
+Group 1: AACQ Risk Appetite and Written Agreements
+Controls: AACQ.C1.1, AACQ.C2.1, AACQ.C3.1, AACQ.C4.1
+Evidence: risk-appetite-policy.md, merchant-agreement-template.md
+```
+
+#### Step B: Spawn subagents per chunk
+
+- **Model:** **Mid tier.** Per-phase review needs careful reasoning across a control's evidence; a small model will miss subtle gaps.
+- **Output schema:** Pick the same schema chosen in Step 5 — generic (`findings-schema.md`) or VARS (`vars-findings-schema.md`). Each schema file owns two subagent prompt templates: **Variant A** for per-phase chunking (this step) and **Variant B** for synthesis chunking (Step 7). Use Variant A here. Do not improvise a third format.
+- **Task prompt skeleton** (fill the bracketed slots from Variant A in the schema):
+
+```text
+You are a compliance auditor. Review the following controls for the specified audit phase.
+
+Audit phase: <document_review | onsite_review | sample_test>
+Controls:
+<paste only the checklist rows for these Control IDs>
+
+Evidence:
+<paste mapped evidence only>
+
+Output format:
+<paste the Variant A block from the chosen schema's "Subagent Prompt Template" section>
+
+Rules:
+- Never mark a control effective without direct evidence.
+- If evidence is absent or ambiguous, mark the gap and explain why.
+- Keep observations specific to this phase.
+- Output observations only.
+```
+
+- **Output:** Each subagent writes phase observations to `phase-<phase>-<group>.md`.
+- **Parallelism:** Spawn all independent chunks concurrently. No merge step is required at this point — Step 7 consumes the per-group phase files directly.
+
+### Step 7: Synthesize Tracker (chunked)
+
+Synthesis is **chunked the same way as Step 6**. The full per-control tracker plus phase trail can blow main-agent context on a 45-control VARS audit; spawn one synthesis subagent per control group.
+
+Use the **same group definitions** as Step 6 so each synthesis subagent reads its group's `phase-<phase>-<group>.md` files and emits both:
+
+1. tracker rows (deliverable)
+2. merged phase-trail blocks (audit work product)
+
+…for that group only.
+
+#### Step A: Spawn synthesis subagents per group
+
+- **Model:** **Mid tier.** Synthesis consolidates multiple phases per Control ID and applies the rubric; needs balanced reasoning. Don't use a small model here.
+- **Output schema:** Variant B in the chosen schema file (`vars-findings-schema.md` or `findings-schema.md`).
+- **Task prompt skeleton** (fill the bracketed slots from Variant B):
+
+```text
+You are a compliance auditor consolidating an assessment.
+
+Controls in scope (this group):
+<paste only the checklist rows for these Control IDs>
+
+Phase trail blocks (all completed phases for these Control IDs):
+<paste contents of phase-<phase>-<group>.md for every phase that ran>
+
+Output format:
+<paste the "Subagent Prompt Template — Variant B" block from the chosen schema file>
+```
+
+- **Output:** Each subagent writes `synth-<group>.md` containing tracker rows, then a `---` separator, then merged phase-trail blocks.
+- **Parallelism:** Spawn all groups concurrently.
+
+#### Step B: Assemble final files
+
+Once synthesis subagents complete, the main agent:
+
+1. Reads each `synth-<group>.md`.
+2. Splits each file on the `---` separator into tracker-rows half and phase-trail half.
+3. Concatenates all tracker-rows halves under the audit-metadata header and the table header into `tracker.md`.
+4. Concatenates all phase-trail halves under the `# Phase Trail` (or `# VARS Phase Trail`) heading into `phase-trail.md`.
+5. Verifies every Control ID in scope appears in both files.
+
+The main agent does **not** rewrite or re-rate findings during assembly — that work happened in the subagents. Assembly is concatenation + sanity check only.
+
+### Step 8: Deliverables
+
+Two files:
+
+- `tracker.md` — the deliverable. One row per Control ID under a metadata header. For VARS, per-mandatory-item detail (`Control 1a:`, `Control 1b:`, …) appears as bulleted entries inside the Observations cell. No executive summary, no roll-up counts, no critical-gaps section.
+- `phase-trail.md` — the audit work product. Per-Control-ID phase-by-phase record. Preserves observations from `document_review`, `onsite_review`, `sample_test` as they were captured.
+
+Treat the checklist as the control library and the schema as the tracker format. If the client wants a roll-up or executive summary, generate it from the tracker on demand — do not write one into the deliverable.
+
+### Step 9: Validate the Tracker
+
+Before sign-off, run a layered validation pass to catch hallucination, schema drift, and over-claimed coverage. The four sub-steps are cheap-to-expensive; run **9A and 9B always**, run **9C and 9D for high-stakes deliverables** (e.g. VARS findings sent to a regulator).
+
+#### Step 9A: Structural validation (deterministic)
+
+Run `scripts/validate_tracker.py` against the produced tracker:
+
+```bash
+python3 {compliance-audit baseDir}/scripts/validate_tracker.py tracker.md \
+  --checklist {compliance-audit baseDir}/references/vars-checklist.md
+```
+
+Checks performed:
+
+- `row_coverage` — every scoped Control ID has exactly one tracker row.
+- `item_coverage` — every numbered checklist item appears as a `Control N:` bullet in Observations.
+- `rating_value` — `Control Effectiveness Rating` is one of the four canonical outcomes: `Satisfactory` / `Improvement Recommended` / `Unsatisfactory` / `N/A`.
+- `rubric_consistency` — the rating obeys the VARS rubric (any mandatory item `Partial` or `Not addressed` ⇒ Unsatisfactory; all mandatory met but a recommended item missing/partial ⇒ Improvement Recommended; all covered ⇒ Satisfactory; `N/A` rows are exempt). Coverage rolls up: a leaf with no bullet inherits its nearest bulleted ancestor's status.
+- `gap_xref` — every `(Control N)` / `[Control N: …]` referenced in Issue Description corresponds to a `Not addressed` or `Partial` Observation bullet (a Recommendations entry may also point to a `Covered` mandatory item flagged for strengthening).
+
+Exit 0 = no errors. Errors are blocking; warnings are surfaced for reviewer judgement. Use `--strict` to fail on warnings too.
+
+#### Step 9B: Citation grounding (deterministic, requires evidence dir)
+
+Add `--evidence` to the same script:
+
+```bash
+python3 {compliance-audit baseDir}/scripts/validate_tracker.py tracker.md \
+  --checklist {compliance-audit baseDir}/references/vars-checklist.md \
+  --evidence ./evidence-md/
+```
+
+For every `Covered in <doc> section <clause>` citation, the script verifies the doc resolves to an evidence markdown file and the cited clause string actually appears in that file. Phantom citations (clause does not exist) are flagged as warnings.
+
+#### Step 9C: Citation judge (subagent — clean context)
+
+Spawn one subagent **per control group** (same chunking as Steps 6–7) using **Variant C** in the schema's "Subagent Prompt Template" section. The subagent receives **only**:
+
+- the checklist rows for its group (with full Verification text),
+- the tracker rows for its group (Observations + Issue Description),
+- the cited evidence excerpts.
+
+It does **not** see the phase trail, other groups' findings, or any synthesis context. Clean context is the point — the judge must verify each citation cold.
+
+- **Model:** **Small / fast tier.** Citation verification is local clause-vs-requirement comparison; a small model handles it well at a fraction of the cost.
+- **Output:** `judge-<group>.md` with per-bullet verdicts (`Confirmed` / `Weak` / `Off-target` / `Missing`).
+- **Parallelism:** Spawn all groups concurrently.
+
+The main agent collates non-`Confirmed` verdicts into a Citation Judge Report attached to the tracker for reviewer attention.
+
+#### Step 9D: Adversarial challenger (subagent — clean context, adversarial system prompt)
+
+Spawn one subagent **per control group** using **Variant D** in the schema. The subagent runs with an **explicit adversarial system prompt**: assume the prior auditor was too generous and look for downgrades.
+
+Critical: this subagent must run with **clean context** — no access to the phase trail, judge findings, or synthesis reasoning. It must form its own challenge from the checklist + tracker + evidence only. Otherwise it will rationalise rather than challenge.
+
+- **Model:** **Mid tier** for routine audits; **large / top-tier** for regulator-facing deliverables where a missed challenge is costly. The challenger has to form a credible adversarial read and articulate concrete downgrades — a too-small model will rubber-stamp.
+- **System prompt:** Variant D in the schema. The system prompt itself frames the adversarial stance — do not soften it in the wrapper.
+- **Output:** `challenge-<group>.md` listing concrete recommended downgrades per coverage claim, with requirement reference and specific weakness.
+- **Parallelism:** Spawn all groups concurrently.
+
+The main agent collates challenges into a Challenge Report. The reviewer reads it and decides per-challenge whether to accept the downgrade before finalising the tracker.
+
+#### Step 9E: Reconcile validated findings into the tracker
+
+Steps 9A–9D produce side files. Step 9E **applies the deterministic ones to `tracker.md`** so hallucinated coverage doesn't survive into the deliverable. The split is deliberate: auto-apply only what's mechanically verifiable; surface the rest for the reviewer.
+
+| Source | Treatment |
+|---|---|
+| 9B citation_grounding "missing clause" warnings | **Auto-apply.** The cited `section X` exact-string isn't in the evidence file, so the citation is hallucinated. Bullet flips `Covered`/`Partial` → `Not addressed — cited clause section X not found in DOC`. |
+| 9C judge verdict `Off-target` | **Auto-apply.** Judge confirmed the cited clause doesn't address the requirement. Bullet flips → `Not addressed — judge: <reason>`. |
+| 9C judge verdict `Missing` | **Auto-apply.** Judge couldn't locate the cited clause. Bullet flips → `Not addressed — judge: <reason>`. |
+| 9C judge verdict `Weak` | **Reviewer-mediated.** Judge says clause references the topic but doesn't operationalise it. Surfaced in `reconciliation.md` for human decision; tracker untouched. |
+| 9D challenger recommendations | **Reviewer-mediated.** These are explicit value judgements, not facts. Surfaced in `reconciliation.md`. |
+
+Run the reconciler:
+
+```bash
+python3 {compliance-audit baseDir}/scripts/reconcile_tracker.py tracker.md \
+  --checklist {compliance-audit baseDir}/references/vars-checklist.md \
+  --validation validation.json \
+  --judge judge-aacq.json \
+  --judge judge-atpa.json \
+  --log reconciliation.md
+```
+
+`--validation` takes the JSON output of `validate_tracker.py --json` (re-run with `--json` to capture it). `--judge` may be passed multiple times to merge per-group judge sidecars.
+
+The reconciler:
+
+1. Parses `tracker.md` and the checklist.
+2. Walks every Observations bullet. For each "auto-apply" finding hitting that bullet, transforms the bullet text and flips its status to `Not addressed`.
+3. Recomputes the row's Control Effectiveness Rating per the rubric using the new statuses.
+4. Updates Issue Description: adds the newly-confirmed gap to **Actions Required** (mandatory) or **Recommendations** (recommended-only).
+5. Writes the updated tracker (default: in place) and a `reconciliation.md` log of every change plus the reviewer-mediated items still pending.
+
+After 9E runs, re-run 9A as a final structural check on the reconciled tracker. The reviewer then works through `reconciliation.md`'s "pending review" section before sign-off.
+
+### Step 10: Normalize Deliverable Formatting
+
+Subagents and reconciler edits produce stylistically inconsistent Observations cells — some bullets are plain text, some bold the item number (`**(1)**`, `**1d**`), some bold the prefix (`**Control 1d:**`), some omit the `Control` prefix entirely, some use `-` instead of `•`, some break with newlines instead of `<br>`. Step 10 enforces the canonical format so the deliverable looks like one document, not a stitched collage.
+
+This step is **purely cosmetic** — it must not change ratings, statuses, citations, or which items are present. If a normalization rule would alter meaning, leave the bullet alone and flag it in `normalization.md` for the reviewer.
+
+Run normalization **after** Step 9E reconciliation and **before** the reviewer sign-off gate. Re-run Step 9A (structural validation) afterwards to confirm nothing broke.
+
+#### Canonical Observations bullet format
+
+Per `vars-findings-schema.md` and `findings-schema.md`:
+
+- Bullet character: `•` (matches Visa VCA convention). Not `-`, `*`, or `–`.
+- In-cell line break: `<br>` between bullets. No literal newlines inside a table cell.
+- Item prefix: `Control <item>:` — e.g. `Control 1a:`, `Control 3.i:`, `Control 1:` (when the checklist row has no sub-items). No bolding of the prefix or the item number.
+- Status phrase: exactly one of
+  - `Covered in <doc> section <clause>` (or `Covered in <doc> section <clause-a> and section <clause-b>` for multiple references)
+  - `Partial — <what's weak>`
+  - `Not addressed` (optionally `Not addressed — <reason>` after 9E auto-applies)
+- Em-dash: `—` (U+2014). Not `--`, `-`, or `–`.
+
+#### Canonical Issue Description format
+
+- Up to two labelled groups, each on its own `<br>`-separated line. **Include only the non-empty groups** — omit a group's heading entirely (do not write `**Recommendations:** —`):
+  - `**Actions Required:** — Missing controls under mandatory controls` (mandatory items rated `Partial` / `Not addressed`)
+  - `**Recommendations:** — Mandatory controls can be improved and/or missing recommended controls` (unmet recommended items + mandatory strengthening)
+- Under each label, list gaps with lowercase roman enumerators: a bracketed item reference (Actions Required carries status; Recommendations may omit it), then ` — ` and a one-line action/recommendation — e.g. `(i) [Control 2.c: Partial] — Document the VMSS listing procedure.`, `(i) [Control R1.c] — Add an Acquirer disclosure clause.`
+
+#### Normalization rules (mechanical rewrites)
+
+The pass walks every Observations cell and Issue Description cell and applies these rewrites in order:
+
+1. **Bullet character.** Leading `-`, `*`, `–`, or unicode bullet variants → `•`.
+2. **Line breaks.** Literal `\n` between bullets in a cell → `<br>`. Collapse runs of `<br>` to a single `<br>`.
+3. **Strip stray bolding around the item label.** `**Control 1d:**` → `Control 1d:`; `**(1)** ...` → `Control 1: ...`; `**1d**: ...` → `Control 1d: ...`.
+4. **Add missing `Control` prefix.** A bullet that opens with the item alone (`1d: ...`, `(1d) ...`, `Item 1d — ...`) → `Control 1d: ...`. Item ids are matched against the checklist row's numbered items; if no match, leave the bullet alone and log it.
+5. **Status phrase casing.** Lowercase variants of `Covered`, `Partial`, `Not addressed` → canonical case. `n/a`, `N/A`, `Not applicable` outside the rubric → leave and log (rubric only allows the three statuses; this is a real issue).
+6. **Em-dash.** ` -- ` or ` - ` separating status from explanation → ` — `.
+7. **Whitespace.** Trim trailing spaces inside cells; collapse double spaces; ensure a single space after `Control <item>:`.
+8. **Issue Description groups.** Each group label sits on its own `<br>`-separated line, followed by `(i)/(ii)/(iii)` roman-enumerated `[Control <id>: <status>] — <one-line action>` entries (not `•` bullets — those are Observations-only). Include only non-empty groups; omit an empty group's heading entirely (never pad with `—`). If gap content exists with no label, wrap it under `**Actions Required:**` (safer default — mandatory) and log for reviewer to confirm.
+9. **Issue Description vs rating.** A `Satisfactory` row's cell reads exactly `No remediation required.`; an `N/A` row has a blank cell. An `Unsatisfactory` row has an Actions Required group with ≥1 entry (a mandatory `Partial`/`Not addressed`). An `Improvement Recommended` row has only a Recommendations group (no Actions Required heading). The script reads the checklist to tell recommended from mandatory item ids; if it can't, it leaves the cell alone and logs the row.
+
+The pass does **not**:
+- Rewrite the substance of any observation (e.g., it never changes "Partial" to "Not addressed" or vice versa).
+- Move bullets between Observations and Issue Description.
+- Add or remove items.
+- Touch the `Control Effectiveness Rating` column.
+
+#### How to run
+
+A deterministic script handles the mechanical rewrites:
+
+```bash
+python3 {compliance-audit baseDir}/scripts/normalize_tracker.py tracker.md \
+  --checklist {compliance-audit baseDir}/references/vars-checklist.md \
+  --log normalization.md
+```
+
+`normalization.md` records every rewrite plus any bullet the script declined to normalize (unmatched item id, ambiguous status phrase, missing group label with content). The reviewer skims this before sign-off.
+
+If the script is not available, the main agent can perform the same rewrites in-place — but only the mechanical ones in the list above. Anything ambiguous goes in `normalization.md`, not silently into the tracker.
+
+After normalization, re-run Step 9A:
+
+```bash
+python3 {compliance-audit baseDir}/scripts/validate_tracker.py tracker.md \
+  --checklist {compliance-audit baseDir}/references/vars-checklist.md
+```
+
+Zero errors before proceeding to the sign-off gate.
+
+#### Reviewer sign-off gate
+
+Before delivering `tracker.md` to the client, the human reviewer must:
+
+1. Confirm Step 9A passes with zero errors against the **reconciled and normalized** tracker.
+2. Read `reconciliation.md`. Confirm the auto-applied changes (9B phantom citations, 9C `Off-target` / `Missing` verdicts) are correct — these are the most mechanical and should rarely need intervention.
+3. Work through `reconciliation.md`'s "pending review" section: 9C `Weak` verdicts and 9D challenger recommendations. Accept or reject each, recording the decision.
+4. Confirm any 9B warnings that the reconciler couldn't auto-apply (e.g. ambiguous citations) are resolved or documented as exceptions.
+5. Skim `normalization.md`. Confirm any bullets the normalizer declined to rewrite (unmatched item ids, ambiguous status phrases) are real issues to fix — not formatting noise to ignore.
+
+The reviewer's sign-off — not the tooling's pass — is what makes the tracker deliverable.
+
+## Built-in Checklists
+
+The following checklist is bundled locally in `references/` and can be loaded directly:
+
+- `references/vars-checklist.md` — Visa VARS control library (table format) keyed by Visa `Control ID` across `AACQ`, `ATPA`, `AHIR`, `AATM`, and `AVDC`. Pair with `references/vars-findings-schema.md` for the tracker format.
+
+To use a built-in checklist, load it in Step 1 instead of asking the user to provide one.
+
+## VARS Audits
+
+VARS governs acquirer obligations under the Visa network across five archetypes (45 sub-controls total):
+
+| Archetype | Code | Applies To | Sub-controls |
+|-----------|------|------------|--------------|
+| All Acquirers | AACQ | Every Visa acquirer | 22 |
+| TPA Sponsors | ATPA | Acquirers sponsoring Third-Party Agents | 15 |
+| High Integrity Risk | AHIR | Acquirers in the VIRP programme | 1 |
+| ATM Acquirers | AATM | Acquirers operating ATM networks | 5 |
+| Visa Direct Clients | AVDC | Acquirers enabling Visa Direct | 2 (recommended-only) |
+
+**At audit start:**
+- Confirm which archetypes apply to the entity. Skip non-applicable parts (e.g., skip ATPA if the acquirer does not sponsor TPAs).
+- Load `references/vars-checklist.md` (control library) and follow `references/vars-findings-schema.md` (tracker output).
+- Tracker rows are **per Control ID**. Per-mandatory-item detail (`1a`, `1b`, `3.i`, …) is captured as bulleted entries inside the Observations cell, prefixed `Control 1a:`, `Control 1b:`, etc., per Visa VCA convention.
+- Use the Visa effectiveness rubric (Satisfactory / Improvement Recommended / Unsatisfactory / N/A; a mandatory `Partial` or `Not addressed` is Unsatisfactory). Do **not** import a critical/major/minor severity scheme.
+
+**Key evidence areas:**
+- Risk appetite policy (board-approved, version-controlled)
+- Merchant agreements and underwriting records
+- VMSS/sanctions screening logs at onboarding and ongoing
+- Transaction monitoring rules, alert logs, investigation records
+- Suspicious activity reporting (SAR) records and procedures
+- PCI DSS certification and data security documentation
+- TPA agreements, underwriting files, monitoring reports (ATPA only)
+- VIRP registration documentation (AHIR only)
+- ATM operator agreements and KYO verifications (AATM only)
+
+## Additional Checklists from reg-parser
+
+For standards not listed above, check `{reg-parser baseDir}/references/checklists/` — additional checklists are added there as they are extracted. Load the relevant checklist and apply the same phased workflow.
+
+## Guidelines
+
+- **One control at a time.** Within any review pass — whether the main agent or a subagent chunk — work through controls one by one. Chunking (Step 6) parallelises *across* control groups but the work *within* a chunk is still sequential, control by control.
+- **Evidence first.** Never mark PASS / Green / Satisfactory without reviewing actual evidence.
+- **Phase-specific observations.** Keep document, onsite, and sample-test conclusions distinct before synthesizing.
+- **Be specific.** Observations reference concrete documents, records, interviews, or test samples.
+- **No assumptions.** If evidence is unavailable, mark FAIL / PARTIAL / Unsatisfactory or request more evidence.
+- **Preserve checklist structure.** Findings map 1:1 to `Control ID` records.
+- **Keep the audit trail.** `tracker.md` is the deliverable but `phase-trail.md` is the defensible record — never overwrite phase observations when finalising the tracker.
+- **Model selection.** Match the subagent's model tier to the cognitive load of its task. Adversarial-stance and synthesis work needs more capability; mechanical tasks (doc conversion, citation lookup) do not. Tiers are vendor-neutral — pick whatever your provider offers at each tier.
+
+| Step | Task character | Recommended tier |
+|---|---|---|
+| Step 0 — evidence preprocessing | Mechanical doc conversion (binary → md) | **Small / fast** |
+| Step 6B — per-phase review | Careful reasoning across a control's evidence | **Mid** |
+| Step 7A — tracker synthesis | Multi-phase consolidation per Control ID | **Mid** |
+| Step 9C — citation judge | Local clause-vs-requirement comparison | **Small / fast** |
+| Step 9D — adversarial challenger | Forming a credible challenge, recommending downgrades | **Mid** for routine; **large / top-tier** for regulator-facing audits |
+| Step 10 — normalize formatting | Mechanical text rewrites against a fixed rule set | **Deterministic script** (no model); fallback **Small / fast** |
+
+Don't run synthesis or the adversarial challenger on a small model — token savings are dwarfed by re-runs caused by sloppy outputs. Don't run preprocessing or the citation judge on a mid-tier model — there's no reasoning improvement to justify the cost.