santosomar/general-secure-coding-agent-skills/ambiguity-detector

Ambiguity Detector

A requirement is ambiguous if two reasonable people can read it and disagree on what it says. Every ambiguity is a future bug, a future argument, or both.

Ambiguity taxonomy

The two-interpretations test

For each flagged phrase: can you write two concrete implementations that both satisfy the text but behave differently? If yes, it's ambiguous.

Requirement: "The search should return relevant results."

• Interpretation A: return everything matching the query, sorted by relevance score.
• Interpretation B: return only results above a relevance threshold (precision over recall).

Both "return relevant results." Different systems. Flag it.

Worked example

Requirement as written:

The API should handle concurrent requests efficiently. When the load is high, requests may be queued. Large payloads should be rejected with an appropriate error.

Scan:

Rewrite prompt (feed to → requirement-enhancer):

The API MUST handle at least {N} concurrent requests with p99 latency under {T} ms. When concurrent requests exceed {N}, additional requests MUST be queued (max queue depth {Q}; beyond that, respond 503). Payloads exceeding {S} bytes MUST be rejected with HTTP 413 and body {"error": "payload_too_large", "max_bytes": {S}}.

The {N}, {T}, {Q}, {S} are holes for the stakeholder to fill. The ambiguity detector's job is to surface the holes, not fill them.

Context-dependent false positives

Some "weak" words are fine in context:

Don't flag mechanically. Check if context resolves it.

Do not

• Do not rewrite the requirement yourself with invented numbers. "quickly → under 200ms" — where did 200 come from? Flag the hole; let the stakeholder fill it.
• Do not flag every "should." In RFC 2119 style, SHOULD is a deliberate weakening of MUST. Flag it only if the doc doesn't use RFC 2119 conventions and the intent is unclear.
• Do not miss structural ambiguity while hunting word-level ambiguity. "Validate X and Y or Z" — is that (X ∧ Y) ∨ Z or X ∧ (Y ∨ Z)? Parenthesization matters.
• Do not treat vague non-functional requirements as less important. "The system should be secure" is the most expensive kind of ambiguity.

Output format

## Requirement (verbatim)
<text>
 
## Ambiguities
| # | Phrase | Type | Interpretation A | Interpretation B | Resolution needed |
| - | ------ | ---- | ---------------- | ---------------- | ----------------- |
 
## Questions for stakeholder
1. <concrete question whose answer resolves ambiguity #N>
...
 
## Suggested restructure
<template with {HOLES} for the stakeholder to fill — not filled in>