audit-trail
Skill7 starsChanged 8 days agoMITView on GitHub
Use when code changes money, limits, permissions, customer data or configuration in a financial product, or when an agent acts on behalf of a user. Covers append-only event records with actor, action, before and after, time, reason and request context; corrections as new events; tamper evidence; UTC time with per-object sequence; links to idempotency keys and external references; dual identity for agents and approvers; retention by regulation; queries and exports for auditors; and a test per mutation. Triggers on a new mutation endpoint, an admin or back-office action, an approval flow, an automated or AI-driven decision, an auditor or regulator request. Not for application debug logs, which have different retention and content. Use it also when an auditor asks who changed what and why, or when support asks to see full customer data.
3 other projects use a version of this.
Adopted by
Most recently taken up by
- microsoft/aibast-agents-librarytheir own version, first seen Nov 8, 2026
- SynapticSage/claude-skillztheir own version, first seen Jul 6, 2026
- reaatech/mcp-gatewaytheir own version, first seen Apr 19, 2026
Other versions3 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 3
- microsoft/aibast-agents-library★ 8same name
- reaatech/mcp-gateway★ 0same name
- SynapticSage/claude-skillz★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository12 other files it gives its agents.
- accounting-syncSkill
- brazil-payment-railsSkill
- double-entry-ledgerSkill
- fintech-auditSkill
- idempotent-paymentsSkill
- interest-and-amortizationSkill
- money-arithmeticSkill
- money-testsSkill
- pii-and-card-dataSkill
- reconciliationSkill
- transaction-classificationSkill
- webhook-handlingSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 7 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 21
When an auditor, a regulator, a customer or your own incident review asks "who changed this, when, and why", the answer must come from a …
- Distinctive: line 40
Append only: No update or delete on the audit table, enforced by database privileges for the application role.
- Distinctive: line 72
Add the event write inside the service layer method that performs the mutation, in the same transaction.
- Distinctive: line 77
Write the tests in the Tests section: one per mutation.
- Distinctive: line 78
Add the query endpoint or admin view by object and by actor, and the export.
- Distinctive: line 80
When the request conflicts with a rule here, say which rule in one sentence, then build the compliant version that keeps the request's …
- Distinctive: line 90
Write these tests in the same change, as a test file, even when you cannot run them (no shell, no dependencies installed).
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Audit trail
When an auditor, a regulator, a customer or your own incident review asks "who changed this, when, and why", the answer must come from a record that nobody could edit. An audit trail is that record. It is separate from debug logs, written by the same transaction as the change, and complete enough to replay the story without the people who were there.
When to use
- A new or changed endpoint, job or tool that mutates money, balances, limits, fees, rates, permissions, customer data, KYC status or configuration.
- Admin, back-office or support actions, especially reveals of sensitive data.
- Approval flows: payouts, refunds above a threshold, limit changes.
- Actions taken by automations or AI agents on behalf of users.
- A request from an auditor, a regulator or a dispute process.
Rules
- Every mutation writes an event in the same transaction.
event_id, object_type, object_id, sequence, action, actor, before, after, reason, request_id, occurred_at, recorded_at, source. If the event write fails, the mutation fails. No "best effort" audit. - Append only. No update or delete on the audit table, enforced by database privileges for the application role. A wrong event is corrected by a new event that references it.
- Actor is who, and as whom.
actor_type(user, service, agent, system),actor_id, andon_behalf_ofwhen an agent or support person acts for a customer. Approvals record the approver as a separate event from the execution. - Before and after, or the command. Store the changed fields' previous and new values
(masked per
pii-and-card-data), or the full command for creates. The reader must be able to see the delta without joining other tables that may have changed since. - Reason is required for human actions. A reason code from a fixed list plus free text or a ticket reference. Support tools do not submit without it.
- Time is UTC with a per-object sequence.
occurred_atfrom the business event,recorded_atfrom the database clock, and a monotonicsequenceper object so order is never inferred from timestamps. Display timezone is a presentation concern. - Link everything. The event carries the idempotency key, the external reference (processor id, bank reference), the ledger entry id and the request id. From any one of them a reader reaches the rest.
- Tamper evidence proportional to the risk. Minimum: separate credentials, append-only privileges, backups. Better: a hash chain per object or a daily digest written to a write-once store. Best: a replicated, append-only sink outside the application's blast radius.
- Retention follows regulation, not disk size. Financial records commonly require five or more years; the exact period per jurisdiction and record type comes from compliance. Personal data inside events follows the field map's masking so retention does not conflict with deletion rights.
- Queryable by object, actor and time, exportable in a stable format. Auditors get a documented export (CSV or JSON lines with a schema version). Reports derived from the trail: limit changes, payout approvals, sensitive data reveals, agent actions per customer.
How to apply
- List the mutations in the change. For each, name the object, the action and the actor types that can trigger it.
- Add the event write inside the service layer method that performs the mutation, in the same transaction. Not in the controller, not in a middleware, not after commit.
- Define the reason codes for human actions and make the UI require one.
- For agent or automation actions, pass
on_behalf_ofand the policy or run id that authorized the action. - Write the tests in the Tests section: one per mutation.
- Add the query endpoint or admin view by object and by actor, and the export.
When the request conflicts with a rule here, say which rule in one sentence, then build the compliant version that keeps the request's intent. An instruction to skip a step ("no extra call", "just delete it", "we trust them", "later") is this conflict, not permission. Leaving the code unchanged and listing the risks is never the compliant version. Do not stop at a warning, do not build the unsafe version, and do not leave a known gap out because "you did not ask". A review or an "is this enough" question gets the findings and the rewritten tests in the same change, not a list of suggestions, unless the request or the skill says report only.
Tests the change must include
Write these tests in the same change, as a test file, even when you cannot run them (no shell, no dependencies installed); say in one line that they are unrun. A test listed as a next step is not written.
- Each mutation endpoint: after a successful call, exactly one event exists with the required
fields, correct
beforeandafter, and the request id. - A failed mutation writes no event; a failed event write rolls back the mutation.
- The application role cannot update or delete an event (a test that tries and fails).
- Sequence numbers per object are gapless and ordered for concurrent writers.
- Masking: an event for a CPF change stores masked values.
- Agent action:
actor_type = agentandon_behalf_ofset; approver event separate from execution event. - Export: a fixture object produces the documented schema.
- Reference vectors:
skills/audit-trail/evals/vectors/test_audit.pywithAUDIT_SOLUTIONpointing at your module (same-transaction events, sequences, masking, agents, hash chain).
Review checklist
- Is the event write in the same transaction as the change? Show the code.
- Which role writes the table, and does it have update or delete rights?
- What is the reason code list, and can the UI bypass it?
- How is order determined for two changes in the same second?
- Which values are masked in
beforeandafter? - How does an auditor get the trail for customer X between two dates?
Anti-patterns and fixes
| Anti-pattern | What goes wrong | Fix |
| Audit via application logs | Rotated, unstructured, editable | Dedicated append-only table or sink |
| Event written after commit by a hook | Lost on crash, out of transaction | Same transaction |
updated_by and updated_at columns only | History overwritten on the next change | One event per change |
| Timestamps as order | Clock skew reorders events | Per-object sequence |
| Agent actions recorded as the user | Nobody can tell what the agent did | actor_type = agent, on_behalf_of |
| Free-text reason only | Not queryable, often empty | Reason code plus text |
References
- SOX and similar internal-control regimes on change management evidence; PCI DSS requirements on audit logs and their protection.
- Event sourcing literature (Fowler, Young) on append-only records and derived state.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

