data-contract-auditor

What this is for

The schema says VARCHAR(255) NOT NULL but the API returns null, the form submits a number where a string is expected. These silent contract violations cause production surprises that no single tool catches - because the schema lives in one file and the usage lives in another, and no linter connects them.

This skill extracts schema declarations (DDL, ORM models, TypeScript interfaces, GraphQL types, OpenAPI schemas) and usage sites (API response serialization, form/data parsing, import/export handlers, ORM write calls), then lets the LLM judge each discrepancy: real violation, harmless flexibility, or schema too strict?

Audience: Both - seniors use it as pre-deployment safety net and API contract review; juniors learn where their code silently drifts from declared contracts.

PROTECTION RULE - never ~/.claude/

Read-only skill. Guard required if write mode added later.

## What You Must Do When Invoked

Step 1

1. If -help or -h is passed, print the ## Usage block below and stop.

Step 2

2. Confirm -ProjectDir is provided and the path exists. If not, print usage and stop.

Step 3

3. Run the collector script:

Step 4

scripts/contract-scan.ps1 -ProjectDir "<path>"

Step 5

4. LLM reads the JSON output. Per contract element (contracts[]):

Step 6

• Examine field, declaredType, declaredNullable.

Step 7

• Examine each usageSites[] entry: file, line, usageType, usedType, usedNullable.

Step 8

5. Per discrepancy:

Step 9

• Is this a real violation? (e.g. NOT NULL field is assigned undefined - will produce null in JSON, may crash strict consumers.)

Step 10

• Is this harmless flexibility? (e.g. parseInt correctly coerces string to number - the consumer handles both.)

Step 11

• Is the schema too strict? (e.g. field declared number but real-world API returns numeric string - schema should be string | number.)

Step 12

• Classify: real-violation / harmless-flexibility / schema-too-strict.

Step 13

• Add confidence: proven / likely / suspected.

Step 14

6. Write data-contract-report.md to the working directory with:

Step 15

• Executive summary (files scanned, contracts found, discrepancies)

Step 16

• Per-field breakdown (field, declared contract, usage sites, verdict, confidence, reasoning)

Step 17

• Cross-cutting patterns (which type of violation is most common)

Step 18

• Recommendations (schema changes, runtime guards, or accept-as-is)

Step 19

• Open questions (suspected-confidence findings needing human review)

Usage

/data-contract                          # interactive, prompts for directory
/data-contract <dir>                    # scan schema + usage in directory
/data-contract -help                    # show usage

Returns JSON with contracts[]: each entry {field, declaredType, declaredNullable, usageSites[{file, line, usageType, usedType, usedNullable}]} plus summary counts: {filesScanned, schemasFound, fieldsFound, usageSitesFound, discrepanciesFound}.

Report Format

data-contract-report.md with:

• Executive summary (files scanned, contracts found, discrepancies by severity)
• Per-field breakdown (field, declared contract, usage sites, verdict, confidence, human-readable reasoning)
• Cross-cutting patterns (most common contract break type)
• Recommendations (schema changes, runtime guards, documentation updates)
• Open questions (findings needing human review)

Collector Output Schema

{
  "contracts": [
    {
      "field": "email",
      "declaredType": "string",
      "declaredNullable": false,
      "usageSites": [
        {
          "file": "handler.ts",
          "line": 10,
          "usageType": "response-return",
          "usedType": "string | undefined",
          "usedNullable": true
        }
      ]
    }
  ],
  "summary": {
    "filesScanned": 2,
    "schemasFound": 1,
    "fieldsFound": 5,
    "usageSitesFound": 8,
    "discrepanciesFound": 2
  }
}