# The Analyst Engineering Review Scorecard (v1.0)

Twelve checks for reviewing an API or event contract before a team integrates with it.
Score each check 0, 1, or 2. Maximum 24. Every point lost, and most points kept, becomes a finding.

Source and updates: https://www.analystengineering.com/scorecard
Practice on a real contract: https://www.analystengineering.com/labs/analyze-payment-api

## Scoring

- 0 = Absent. The topic is not addressed anywhere the consumer can find.
- 1 = Partial. Implied, scattered across pages, or stated without numbers ("may", "in some cases", "too many").
- 2 = Explicit. Stated once, with numbers or examples, and consistent across the contract.

Verdict: 20 to 24 integrate; 14 to 19 integrate after the high findings are answered in writing; 0 to 13 do not start.

## Contract under review

- Provider and contract:
- Version or date of the documentation reviewed:
- Reviewed by, on:
- Sources read (reference, guides, changelog, error list):

## Lens 1: Meaning

- [ ] **C1 Vocabulary** (score: __ /2). Does every resource, field, and enum map to exactly one business term?
  A 2 looks like: one name per concept across the whole contract, no synonyms, no database or legacy names beside the current ones, every enum value explained.
- [ ] **C2 Lifecycle** (score: __ /2). Are every state and every legal transition written down, with the trigger and the terminal states?
  A 2 looks like: a complete state list, each transition with its cause, terminal states named, every automatic transition quantified (after how many attempts, after how long).
- [ ] **C3 Money and time** (score: __ /2). Do amounts carry an explicit unit and currency, and timestamps an explicit zone and precision, the same way everywhere?
  A 2 looks like: integers in minor units or decimal strings with a currency, never floats; timestamps with a declared epoch or zone and precision; the same rule on every endpoint and event.

## Lens 2: Completeness

- [ ] **C4 Operations** (score: __ /2). Is there an operation for every process step, including cancel, correct, and retry?
  A 2 looks like: every process step has an operation, reversal and correction paths exist, and their constraints (once only, partial allowed, window) are stated.
- [ ] **C5 Errors** (score: __ /2). Does every failure the consumer must handle have a stable code, a status, and a recovery action?
  A 2 looks like: one error shape, a published code list, the HTTP status per code, which messages are safe to show a user, what to do next per class.
- [ ] **C6 Limits** (score: __ /2). Are lengths, sizes, minimums, maximums, rate limits, and retention windows stated as numbers?
  A 2 looks like: every limit is a number with a unit, including field lengths, amount bounds, request rates, per-object rates, and how long keys, holds, and events are kept.

## Lens 3: Safety

- [ ] **C7 Idempotency** (score: __ /2). Do creates and money-moving actions define a key, its scope, its retention, and what happens on mismatch?
  A 2 looks like: the header or field, its maximum length, how long the server remembers it, whether failures are replayed, what a reused key with different parameters returns, which operations honour it.
- [ ] **C8 Concurrency and ordering** (score: __ /2). Is the behaviour under concurrent writers stated, and are event ordering and duplication stated?
  A 2 looks like: locking or conflict behaviour on the same object, whether events arrive out of order or more than once, what to deduplicate on, exactly when duplicates are produced.
- [ ] **C9 Authorization and secrets** (score: __ /2). Is it explicit which credential can do what, and which values must never be logged or exposed?
  A 2 looks like: credential types and scopes per operation, signature or token verification rules with tolerances, secret rotation, a named list of values to keep out of logs and front ends.

## Lens 4: Evolution

- [ ] **C10 Versioning** (score: __ /2). Are the version mechanism, the definition of a breaking change, and the deprecation policy written down?
  A 2 looks like: how a version is selected per request and per event, what the provider promises not to break, how often versions ship, how long old ones live.
- [ ] **C11 Traceability** (score: __ /2). Does every object and event carry a stable identifier and a handle the consumer can correlate and reconcile with?
  A 2 looks like: stable ids on every object and event, a request identifier per call, a place for the consumer's own reference, a stated way to find an object from that reference.
- [ ] **C12 Evidence** (score: __ /2). Do examples, a sandbox, and test fixtures exist for the paths that matter, including failures?
  A 2 looks like: realistic examples per request and response, a sandbox whose differences from production are documented, a way to trigger every failure and event type on demand.

## Total: __ /24. Verdict: ______________________

## Findings register

Severity, from the consumer's seat: High (money or data goes wrong), Medium (an incident or rework), Low (a question to close before build), Note (context).

| Id | Check | Location | Finding | Evidence | Severity | Impact | Decision or question |
|----|-------|----------|---------|----------|----------|--------|----------------------|
| F1 |       |          |         |          |          |        |                      |
| F2 |       |          |         |          |          |        |                      |
| F3 |       |          |         |          |          |        |                      |

A CSV version of this register: https://www.analystengineering.com/downloads/findings-register-template.csv

Analyst Engineering, https://www.analystengineering.com. Free to use and share with attribution.