Cross Layer Contract Audit

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

1. Identify the user-requested contract or feature area.
2. Map callers and callees across layers.
3. 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.

1. Revalidate each suspected mismatch against source files.
2. 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mo-hawary
• Source: mo-hawary/hawary-workflow-skills
• License: MIT

Install and usage instructions live in the source repository linked above.