💡 IN THIS EDITION (PART 2 OF 2 IN OUR SDLC SERIES):
The Series Bridge: In Part 1, we covered how repo-level context breaks at scale. In Part 2, we move upstream: how to eliminate requirement ambiguity in Jira tickets using EARS syntax before a single line of code is written.
The Signal: Why unstructured prompt engineering breaks down as enterprise codebases expand.
Why It Matters: The hidden financial and lead-time cost of ambiguous tickets and re-explanation taxes.
The Architecture: Shifting ambiguity resolution upstream using EARS syntax and living context boundaries.
Reusable Artifact: The Enterprise EARS Requirements & Ticket Refinement Schema.
1. The Signal
In Part 1 of this series, we examined how un-governed repository context drives token bloat, architectural drift, and code review fatigue. But fixing repository context only solves half the equation.
If an AI coding assistant receives an ambiguous ticket, no amount of repository context will stop it from implementing the wrong business logic.
As engineering organizations attempt to scale AI coding tools across teams, many encounter an unexpected plateau. Initial productivity spikes during greenfield prototypes, but velocity slows as work shifts to complex, enterprise codebases. Senior engineers find themselves spending more time reviewing hallucinated edge cases, untangling bad assumptions, and debugging integration errors than they saved by generating syntax.
In response, the industry has rushed toward Spec-Driven Development (SDD)—writing detailed Markdown documents upfront to guide AI agents. But un-governed SDD often creates its own failure mode:
Documentation Bloat: In open-source SDD benchmarks, adding a simple date display to a UI generated 8 separate Markdown files and 1,300 lines of prose.
The "README Trap": Static Markdown specs rot quickly. When specs depend on human memory to stay updated, they become documentation debt.
The Re-Explanation Tax: Freeform instruction files are frequently treated as loose suggestions by models, leading to 15–20 minutes of re-explanation overhead per session restart.
Writing pages of conversational text is the wrong abstraction. The path forward isn't more documentation—it is upstream requirements refinement paired with machine-readable context boundaries.
2. Why It Matters
When an AI coding assistant receives an ambiguous ticket, it does not stop to ask questions; it fills knowledge gaps using general training weights.
If a Jira ticket reads "Update CTA link" or "Improve matching logic," the assistant will build an implementation instantly—and it will often be wrong.
| The Downstream Ambiguity Compound Tax | |
|---|---|
| Ambiguity Failure Mode | Operational & Financial Impact |
| 1. Ambiguous Ticket Intake | AI guesses business logic, causing subtle architectural drift across services. |
| 2. Unbounded Context Ingestion | Search indexers ingest stale notes, inflating token costs by 20%+. |
| 3. Double Code Review Overhead | Engineers review generated specs AND buggy code, doubling review fatigue. |
| 4. Test Readiness Divergence | Code-ready work gets blocked by missing QA stage data or S3 fixtures late in cycle. |
The highest-leverage opportunity in AI-native engineering is moving ambiguity resolution earlier in the delivery lifecycle. Resolving uncertainty at the requirement stage is exponentially cheaper than unwinding buggy pull requests.
3. The Architecture / Operating Model
To make Spec-Driven Development practical without creating Waterfall bureaucracy, enterprise platforms deploy an Upstream Requirements Refinement Engine anchored by EARS syntax (Easy Approach to Requirements Syntax).
| Upstream Requirements Refinement & Living Context Architecture | ||
|---|---|---|
| Pipeline Stage | Operational Mechanism | System Output / Contract |
| 1. Ticket Intake | Ingests raw, unstructured Jira stories or user requests directly from the system of record. | Rough User Story |
| 2. Refiner Skill | Evaluates ticket against repository context (AGENTS.md, existing schemas, test suites) to uncover hidden gaps. | Repo-Grounded Audit |
| 3. EARS Spec & Schemas | Converts ambiguous text into standardized EARS clauses (Ubiquitous, Event, State, Unwanted Behavior) and rigid JSON/Zod schemas. | AI-Ready Contract |
| 4. CI/CD Pre-Flight | Runs deterministic linters, compilers, and test suites prior to LLM evaluation, verifying spec and code alignment before PR merge. | Deterministic Merge Gate |
Key Architectural Invariants:
Shift Resolution Upstream: Before a developer writes code, an interactive skill or automated agent evaluates the ticket against repository context (
AGENTS.md, existing schemas, test suites).Standardize on EARS Syntax: Replace conversational prose with rigid EARS patterns that eliminate ambiguity:
Ubiquitous: The
[system]shall[action].Event-Driven: WHEN
[trigger], the[system]shall[action].State-Driven: WHILE
[state], the[system]shall[action].Optional Feature: WHERE
[feature], the[system]shall[action].Unwanted Behavior: IF
[condition], THEN the[system]shall[action].
Keep Context Conditional: Do not dump entire codebases into prompts. Load Figma UI context or Snowflake/Atlan data schemas only when ticket signals explicitly require them.
Decouple Artifact Lifecycles:
Transient Task Specs (Ephemeral): Ticket-level plans used during local iteration, purged from
mainupon PR merge to prevent search indexer bloat.Living Domain Specs (Persistent): Core business contracts stored in
docs/specs/[domain]/*.mdupdated concurrently in the same PR.
4. The Counterargument & Failure Modes
"Isn't writing structured EARS requirements just Waterfall 2.0?"
This is a common objection from engineering leaders burned by Big Design Up Front. The key differences lie in granularity and automation:
Waterfall: Heavy upfront planning attempting to predict an entire 6-month system architecture before writing code.
Living Context Refinement: Micro-refinement executed on a single ticket, mapping vague user stories into concrete API fields and EARS syntax in seconds.
Where This Model Fails:
Relying on Human Memory for Doc Updates: If spec updates depend on human memory, persistent docs rot immediately. Mitigation: Deploy IDE pre-flight checks and CI/CD skill gates where the AI detects code diffs and interactively drafts spec updates within the PR.
Over-Specification on Exploratory Work: For early sandbox experiments, heavy spec refinement adds friction. Mitigation: Apply the readiness rubric as advisory guidance rather than a blocking workflow gate during early phases.
5. The Decision Framework
Use this trade-off matrix to evaluate how your organization manages context and requirements for AI coding tools:
Dimension | Ad-Hoc Prompting | Un-Governed Markdown SDD | Living Context & EARS Refinement |
|---|---|---|---|
Primary Input | Conversational chat prompts. | Monolithic text files. | EARS syntax & JSON schemas. |
Context Boundary | Unbounded repo dumps. | Manual | JIT selective ingestion + |
Doc Maintenance | None (High drift). | Manual edit tax. | Automated PR pre-flight checks. |
Token Cost Profile | High (Repeated retries). | Extreme (+20% bloat). | Low (Isolated JIT context). |
Target Outcome | Variable, unguided code. | Documentation debt. | Machine-readable, verifiable contracts. |
6. Reusable Artifact
Below is the Enterprise EARS Requirements & Ticket Refinement Schema. Implement this standard inside your team's shared skills repository or local AGENTS.md workflow to transform rough tickets into AI-coding-ready inputs.
# AI-READY TICKET REFINEMENT SPECIFICATION (EARS STANDARD)
## 1. TICKET SUMMARY & OBJECTIVE
- Ticket ID: [JIRA-KEY]
- Primary Objective: [1-sentence clear business goal]
- Implementation Surface: [Target repo files, API endpoints, or database tables]
## 2. EARS REQUIREMENT CONTRACT
[Must use explicit EARS syntax clauses below. Delete unused patterns.]
- UBIQUITOUS REQUIREMENT:
The [system/service] SHALL [action/behavior].
- EVENT-DRIVEN REQUIREMENT:
WHEN [event/trigger occurs], the [system] SHALL [action] within [latency/constraint].
- STATE-DRIVEN REQUIREMENT:
WHILE [system is in state X], the [system] SHALL [action].
- UNWANTED BEHAVIOR (FALLBACK & ERROR HANDLING):
IF [error condition / dependency missing], THEN the [system] SHALL [fallback action] AND return [status code/error contract].
- OPTIONAL FEATURE:
WHERE [feature flag / config enabled], the [system] SHALL [optional action].
## 3. CONTRACT & SCHEMA DEFINITIONS
- Expected Request/Response Schema: [Insert JSON Schema definition]
- Affected API Fields: [Explicit list of added, modified, or deprecated fields]
## 4. VALIDATION & TEST READINESS
- Deterministic Gate Command: [e.g., npm run lint && npm test]
- Coding Readiness Score: [Pass / Fail / Blocked]
- Test/QA Readiness Score: [Pass / Fail / Blocked by stage data or fixtures]
- Test Scenarios:
1. [Happy path scenario]
2. [Failure/fallback scenario]
7. The Executive Question
Bring this question to your next engineering leadership or architecture committee meeting:
"How is our engineering organization resolving requirement ambiguity before AI coding assistants begin implementation, and what automated gates enforce specification freshness in our merge pipelines?"
🔗 Missed Part 1? Read Issue 1.1 on www.thedatalead.com: Why AI Coding Breaks at Scale—and How Living Context Fixes It