Cross-Layer Contract Audit
Find mismatches between layers. Code and schema evidence outrank documentation.
When To Use
Use this for cross-layer behavior where two or more implementation layers must agree.
Do not use this for a general repo status snapshot; use project-status-dashboard. Do not use it for planning a new feature from scratch; use feature-spec-delivery-pipeline.
Scope
Adapt the layer map to the repo. Common layers include:
- Client models, forms, screens, state, and generated API clients.
- API routes, handlers, serializers, validators, and service methods.
- Database schema, migrations, views, policies, triggers, and seed data.
- Background jobs, queues, webhooks, and third-party integration contracts.
- Documentation and specs as supporting context only.
Input Signals
Start from concrete signals such as changed files, failing tests, route names, migration names, API schemas, generated clients, UI forms, webhook payloads, or user-reported mismatches. If the user gives only a broad area, map the smallest boundary that can be verified end to end.
Workflow
- Identify the user-requested contract or feature area.
- Map callers and callees across layers.
- Compare:
- Field names, types, nullability, defaults, enums, and units.
- Required vs optional values.
- Error formats and status codes.
- Auth, permissions, tenancy, and ownership checks.
- State transitions and side effects.
- Revalidate each suspected mismatch against source files.
- Produce a severity-ranked report.
For sample prompts and report shape, see references/examples.md.
For a compact field-by-field audit checklist, see references/contract-checklist.md.
Output
For each finding:
- Severity: blocker, high, medium, low.
- Contract: the layer boundary that is inconsistent.
- Evidence: file paths, symbols, routes, migrations, or schema names.
- Impact: likely user or data effect.
- Fix Direction: smallest safe repair, noting which layer should change.
- Verification: targeted tests or commands that would prove the fix.
Guardrails
- Do not trust docs as truth when implementation differs.
- Do not fix during the audit unless the user explicitly approves implementation changes.
- Flag unclear product behavior as an open question rather than deciding it.
- Treat auth, payments, sessions, data migration, and destructive changes as high-risk.
Avoid
- Do not report a mismatch without naming both sides of the boundary.
- Do not collapse product uncertainty into an implementation recommendation.
- Do not broaden the audit into unrelated refactors.
Final Checks
- Every finding has source-backed evidence.
- Each impact explains the likely user, data, or operational effect.
- Each fix direction names the layer that should change.
- Unknown product behavior is listed as an open question, not resolved by assumption.
1---2name: cross-layer-contract-audit3description: Audit client, API, database, and docs for contract mismatches. Use for schema drift, auth/session/payment changes, migrations, or integration regressions.4---5
6# Cross-Layer Contract Audit
7
8Find mismatches between layers. Code and schema evidence outrank documentation.
9
10## When To Use
11
12Use this for cross-layer behavior where two or more implementation layers must agree.
13
14Do not use this for a general repo status snapshot; use `project-status-dashboard`. Do not use it for planning a new feature from scratch; use `feature-spec-delivery-pipeline`.
15
16## Scope
17
18Adapt the layer map to the repo. Common layers include:
19
20- Client models, forms, screens, state, and generated API clients.
21- API routes, handlers, serializers, validators, and service methods.
22- Database schema, migrations, views, policies, triggers, and seed data.
23- Background jobs, queues, webhooks, and third-party integration contracts.
24- Documentation and specs as supporting context only.
25
26## Input Signals
27
28Start from concrete signals such as changed files, failing tests, route names, migration names, API schemas, generated clients, UI forms, webhook payloads, or user-reported mismatches. If the user gives only a broad area, map the smallest boundary that can be verified end to end.
29
30## Workflow
31
321. Identify the user-requested contract or feature area.
332. Map callers and callees across layers.
343. Compare:
35 - Field names, types, nullability, defaults, enums, and units.
36 - Required vs optional values.
37 - Error formats and status codes.
38 - Auth, permissions, tenancy, and ownership checks.
39 - State transitions and side effects.
404. Revalidate each suspected mismatch against source files.
415. Produce a severity-ranked report.
42
43For sample prompts and report shape, see `references/examples.md`.
44For a compact field-by-field audit checklist, see `references/contract-checklist.md`.
45
46## Output
47
48For each finding:
49
50- **Severity:** blocker, high, medium, low.
51- **Contract:** the layer boundary that is inconsistent.
52- **Evidence:** file paths, symbols, routes, migrations, or schema names.
53- **Impact:** likely user or data effect.
54- **Fix Direction:** smallest safe repair, noting which layer should change.
55- **Verification:** targeted tests or commands that would prove the fix.
56
57## Guardrails
58
59- Do not trust docs as truth when implementation differs.
60- Do not fix during the audit unless the user explicitly approves implementation changes.
61- Flag unclear product behavior as an open question rather than deciding it.
62- Treat auth, payments, sessions, data migration, and destructive changes as high-risk.
63
64## Avoid
65
66- Do not report a mismatch without naming both sides of the boundary.
67- Do not collapse product uncertainty into an implementation recommendation.
68- Do not broaden the audit into unrelated refactors.
69
70## Final Checks
71
72- Every finding has source-backed evidence.
73- Each impact explains the likely user, data, or operational effect.
74- Each fix direction names the layer that should change.
75- Unknown product behavior is listed as an open question, not resolved by assumption.
aibot88