Lint Requirements for Ambiguity and Rewrite Them in EARS Form

Workflow area: Requirements Quality · Tier: Core · Hands-on time: ~30 minutes

Ambiguity is the cheapest defect to fix at draft time and the most expensive to fix in UAT, when "fast" turns out to mean 200 milliseconds to the sponsor and two seconds to the vendor. Human reviewers are bad at catching it because the brain autocompletes vagueness with its own assumptions — everyone reads "the data shall be archived" and silently supplies a different actor and a different retention period. Models are excellent pattern-matchers for exactly these constructions, and EARS (Easy Approach to Requirements Syntax) gives the rewrite a target shape: a trigger, a named system, a "shall," and a measurable response. The discipline that keeps this honest: the lint proposes, the rewrite is reviewed clause by clause, and any number the model had to invent to make a requirement testable is a placeholder to elicit — never a fact.

When to use — and when not to

• Use it on every requirements set before review circulationlinting your own draft before others see it converts review meetings from wordsmithing to substance.
• Use it on inherited or vendor-authored requirementsa lint pass over a vendor's spec is the fastest way to enumerate what has quietly been left undefined, and each flag is a clarification question.
• Use it before test designuntestable requirements surface here or in UAT; here is cheaper by two orders of magnitude.
• Skip the blind auto-acceptbatch-applying rewrites without review swaps your ambiguity for the model's guesses. The invented threshold inside a fluent EARS sentence is the failure mode this playbook exists to catch.
• Skip full EARS for lightweight artifactsuser stories keep their story shape; lint the acceptance criteria instead. Forcing EARS onto everything is syntax worship.
• Skip it when the ambiguity is politicalsometimes "appropriate approval" is vague because stakeholders have not agreed. The lint finds it; only a decision meeting fixes it. Rewriting it precisely without agreement just moves the fight to sign-off.

The recipe

1. 1.

   Stage the requirements with IDs. Export the set with stable identifiers (BR-001...) — flags must be traceable back. Include the glossary if you have one, so the lint distinguishes your defined terms from genuine vagueness.

2. 2.

   Run the lint-then-rewrite. Paste into Claude or ChatGPT with this prompt:

   Copy

   You are a requirements-quality linter. Lint first, rewrite second.
   Glossary of defined terms (do not flag these): [PASTE OR "none"]
   
   PASS 1 — LINT. For each requirement, flag every instance of:
   - vague quantifiers ("fast", "user-friendly", "minimal",
     "appropriate", "as needed", "etc.")
   - passive voice hiding the actor ("data shall be archived" — by
     whom/what?)
   - compound requirements (two shalls, "and/or", hidden second
     requirement)
   - unbounded terms ("all", "any", "always" without scope)
   - untestable claims (no observable pass/fail)
   Output: ID | flagged text | defect type | why it is a defect.
   Flag nothing that is precise. If a requirement is clean, say so.
   
   PASS 2 — REWRITE. For each flagged requirement, rewrite into EARS:
   - Ubiquitous: The <system> shall <response>.
   - Event: WHEN <trigger>, the <system> shall <response>.
   - State: WHILE <state>, the <system> shall <response>.
   - Unwanted: IF <condition>, THEN the <system> shall <response>.
   Split compounds into numbered atomic requirements.
   CRITICAL: where a rewrite needs a number, threshold or actor the
   original does not supply, insert [TBD: what to elicit and from
   whom] — NEVER invent a value.
   
   Requirements:
   [PASTE]
   

3. 3.

   Review flags and rewrites separately. Good output looks like this:

   Copy

   BR-012 | "Invoices should be processed quickly during month-end"
   | vague quantifier + untestable | "quickly" has no measure; no
   pass/fail is observable.
   
   Rewrite:
   BR-012a WHILE the month-end close window is open, the invoicing
   service shall complete invoice validation within [TBD: target
   seconds — elicit from finance ops lead].
   BR-012b WHEN validation exceeds the BR-012a target, the system
   shall queue the invoice and notify [TBD: role — finance ops?].
   

   Adjudicate every flag: accept, reject with a reason (some "vague" terms are defined elsewhere), or escalate (the politically vague ones). Check every rewrite for meaning drift — an EARS sentence that says something subtly different from the stakeholder's intent is a new defect wearing a suit.

4. 4.

   Chase the [TBD]s — they are the real findings. Each placeholder is a specific elicitation question with a named target. Batch them by stakeholder and clear them in one round of short calls. A [TBD] that survives into baseline must be logged as an explicit open item with an owner and date, not left as decoration.

5. 5.

   Update, log, and re-lint. Apply accepted rewrites under version control, record rejected flags with reasons (your audit trail that the lint ran and was judged), and run one final lint pass — clean output or adjudicated flags only — before the set goes to review or baseline.

Make it yours

• Team lint standard: freeze the defect taxonomy and prompt for the whole analyst team, so "linted" means the same thing on every project and review meetings start from a shared floor.
• QVscribe-class tools at volume: dedicated requirements-QA tools score at scale and integrate with DOORS/Jira pipelines; keep the LLM for the rewrite step, where tools are weakest and the EARS transformation shines.
• Story-mode variant: for agile backlogs, lint acceptance criteria against the same taxonomy but rewrite into Given/When/Then instead of EARS — same defects, native shape (pair with pb-05).
• Lint-on-intake gate: run the pass on every vendor spec and inherited document the day it arrives; the flag list becomes your first clarification agenda with the counterparty.

Quality check

• Every flag was adjudicated by a humanaccepted, rejected with a reason, or escalated; no rewrite was batch-applied unread.
• No invented valuessearch rewrites for numbers and actors absent from the originals; every one is either sourced or a [TBD]. An unmarked invented threshold is the pass's cardinal failure.
• Meaning survived the rewritesampled rewrites were compared against the original stakeholder intent (and its citation, if the set came from an evidence pack); precision did not change the promise.
• Compounds are atomic and renumberedsplit requirements got IDs, and traceability links were updated to point at the children.
• [TBD]s are ownedevery placeholder has a named elicitation target, and none survived to baseline without an explicit open-item log entry.
• Political vagueness went to a decision forumflags reflecting unresolved stakeholder conflict were escalated, not silently "fixed" by wording.