interface-review

Interface Review

Review public and shared boundaries from the caller's perspective. Determine whether the common call path is obvious, whether the boundary owns one coherent job, and whether callers can use it without learning implementation details.

Route Nearby Work

• Use adversarial-review for broad correctness, security, operational, or high-scrutiny review.
• Use simplify for internal complexity that does not affect callers.
• Use plan-changes when no implementation exists yet.

Select the Boundaries

Inspect changed:

• APIs, commands, events, schemas, and serialized messages;
• exported functions, classes, service methods, and libraries;
• hooks, shared components, callbacks, and extension points;
• configuration surfaces and feature switches;
• errors, return values, async behavior, and side effects visible to callers.

Trace actual callers and nearby existing boundaries. Do not evaluate an interface in isolation from how it is used.

Ask the Caller Questions

For each boundary:

1. What job is the caller trying to do?
2. Does the name describe that job and its side effects?
3. Are required inputs, defaults, modes, return values, errors, and lifecycle behavior explicit?
4. Does the caller need to know this provider, transport, storage, or framework detail?
5. Does an existing boundary already partly solve the same job?
6. Would a new caller know which of the overlapping entrypoints to choose?
7. Can the interface evolve without forcing unrelated callers to change?

High-Signal Problems

Prioritize:

• near-duplicate entrypoints for the same caller job;
• optional input whose omission silently selects a different workflow;
• boolean flags or mode strings that combine unrelated behavior;
• several primitives that travel together but represent one domain concept;
• a large options object that only relocates confusion;
• query-like names that hide writes, notifications, or network effects;
• provider, storage, transport, or framework leakage;
• nullable or ambiguous return values without a caller-visible reason;
• extensibility machinery with one implementation and no demonstrated second consumer;
• breaking changes without a deliberate migration or version boundary.