Engineering guide

Resolve ambiguous requirements before choosing behavior

A requirement is ambiguous when reasonable readers can implement different behavior and still claim to follow it. The useful outcome of review is a resolved decision, not merely cleaner wording.

Find the decision hidden in the sentence

Consider “the client should retry failed requests promptly.” It leaves several product decisions open: which failures qualify, how many attempts are allowed, whether a deadline limits retries, and whether a retry can repeat a side effect. Replacing “promptly” with “quickly” changes none of those decisions.

Illustrative review. For a read-only request, the proposed contract is: retry connection failures at most twice, stop at the original request deadline, and return the last error if no attempt succeeds. This is candidate intent to approve, not a fact inferred from whatever the current client happens to do.

Resolve the uncertainty with its owner

Collect the conflicting interpretations and their consequences. A caller may rely on a bounded response time while an operator values eventual success. The accepted rule needs to reconcile those needs, identify the operating assumptions, and preserve the reason for the decision.

An agent can gather evidence and propose wording. Authority to resolve the product decision comes from the project's approval and delegation policy. A test generated from one interpretation does not make that interpretation authoritative.

Turn the decision into reviewable cases

Case	Expected observation under the proposed rule
First attempt succeeds	Return its result; no retry.
Connection fails twice, then succeeds	At most three total attempts, within the deadline.
Deadline expires during retry handling	Stop without starting a late attempt.
Request has a non-repeatable side effect	Use a separately approved retry contract.

The last row deliberately preserves a boundary. Do not extend a rule for read-only requests to payments without resolving idempotency and failure semantics.

Use automated findings as review prompts

proof gaps specs/system --check ambiguity
proof audit --check ambiguity_reviewed --verbose

Replace the spec path with one configured in the project. The ambiguity analysis and review check can expose recorded uncertainty and missing review disposition. They do not establish that all possible interpretations have been eliminated.

After the decision, update affected prose, formalization, acceptance criteria, and tests together. If the accepted meaning changes, record that as an intent change and reassess existing evidence. A clearer sentence that changes the promise is more than an editorial correction.

Continue from here

Validate the proposed promise. Review prose/formalization drift.

Bring one requirement for which two reasonable implementations would behave differently. Bring a change to Proof.