API Contract Sentinel

API Contract Sentinel

Version: 1.2.2| Maturity: stable

Use this skill to perform a contract-first audit of API implementations.

Treat the contract as the source of truth unless the user explicitly says the implementation is authoritative. Prefer exactness over generosity, but separate confirmed violations from unresolved ambiguity.

Outcomes

Produce an evidence-backed audit that helps the user answer:

• Does the implementation match the contract?
• Which mismatches are definitely real?
• Which gaps are caused by an incomplete or ambiguous contract?
• What should be fixed in code, in the contract, or in both?

Required Inputs

Gather enough material to compare intent with implementation:

• One authoritative contract source. Examples: openapi.yaml, openapi.json, AsyncAPI, protobuf, JSON Schema bundle, or a technical PRD that defines API behavior.
• One implementation surface. Examples: controllers, routes, handlers, DTOs, serializers, validators, generated server stubs, generated client code, or integration tests that document runtime behavior.

If either side is missing, say so clearly and scope the audit to what is available.

Source Hierarchy

When multiple sources disagree, rank them explicitly before auditing:

1. Formal machine-readable contract approved by the team
2. Versioned technical spec or API PRD
3. Generated code derived from the contract
4. Handwritten implementation details
5. Tests, examples, and comments

Do not silently merge conflicting sources. Call out the conflict and say which source you treated as authoritative.

Audit Workflow

1. Establish the audit boundary

Identify:

• the contract version or file used
• the implementation files or generated artifacts inspected
• the routes, operations, message types, or schemas in scope
• whether the task is read-only audit, remediation planning, or both

If the user did not define scope, infer the narrowest reasonable scope from the provided files and state that assumption.

2. Normalize the contract

Extract the comparison surface into a compact checklist:

• operation or message name
• method and path
• path, query, header, and cookie parameters
• request body shape and required fields
• response status codes
• response body shape
• auth and required headers
• content types
• enums, formats, nullability, defaults, pagination, and error model rules when specified

When auditing from a prose PRD instead of a formal contract, convert the prose into explicit expected behavior before comparing implementation. Mark this as an inferred contract, not a guaranteed one.

3. Map the implementation

Inspect the real execution surface rather than relying on naming alone:

• route declarations
• controller or handler signatures
• request parsing and validation
• serialization and response shaping
• status-code selection
• auth middleware or policy annotations
• generated model types
• error handling paths

If the implementation is generated, still verify post-generation edits, wrappers, and adapters around the generated code.

4. Compare contract to implementation

Check at minimum:

• operation presence: missing, extra, or renamed endpoints
• method and path correctness
• parameter names, location, requiredness, and type
• request body required fields, optional fields, nullability, and formats
• response status codes and payload shape
• auth, headers, and content negotiation
• error responses that the contract requires but implementation omits

Prefer precise statements like Spec requires 201; handler returns 200 over broad claims like status codes differ.

5. Classify findings

Use these severities:

• critical: contract break that will likely cause runtime failure, client breakage, or security/compliance issues
• high: behaviorally incorrect implementation with real integration risk
• medium: partial mismatch, missing documented behavior, or drift that may not fail immediately
• low: naming, documentation, or consistency issue with limited immediate runtime risk

Also label each finding as one of:

• implementation bug
• contract bug
• contract ambiguity
• needs confirmation

If evidence is insufficient, do not overstate. Downgrade confidence and explain the blocker.

6. Recommend the right fix target

For each finding, say whether the best next step is:

• fix implementation
• fix contract
• align both in the same change
• confirm intended behavior before changing either

Do not rewrite files unless the user explicitly asks for remediation after the audit.

Response Contract

Return the audit in this structure:

Audit Summary

• Verdict: pass, pass-with-ambiguities, or fail
• Authority: contract file or source used
• Implementation Scope: files, modules, or generated artifacts inspected
• Coverage: what was checked and what was not

Findings

Provide one row or bullet per finding with:

• severity
• classification
• contract reference
• implementation reference
• mismatch description
• integration risk
• recommended next step

Assumptions And Ambiguities

List anything that reduced certainty:

• incomplete contract sections
• implementation files not available
• generated code without the templates that produced it
• ambiguous PRD language
• version mismatch between contract and code

Optional Remediation Sketch

When useful, provide a minimal patch sketch or pseudocode for the highest-severity finding. Keep it short and illustrative.

Evidence Rules

• Cite concrete paths, schema names, operation IDs, or line references when available.
• Quote or paraphrase only the minimum needed to prove the mismatch.
• Distinguish observed behavior from inferred behavior.
• Do not claim a mismatch if you only saw naming drift with no behavioral evidence.

Guardrails

• Do not treat generated code as automatically correct just because it compiles.
• Do not assume undocumented runtime behavior is contract-compliant.
• Do not silently accept additive response fields when the contract is strict and clients may validate schemas.
• Do not collapse all issues into a single vague "schema mismatch" bucket; enumerate them.
• Do not convert ambiguity into certainty. Say needs confirmation when evidence is incomplete.

Memory Model

Use runtime memory by default for the current audit.

If the user wants persistent project-local tracking, store durable findings in a project artifact such as contract-audit-report.md or contract-drift-log.md. Keep that memory local to the project or repository.

Do not create or depend on shared cross-agent memory inside this skill. If the user needs organization-wide contract drift tracking, integrate with a separate shared-memory or governance system instead of embedding that infrastructure here.

Bundled References

Load these only when they help:

• references/audit-rubric.md: detailed comparison checklist and severity guidance
• references/response-template.md: reusable report template
• examples/README.md: example inputs and outputs for this skill

Success Criteria

The skill has succeeded when the user can tell:

• what contract source was trusted
• exactly where the implementation diverges
• how confident each finding is
• whether the next fix belongs in code, the spec, or both