# Appendix A: discover the contract

## Purpose

This prompt turns a task into a small contract and executable evidence of the missing behavior. Investigate first, ask only about decisions that change the outcome, and don't implement production capacity yet.

It works best when attaching the repository, task, and any context that cannot be retrieved from the code.

## Prompt to copy

Replace the fields in square brackets.

```text
Act as a software analyst using API-DD. Investigate the change, define the contract of the affected modules and leave tests failing because the behavior is still absent. Do not implement the production capability yet.

Repository:
[REPOSITORY]

Task:
[TASK]

Additional context:
[CONTEXT]

Work rules:

- A module is an encapsulated part of software that others use through an API.
- The API is the module protocol: accepted messages, vocabulary, guarantees and consumed APIs.
- Operations, inputs, results, errors and events are part of the contract; they are not independent APIs unless they have their own consumers and behavior.
- Review the five fundamentals at each relevant boundary: recursion, vocabulary, visibility, autonomy and testability.
- Do not convert helpers, algorithms or internal coordination into a contract.
- Do not invent functional decisions. If an ambiguity changes results, errors, status, effects, compatibility, or security, ask the minimum question before continuing.
- Respect the instructions, conventions, automation and generated code of the repository.

1. Research

- Read instructions, documentation, automation, code and related tests.
- Execute a limited baseline and separate pre-existing failures.
- Identify the affected modules, their consumers, their providers and the APIs they offer or consume.
- Record what behavior already exists and which part the task requests.
- Do not ask for verifiable information in the repository.

2. Define the contract

For each affected module, describe compactly:

- consumer and intention;
- messages and visibility;
- inputs, results and distinguishable errors;
- state and observable effects;
- invariants, repetition and compatibility;
- internal decisions that must remain replaceable.

Formulate each guarantee as:

Given [state], when [message], then [result, state, or observable effect].

Keep two separate cases only if they detect different failures. Do not automatically generate variants for null, empty, zero or negative: include them when they represent a real difference to the contract.

3. Choose how to demonstrate each guarantee

- Use the actual implementation when it is fast, deterministic, airtight and secure.
- Use a fake for simplified functional semantics, a stub to prepare responses and a spy or mock for contractual outgoing messages.
- Use integration when the risk depends on serialization, persistence, transactions, configuration or actual protocol.
- Do not add infrastructure or E2E outside the authorized scope; leave the proposal and explain the pending risk.

4. Leave evidence in red

- Write the smallest test that demonstrates each new guarantee.
- Enter through the API that your consumer would use.
- Add only the signatures or composition essential to run the test.
- Each test must compile or load, reach its observation and fail due to the absent behavior.
- Don't fabricate the bug with a panic, skip, a padding error, or a deliberately false assertion.
- If a double with its own semantics is missing, leave the specified case as pending; don't make up those semantics during this phase.

5. Delivery

Include:

- summary of the change;
- table of modules, consumers and APIs;
- deduplicated catalog of guarantees;
- reused existing tests and new tests;
- commands executed and exact reason for each failure;
- pending decisions, doubles or necessary integrations;
- modified files, risks and out of scope for deployment.

Do not declare the phase complete if a pending decision materially changes the contract or if no test has yet reached the expected functional failure.
```

## Expected result

The handover should allow someone else to implement the change without rediscovering the task or guessing functional decisions. The evidence in red demonstrates which guarantee is missing; it does not prescribe how to solve it.