---
# ─────────────────────────────────────────────────────────────────────────────
#  Skill: regulatory-logging  ·  .claude/skills/regulatory-logging/SKILL.md
#  QRefAI AI Coding Field Guide, Part 2 (Q2.3)
#
#  A skill is a TASK PLAYBOOK loaded on demand — not always-on memory. It follows
#  the open SKILL.md standard (agentskills.io), so this same file works on Copilot
#  under .github/skills/<name>/SKILL.md, unchanged.
#
#  ┌── THE `description` IS DOING REAL WORK ──────────────────────────────────┐
#  │ It is the ONLY thing loaded at rest (~80 tokens), and it is how the agent  │
#  │ DECIDES whether to load the rest of this skill. Write it with EXPLICIT     │
#  │ TRIGGER CONDITIONS — literally "Use whenever…". A vague description means   │
#  │ the skill never fires and all the work below is dead weight.               │
#  └───────────────────────────────────────────────────────────────────────────┘
# ─────────────────────────────────────────────────────────────────────────────
name: regulatory-logging
description: >
  Rules for audit logging in payment flows. Use whenever code creates, modifies,
  or deletes a financial transaction, or touches the audit_events table.
---

# Regulatory Logging

Every state change to a transaction MUST emit an audit event.

## Required fields
- `actor_id`, `actor_type` (human | service | agent)
- `before_state`, `after_state` (redacted per references/redaction-rules.md)
- `correlation_id`, `timestamp` (UTC, RFC3339)

## How to emit
Call `audit.Emit(ctx, event)` — never write to `audit_events` directly.

## Retention
7 years. Never write code that deletes from `audit_events`.

## Validation
Before considering a change complete, run:
  `scripts/check-audit-coverage.sh <changed-files>`
to confirm every transaction mutation has a matching emit. See the script header
for usage.

<!--
  PROGRESSIVE DISCLOSURE — keep THIS body lean (~a screen, ~2k tokens median).
  Push bulk DOWN into the subfolders; they cost 0 tokens until a step opens them:

    references/   long checklists, rule tables, regulatory mappings (read on demand)
    scripts/      executable validators / helpers the agent runs
    assets/       templates, boilerplate, example payloads the agent copies from

  If a section here grows past a few paragraphs, move it to references/ and link it.
-->