kemiljk/skills/interaction-contracts

Interaction Contracts

Make the behaviour of a named interaction explicit enough that designers and engineers can build and verify the same experience. A contract describes observable promises; it does not require a state-machine library or a particular architecture.

Find the unresolved promise

Use the existing brief, interface, component API, and implementation to identify the person, task, starting state, and supported inputs. Preserve established behaviour unless the task calls for changing it. Distinguish a requirement from observed behaviour and a proposed change.

Cover the consequential uncertainty, not every possible event. An already specified local edit needs only the affected promise. Ask when a missing product decision would materially change the contract; otherwise state a reasonable assumption and proceed. A request for a specification authorises a specification; implementation requires an implementation request.

Describe the observable contract

Use a compact table, annotated flow, or the team's existing format. Include what matters for the interaction:

Separate cancelling an edit from cancelling a request and undoing a committed change. If cancellation cannot reverse a remote effect, do not promise that it does. Optimistic feedback needs an account of failure and reconciliation. Distinguish local acceptance from server confirmation or later processing when that difference matters to the task.

Inspect plausible overlapping actions: repeated submission, editing during a pending save, leaving and returning, or an older response arriving after a newer one. Include a sequence only when supported use can reach it. Resolve which result may update the UI without prescribing an unnecessary implementation mechanism.

Example: editing a project title

This is a hypothetical contract, not a product finding. Suppose the existing product uses explicit Save and Cancel:

Decide validation, navigation during saving, and focus return from product context. Do not infer that every editor should use this save model.

Carry the contract into the work

For design, represent the needed states and transitions and annotate requirements the medium cannot demonstrate. For code, map the contract to existing state ownership, controls, and service boundaries. Avoid replacing an architecture merely to make the specification look tidy.

Verify representative sequences against observable results. Use behavioural tests for consequential state or persistence changes; visual inspection alone cannot establish those promises. A mock service proves only the behaviour it simulates. Disclose unavailable checks and unresolved decisions.

When reporting a bug, identify the affected consumer and task, prerequisites and reproduction steps, expected and actual behaviour, and impact. Keep unexecuted concerns as hypotheses; do not report an imagined event sequence as a reproduced failure.

Deliver the requested contract, review, or scoped implementation, with the decisions made, acceptance checks performed, and remaining limits. This skill defines behaviour; it does not expand a local interaction into a whole-product hardening pass.