Audit Log Architect

---
name: audit-log-architect
description: Design a durable, tenant-scoped audit log system with an event taxonomy, record schema, append-only integrity, write-failure policy, retention, redaction, scoped reads, and negative tests. Include rollout and safe rollback for a live system. Use for audit logging and compliance trails such as System and Organization Controls 2 (SOC 2), International Organization for Standardization/International Electrotechnical Commission (ISO/IEC) 27001, or customer contracts. Do NOT use for external event contracts (api-event-architect), observability, security detection and alerting (security-logging-alerting-architect), or permission design (authorization-matrix-designer).
---

# Audit Log Architect

Here, **ISO/IEC 27001** is the information-security management standard of
the International Organization for Standardization and International
Electrotechnical Commission. **PII** means personally identifiable
information, **IP** means Internet Protocol, **ORM** means object-relational
mapper, **DB** means database, **API** means application programming
interface, and **WORM** means write once, read many. **SOC 2** means System
and Organization Controls 2, an independent auditor's report on a service
organization's controls.
**HIPAA** means the United States Health Insurance Portability and
Accountability Act; whether it applies depends on the actual system and data.

## Purpose

Produce an audit system that can answer "who did what, to what, in which
tenant, when, and what happened" — durably, provably, and without leaking one
tenant's activity to another. Deliverables: an event taxonomy, a record
schema, integrity and failure-policy rules, retention/redaction policy, a
tenant-scoped access model, negative tests, and a plan for introducing it to
a live system. An audit log differs from application logging in exactly the
properties people skip: completeness by taxonomy, immutability, and scoped
access — a grep-able stdout stream is not an audit trail.

## Use When

- Use when: compliance (SOC 2, ISO/IEC 27001, HIPAA-adjacent, enterprise
  contracts) requires demonstrable audit trails.
- Use when: audit-worthy actions are currently ad-hoc `logger.info` calls
  with no schema, durability, or access story.
- Use when: designing tenant-facing audit views ("show my workspace's
  activity") or staff-action accountability (support access must be
  auditable).
- Use when: an incident post-mortem revealed you cannot reconstruct who did
  what.
- Do NOT use when: designing events that INTEGRATIONS consume (webhooks,
  event feeds) — that is `api-event-architect`; audit events are a record,
  not an integration contract, even when one action produces both.
- Do NOT use when: the need is debugging/observability (traces, metrics,
  app logs) — different retention, different audience, different guarantees.
- Do NOT use when: deciding who is ALLOWED to act — that is
  `authorization-matrix-designer`; this skill records what they did.
- Do NOT use when: designing security detection and alerting (what must
  fire, thresholds, owners) — that is `security-logging-alerting-architect`;
  this skill designs the audit record, which never detects or alerts.

## Inputs to Inspect

1. The authorization design (authorization-matrix-designer output): sensitive
   permissions, cross-tenant platform roles, and brokered-access rules — each
   implies required audit events.
2. The tenant model: tenant boundary, lifecycle states (audit retention must
   survive offboarding questions), membership semantics for actor identity.
3. Current logging: what is emitted today, from where, with what fields —
   the gap between it and the taxonomy is the work.
4. Compliance requirements naming specific events, retention periods, or
   access rules (SOC 2 criteria, contractual audit clauses).
5. Data-sensitivity constraints: what may never appear in an audit payload
   (secrets, credentials, full PII records).
6. Volume expectations: events/day at the taxonomy's scope — drives storage
   and the high-volume design decisions.

## Workflow

For any user-facing build choice, define terms and each viable path's purpose;
compare case-specific pros/cons and money, setup, and maintenance costs (mark
unknowns). Recommend one and why, then ask one atomic decision question. If a
deciding fact is missing, ask only for that fact this turn. A choice does not
authorize execution.

1. **Build the event taxonomy** from the starter set in
   [references/audit-event-taxonomy.md](references/audit-event-taxonomy.md):
   authentication, access-control changes, data access/export, admin and
   support actions, security events, billing/plan changes, lifecycle
   transitions. For each category: which concrete actions MUST be recorded.
   The taxonomy is the completeness contract — an unlisted action is a
   decision, not an oversight.
2. **Define the record schema**: actor (user/service/support-grant id, never
   just "admin"), on-behalf-of for impersonation, tenant id, action (from the
   taxonomy), target (type + id), outcome (success/denied/failed), timestamp,
   correlation/request id, origin (IP/user-agent where policy allows), and a
   redacted details payload. Schema versioned from day one.
3. **Set integrity rules**: append-only store — no update or delete API
   exists; tamper-evidence proportional to requirements (restricted DB
   permissions at minimum, hash-chaining/WORM storage where contracts demand
   it); clock source stated.
4. **Decide the write-failure policy per category** — the question that
   distinguishes audit from logging: if the audit write fails, does the
   action proceed? Security-critical categories (access-control changes,
   impersonation, exports) fail closed or queue-with-guarantee; lower
   categories may fail open with an alert. Write the policy down per
   category.
5. **Define retention and redaction**: retention per category (compliance
   floor, cost ceiling), what redaction removes from payloads before write
   (secrets always; PII per policy), and whether audit records survive tenant
   purge (usually yes, in de-identified or platform-scoped form — state it,
   it is a legal decision → flag to the human).
6. **Design the access model**: tenant admins read their own tenant's
   events only (scoped views); platform/staff audit access is itself an
   audited action; no general-purpose query access to the raw store.
   Support-facing and tenant-facing views may differ in fields — say how.
7. **Write the negative-test plan**: cross-tenant audit read denied;
   update/delete attempts on audit records fail at the store level; an
   audited action performed without a resulting event = test failure
   (completeness probe on the top sensitive actions); impersonation without
   an audit event fails.
8. **Plan the rollout to a live system**: emit-only first (no consumer),
   verify volume and schema against real traffic, then attach views and
   alerts; backfill is usually impossible — state the audit-coverage start
   date honestly rather than fabricating history. Rollback may disable
   optional emission per category; for a security-critical category, retain
   the fail-closed or guaranteed-queue policy until a reviewed coverage
   change is approved. Already-written records are never deleted.

## Output Format

When asking for a build choice, show the explained options and justified
recommendation before the one question.

```
AUDIT LOG DESIGN — <product/scope>
Event taxonomy: <category → concrete actions recorded; explicit exclusions
  with rationale>
Record schema: <fields, versioned; impersonation via on-behalf-of>
Integrity: <append-only mechanism; tamper-evidence level; clock source>
Write-failure policy: <category → fail-closed / queued-guaranteed /
  fail-open+alert>
Retention & redaction: <category → retention; payload redaction rules;
  post-purge policy (flagged as legal decision)>
Access model: <tenant-scoped views; staff access audited; raw-store access:
  none>
Negative-test plan: <test — attempted violation — expected result>
Rollout & rollback: <emit-only → verify → attach consumers; coverage start
  date; optional-category disable only; mandatory coverage retained;
  records never deleted>
Assumptions & open questions: <each with risk-if-wrong / who answers>
```

## Validation Checklist

- [ ] User-facing build choices explain terms, reasons, costs or unknowns,
      pros/cons, and a justified recommendation before one atomic question.
- [ ] Every sensitive permission and brokered-access rule from the
      authorization design has a corresponding audit event.
- [ ] Actor is always a resolvable identity; impersonation carries both
      identities via on-behalf-of.
- [ ] No update/delete path exists to audit records; the mechanism is named.
- [ ] Write-failure policy is explicit per category — the fail-open/closed
      question is answered, not dodged.
- [ ] Payload redaction rules exist; secrets can never be written.
- [ ] Tenant admins can read only their tenant; staff audit reads are
      themselves audited.
- [ ] Negative tests cover cross-tenant reads, tampering, and completeness
      (action-without-event).
- [ ] Rollout starts emit-only and rollback never deletes written records.
- [ ] Audit events are not conflated with integration webhooks or app logs.

## Tenant Isolation Rules

- Every audit event carries the tenant id (or an explicit `platform` scope
  for tenant-less staff actions); there is no ambiguous scope.
- Tenant-facing audit queries are scoped at the store/view layer, not by
  application-side filtering of a global table.
- Cross-tenant audit access (staff, regulators) is enumerated, brokered, and
  produces its own audit events.

## Security Rules

- Append-only is a property of the store's permissions, not a code
  convention — the application role used for writes has no UPDATE/DELETE.
- Secrets, tokens, and credentials never enter payloads; redaction runs
  before write, not at read time.
- Security-critical actions (access-control changes, impersonation, exports)
  must not silently proceed when auditing is unavailable — per the stated
  fail-closed/queued policy.
- Negative tests are part of the deliverable; an audit system without a
  tamper test and a completeness probe is a logging system.

## Gotchas

- High-volume read events (every record view) can swamp the store; the
  taxonomy may record reads at coarser grain (search performed, export
  taken) — but that is a stated decision with compliance sign-off, not
  sampling by accident.
- Audit through the ORM inherits soft-delete and update paths you thought
  you removed; write via a dedicated append-only writer.
- "We'll backfill audit history later" is fiction; the coverage start date
  is what it is — document it.
- Correlation ids that never propagate to background jobs make job actions
  unattributable; the job context must carry actor + correlation from the
  triggering request.
- Tenant purge vs audit retention is a genuine legal tension — surface it;
  do not resolve it silently in either direction.

## Stop Conditions

- Compliance regime or contractual audit clauses unknown AND they would
  change taxonomy/retention → ask before designing to guesses.
- Post-purge audit retention (keep vs destroy) is a legal decision →
  `human-approval-boundary`; present both options with consequences.
- The system has no authorization design to hang events off → run
  `authorization-matrix-designer` first or in tandem; auditing undefined
  permissions records noise.
- Asked to implement the pipeline in the same pass → separate, scoped task;
  this skill delivers the design and test plan.

## Supporting Files

- [references/audit-event-taxonomy.md](references/audit-event-taxonomy.md) —
  starter taxonomy by category with must-record actions and grain guidance.
- `evals/evals.json` — trigger + behavior cases.
- `evals/trigger-evals.json` — discrimination against
  `authorization-matrix-designer` and `api-event-architect` (access & events
  cluster).