From User Stories to DTO + Interface Deltas

In ALD, user stories don’t translate directly into “services.” They translate into decision boundaries, expressed as role-based interfaces, DTOs/types that capture ubiquitous language, and contract tests that define behavior before implementation.

Follow the workflow Copy AI prompts

Goal: produce a crisp, reviewable contract-surface delta (Changed + New) before anyone writes “nitty-gritty” code.

ALD one-liner

DDD helps find boundaries and language. ALD turns that intent into contracts + tests so teams and AI can implement safely behind stable interfaces.

Role-based interfaces DTO vocabulary Contract tests SRP + ISP Adapters at edges

Repeatable workflow (story → contracts)

Use this process every time you want to translate requirements into interfaces and DTOs.

  1. Extract decision boundaries Underline “must decide” statements: approve/deny, classify, validate, price, authorize, route, transform.
  2. Separate orchestration from decisions Use cases coordinate. Policies decide. Adapters integrate. Don’t mix them.
  3. Define DTOs/types in ubiquitous language Use intention-revealing types (e.g., Money, CustomerId) and enforce invariants.
  4. Define role-based interfaces Name roles by responsibility (e.g., EligibilityPolicy, not EligibilityService).
  5. Write contract tests first Tests are the agreement. They remove ambiguity and define policy.
  6. Produce a delta proposal Classify changes: Existing unchanged, Existing changed, New, Deprecated. Flag breaking changes.
  7. Hand off to implementation Teams/AI implement behind contracts. Internal refactors are safe as long as contract tests pass.
Rule of thumb: if the behavior is important enough to argue about, it’s important enough to encode in contract tests.

Story signals that imply DTO/interface changes

Signals that you need new/changed DTOs

  • New data must be captured (“include reason codes”, “track metrics”, “store audit fields”)
  • New meaning emerges (“risk band”, “eligibility status”, “confidence score”)
  • New invariants appear (“LTV must be 0–1”, “currency required”, “timestamp required”)
  • Cross-boundary translation is needed (integration DTO vs domain DTO)

Signals that you need new/changed interfaces

  • A new decision/policy exists (“determine eligibility”, “calculate price”, “authorize action”)
  • A dependency boundary is required (credit bureau, payment gateway, identity provider)
  • You need variability (multiple strategies over time)
  • You need clean orchestration (new use case / workflow step)
ALD boundary rule: vendor/framework types stay in adapters; domain roles depend on ports (interfaces), not SDK models.

Recommended delta output format (what to propose)

This is the “deliverable” developers should produce before implementation (or ask an AI agent to propose). 

A) Decision boundaries (1 sentence each)

B) DTO delta
   - Changed DTOs: name (fields added/removed, invariants)
   - New DTOs/types: name (fields, invariants)

C) Interface delta
   - Changed interfaces: name (signature changes)
   - New roles/ports: name (methods + responsibility statement)

D) Contract test plan
   - For each role: test list (name + 1-line intent)

E) Risks & notes
   - Breaking changes, migrations, open questions
Important: changing a contract test is a policy change. Treat it like a governance decision.

Mini example (story → delta)

A compact illustration. Your real stories will be richer, but the process stays the same.

User story

As an underwriter, I want to submit a loan application and receive an eligibility decision with reason codes.

  • If LTV > 80%, ineligible with LTV_EXCEEDS_MAX
  • If credit score < 620, ineligible with CREDIT_SCORE_BELOW_MIN
  • Otherwise eligible with ELIGIBLE
  • Decision includes status, reason codes, evaluated metrics, timestamp

Resulting contracts

  • New roles: EligibilityPolicy, LoanToValueCalculator, CreditScoreProvider
  • Changed DTO: LoanApplicationDraft (add applicant + property value + loan amount)
  • New DTOs: EligibilityDecision, EligibilityMetrics, EligibilityReasonCode
  • Contract tests: define thresholds, reason codes, and required evidence fields
Example contract test names 
ineligible_when_ltv_exceeds_max_returns_LTV_EXCEEDS_MAX()
ineligible_when_credit_score_below_min_returns_CREDIT_SCORE_BELOW_MIN()
eligible_when_thresholds_met_returns_ELIGIBLE()
decision_includes_metrics_and_timestamp()
ALD intent: the orchestrator stays thin; decisions live behind policies; integrations live behind adapters.

AI agent prompt (to propose a DTO/interface delta)

If your AI agent is aware of the repo and ALD principles, use this prompt to get a structured delta proposal. 

You are an ALD-aware software architect assistant with full read access to this repo.
Your job is to propose the smallest, safest CONTRACT-SURFACE change (DTOs + role interfaces + contract tests) needed to satisfy the user story.

ALD rules you must follow:
- Interfaces are ROLE-based, not layer-based (no “Service/Repository” buckets).
- Prefer SRP/ISP: split responsibilities so each role has one reason to change.
- DTOs/types must reflect ubiquitous language and enforce invariants (avoid primitives when meaning exists).
- Keep frameworks/vendors at the edge via ports/adapters. Do not leak vendor SDK types into core domain.
- Contract tests define behavior; changing a contract test = policy change.

Task:
1) Identify decision boundaries implied by the story.
2) Produce a proposed DTO/interface delta: Existing -> Changed, and New.
3) Propose contract tests (names + scenarios) that define intended behavior.
4) Call out breaking changes and propose a safer alternative if possible.

Output format (strict):
A) Decision boundaries
B) DTO delta (Changed + New)
C) Interface delta (Changed + New)
D) Contract test plan (by role)
E) Risks & notes

User story:
<PASTE STORY + ACCEPTANCE CRITERIA HERE>
Tip: Ask the agent to search the repo first and list “relevant existing DTOs/roles found” before proposing changes.

Quick checks (what good looks like)

Good DTOs

  • Use domain terms (ubiquitous language)
  • Enforce invariants (invalid states are hard to represent)
  • Separate domain DTOs from integration DTOs
  • Prefer additive evolution and translation at boundaries

Good interfaces (roles)

  • Single responsibility (SRP)
  • Small surface (ISP)
  • Named by decision responsibility (not layers)
  • Integrations behind ports/adapters
  • Behavior defined by contract tests
Final takeaway: if you can’t describe a role in one sentence, it’s probably too broad.