nwave-ai/nw-dor-validation

DoR Validation and Antipattern Detection

Definition of Ready Checklist (8 Items - Hard Gate)

All items must PASS with evidence. Each FAIL blocks handoff.

Item 1: Problem Statement Clear and Validated

Domain language (not technical), describes real user pain, testable. Pass: "Maria wastes 30 seconds typing credentials on every visit" Fail: "Users need authentication" | "Implement login feature"

Item 2: User/Persona with Specific Characteristics

Real name, specific role, clear context. Pass: "Maria Santos, returning customer (2+ orders), using trusted MacBook" Fail: "User" | "Customer" | "End user" | "Authenticated user"

Item 3: At Least 3 Domain Examples with Real Data

Min 3 examples, real names (not user123), real values, different scenarios (happy/edge/error). Pass: "Example 1: Maria on MacBook, 5 days since login, goes to dashboard" Fail: "User logs in successfully" | "Test with valid credentials"

Item 4: UAT Scenarios Cover Happy Path + Edge Cases

Given/When/Then format, 3-7 scenarios, real data, covers happy + edge. Pass: "Given Maria authenticated on 'MacBook-Home' 5 days ago..." Fail: "Test login works" | "Given a user When they login Then success"

Item 5: Acceptance Criteria Derived from UAT

Checkable (checkbox), traceable to UAT, outcome-focused (not implementation). Pass: "Sessions older than 30 days require re-authentication" Fail: "Use JWT tokens" | "System should work correctly"

Item 6: Story Right-Sized (1-3 Days, 3-7 Scenarios)

Effort estimate provided, scenario count in range, single demonstrable outcome. Pass: 2 days, 5 UAT scenarios, demoed in single session Fail: >7 scenarios | >3 days | multiple distinct outcomes

Item 7: Technical Notes Identify Constraints

Dependencies listed, risks identified, architectural considerations noted. Pass: "Requires JWT token storage, GDPR cookie consent integration" Fail: no technical notes section

Item 8: Dependencies Resolved or Tracked

Blocking deps identified, resolution status clear, escalation path. Pass: "Depends on US-041 (completed) and Auth service API (available)" Fail: "Needs some API - TBD"

---

Antipattern Detection (8 Patterns)

1. Implement-X (critical)

Signal: starts with "Implement", "Add", "Create", "Build", "Develop" Detection: ^(Implement|Add|Create|Build|Develop)\s | Fix: rewrite as user pain

2. Generic Data (high)

Signal: user123, [email protected], foo, bar, lorem, placeholder Detection: user[0-9]+, test@, example@, foo, bar | Fix: real names -- Maria Santos

3. Technical AC (high)

Signal: AC describes implementation not outcome Detection: "Use JWT", "Implement using", "Database should", "API must return" Fix: outcome focus -- "Session persists for 30 days"

4. Giant Stories (critical)

Signal: >7 scenarios | >3 days | multiple distinct outcomes | Fix: split by user outcome

5. No Examples (critical)

Signal: no "Example" section | <3 examples | abstract examples | Fix: add 3+ with real data

6. Tests After Code (high)

Signal: "Tests to be added", "Will write tests later", "Tests TBD" | Fix: UAT first, RED first

7. Vague Persona (high)

Signal: "User", "Customer", "End user" as persona | Fix: "Maria Santos, returning customer (2+ orders)"

8. Missing Edge Cases (medium)

Signal: all success scenarios, no errors, no boundaries | Fix: add expired session, invalid device, etc.

---

UAT Scenario Quality Checks

Format: Given/When/Then with complete sentences. Fail: "Test login", "Given user When login Then success" Real Data: real names, values, scenarios. Fail: "Given user123", "When X happens" Coverage: min 1 happy path + 1 edge + 1 error. Range: 3-7 scenarios.

---

Domain Language Checks

Technical Jargon: flag in user-facing sections: JWT, API, database, backend, frontend, microservice, REST, HTTP, JSON, SQL. Exception: Technical Notes section. Fix: "session token" -> "remember me"

Generic Language: flag "the system", "the application", "functionality", "feature". Fix: use specific names -- "the login page" -> "the welcome screen"