Nw Leanux MethodologySAFE

AI agents that guide you from idea to working code, with you in control at every step.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: nw-leanux-methodology
description: LeanUX backlog management methodology - user story template, story sizing, story states, task types, Definition of Ready/Done, anti-pattern detection and remediation
user-invocable: false
disable-model-invocation: true
---

# LeanUX Backlog Management Methodology

"A backlog is not a todo list. It's a collection of validated hypotheses waiting to become working software."

## Story States

| State | Meaning | Entry Criteria |
|-------|---------|----------------|
| Draft | Idea captured, not validated | Has problem statement |
| Ready | Validated, has UAT, ready to build | All DoR items complete |
| In Progress | Actively being built | UAT test written (RED) |
| In Review | Code complete, awaiting review | All tests green |
| Done | Merged, deployed, validated | UAT passes in production |
| Blocked | Cannot proceed | Blocker documented |

## Story Sizing Criteria

### Right-Sized
Completable in 1-3 days | 3-7 UAT scenarios | Delivers demonstrable value | Explainable in 2 minutes

### Oversized Indicators
>7 UAT scenarios | >3 days effort | Multiple distinct user outcomes | Cannot demonstrate in single session

### Splitting Strategy
Split by user outcome, not technical layer. Each resulting story delivers independently demonstrable value.

Example: "User Management" (20 scenarios) splits into:
- "Quick Login" (5 scenarios) -- returning customer on trusted device
- "New Registration" (4 scenarios) -- first-time customer sign-up
- "Password Recovery" (3 scenarios) -- customer who forgot credentials
- "Profile Settings" (4 scenarios) -- customer updating preferences

## Definition of Ready (DoR) - Hard Gate

Stories pass ALL 8 items before proceeding to DESIGN wave.

### Checklist with Pass/Fail Examples

**1. Problem statement clear and in domain language**
- Pass: "Maria wastes 30 seconds typing credentials on every visit"
- Fail: "Users need authentication"

**2. User/persona identified with specific characteristics**
- Pass: "Returning customer (2+ orders) on trusted personal device"
- Fail: "User" or "Customer"

**3. At least 3 domain examples with real data**
- Pass: "Maria on her MacBook, last login 5 days ago, goes directly to dashboard"
- Fail: "User logs in successfully"

**4. UAT scenarios in Given/When/Then (3-7 scenarios)**
- Pass: "Given Maria authenticated 5 days ago on 'MacBook-Home'..."
- Fail: "Test login functionality"

**5. Acceptance criteria derived from UAT**
- Pass: "Sessions older than 30 days require re-authentication"
- Fail: "System should work correctly"

**6. Story right-sized (1-3 days, 3-7 scenarios)**
- Pass: "2 days effort, 5 scenarios, single demo-able feature"
- Fail: "Epic with 20 scenarios"

**7. Technical notes identify constraints**
- Pass: "Requires JWT token storage, GDPR cookie consent"
- Fail: "No technical considerations"

**8. Dependencies resolved or tracked**
- Pass: "Depends on US-041 (completed) and Auth service API (available)"
- Fail: "Unspecified external dependencies"

### Validation Output Format

```markdown
## Definition of Ready Validation

### Story: {story-id}

| DoR Item | Status | Evidence/Issue |
|----------|--------|----------------|
| Problem statement clear | PASS/FAIL | {evidence or issue} |
| User/persona identified | PASS/FAIL | {evidence or issue} |
| 3+ domain examples | PASS/FAIL | {evidence or issue} |
| UAT scenarios (3-7) | PASS/FAIL | {evidence or issue} |
| AC derived from UAT | PASS/FAIL | {evidence or issue} |
| Right-sized | PASS/FAIL | {evidence or issue} |
| Technical notes | PASS/FAIL | {evidence or issue} |
| Dependencies tracked | PASS/FAIL | {evidence or issue} |

### DoR Status: PASSED / BLOCKED
```

### Failure Recovery
When DoR fails:
1. Display specific failures with remediation guidance
2. Do not proceed to peer review or handoff
3. Return to user with action items
4. Re-validate after fixes applied

## Definition of Done (DoD) - Completion Criteria

DoD validation owned by acceptance-designer during DISTILL->DELIVER transition. Product-owner defines checklist, acceptance-designer enforces.

Checklist:
- All UAT scenarios pass (green) | All supporting tests pass (unit, integration, component)
- Code refactored, no obvious debt | Code reviewed and approved
- Merged to main branch | Deployed to staging/production
- Story can be demoed to user

## Anti-Pattern Detection and Remediation

### Implement-X
- Signal: Task starts with "Implement X" or "Add X"
- Problem: No user context, technical focus, vague completion
- Bad: "Implement user authentication"
- Good: "Returning Customer Quick Login -- Maria wastes 30 seconds..."
- Fix: Start with user pain point, rewrite as problem statement

### Generic Data
- Signal: Examples use "user123", "[email protected]"
- Problem: Lacks real-world context, harder to validate
- Bad: "Given user123 logs in with password123"
- Good: "Given Maria Santos ([email protected]) on her MacBook"
- Fix: Replace all generic data with real names and realistic values

### Technical Acceptance Criteria
- Signal: AC describes implementation ("Use JWT tokens")
- Problem: Prescribes solution, not testable outcome
- Bad: "Use JWT tokens for session management"
- Good: "Session persists for 30 days on trusted device"
- Fix: Focus on observable user outcome, move tech choices to DESIGN

### Oversized Stories
- Signal: >7 scenarios or >3 days effort
- Problem: Too large to track, deliver, or demo meaningfully
- Bad: "Complete user management (20 scenarios)"
- Good: "Quick Login (5 scenarios), Password Reset (4 scenarios)"
- Fix: Split into focused stories by user outcome

### No Examples
- Signal: Abstract requirements without concrete examples
- Problem: Ambiguous, untestable, different interpretations
- Bad: "Users should be able to manage their settings"
- Good: "Maria changes notification frequency from daily to weekly"
- Fix: Add 3+ concrete narratives with real data

### Tests After Code
- Signal: Tests written after implementation
- Problem

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.