`carrick-drift` compares producer API types, consumer expected types, and stored contract verdicts side by side to diagnose cross-service type discrepancies.

## Invocation triggers

Agents execute `carrick-drift` in the following situations:

- When verifying whether a producer and consumer still agree on interface types
- Before modifying a request body, path parameter, or response payload shape
- When investigating a compatibility error that lacks specific source locations

## Tool sequence

1. **Discover service pairs**:
   - `get_service_graph()`: Retrieves all cross-service dependency edges.
2. **Inspect contract pairs**:
   - `get_contract_pair(consumer_service, producer_service, method?, path?)`: Retrieves side-by-side type definitions, call site locations, and stored verdicts for each operation between the services.

## Classification hierarchy

The skill classifies each operation by applying the following deterministic rules in priority order:

1. **`DRIFT`**: The stored verdict is `incompatible`. The finding details the mismatched property and direction.
2. **`PRODUCER UNTYPED`**: The producer lacks an extracted request type (on body-bearing methods) or response type.
3. **`CONSUMER UNTYPED`**: The consumer call site provides no type declaration for an operation that exposes types.
4. **`UNRESOLVED`**: The stored verdict is `unresolved` (due to dynamic or unextracted types).
5. **`NOT JUDGED`**: No stored verdict exists for the operation.
6. **`MATCH`**: The stored verdict is `compatible`.

On `UNRESOLVED` and `NOT JUDGED` rows, the skill performs a secondary structural inspection of the returned type texts, noting whether types are missing, have mismatched optionality, or declare different primitive types.

## Interpretation rules and edge cases

- **Verdict scope**: A stored verdict evaluates the contract between a consumer and producer service across that operation; all call sites on that operation share the verdict.
- **GET request bodies**: HTTP GET operations do not declare request bodies and are not marked as untyped.
- **Date and string serialization**: When JSON serialises `Date` objects to strings, Carrick notes the wire compatibility without flagging it as drift.

## Example

Evaluating an operation with `get_contract_pair`:

```json
{
  "consumer": "acme-gateway",
  "producer": "acme-orders",
  "operations": [
    {
      "operation": "POST /v1/orders {action=refund}",
      "producer": {
        "service": "acme-orders",
        "request": null,
        "response": null,
        "endpoint_source": "fact: declared operation"
      },
      "consumer": {
        "service": "acme-gateway",
        "call_sites": [
          {
            "file_location": "functions/gateway/src/api-client.ts:133",
            "expected_request": null,
            "expected_response": null,
            "call_source": "candidate: model"
          }
        ]
      },
      "untyped_sides": 4,
      "verdicts": [
        {
          "state": "unresolved",
          "scope": "pair",
          "scope_note": "One stored verdict covers the whole consumer/producer pair, not one call site: every call site listed on this operation shares it.",
          "scanner_version": "0.3.82",
          "response": {
            "verdict": "unverifiable",
            "resolved": false,
            "unresolved_reason": "the producer surface export is missing or renamed"
          }
        }
      ]
    }
  ],
  "types": []
}
```

The skill formats the result into a drift table:

| operation | class | producer type | consumer type | call site | verdict |
| :--- | :--- | :--- | :--- | :--- | :--- |
| POST /v1/orders {action=refund} | PRODUCER UNTYPED | none extracted | none extracted | functions/gateway/src/api-client.ts:133 | unresolved; the producer surface export is missing or renamed |

## Related

- [Task skills](/task-skills) covers the complete set of agent skills.
- [MCP tools](/mcp-tools) documents `get_service_graph`, `get_contract_pair`, and `check_compatibility`.
- [PR comments](/pr-output) describes automated drift checks on pull requests.