The Perfect User Story: Write for Humans, Not Robots

Most Jira tickets are garbage. "As a user, I want to click the button so that the button is clicked." This tells the engineer nothing.

A bad user story leads to:

• "That's not what I meant."
• "Why did you build it this way?"
• "This handles the happy path but crashes on errors."

A User Story is not a contract. It is a Placeholder for a Conversation. But you still need to write it down.

Here is what we'll cover:

1. The Template: Beyond "As a User..."
2. Acceptance Criteria (AC): Given/When/Then.
3. The "Why": Giving engineers purpose.
4. The Definition of Ready (DoR).

1. The Narrative (The "Why")

Standard Template:

As a [Role], I want [Feature], so that [Benefit].

Senior Upgrade: Add Context.

Context: Currently, users have to email support to reset their password. This costs us $5,000/month in support time. Goal: Allow users to self-serve password resets via SMS.

Now the engineer knows why. If they realize SMS is too expensive, they might suggest Email instead. You have empowered them to solve the problem, not just build the feature.

2. Acceptance Criteria (The "What")

Ambiguity is the enemy. Bad AC:

• "User can reset password." (Too vague).

Good AC (Gherkin/BDD Style):

Scenario 1: Successful Reset

• Given the user is on the login page
• When they click "Forgot Password"
• Then they should receive an SMS with a 6-digit code

Scenario 2: Invalid Code

• Given the user enters the wrong code 3 times
• Then the account should be locked for 15 minutes

This is testable. A QA engineer can look at this and write the test cases immediately.

3. The Definition of Ready (DoR)

Don't let a story into the sprint unless it meets the DoR.

• Narrative: clear user value.
• AC: Testable scenarios (Happy & Sad paths).
• Assets: specific Figma links (not just "see design").
• Dependencies: Is the API ready?
• Estimated: Has the team agreed on points?

Mentor Tip: Be the gatekeeper. If a PM gives you a half-baked story, say: "This doesn't meet our DoR. Let's refine it in the next session." Do not pollute your sprint with ambiguity.

4. Technical Stories (Chore vs. Spike vs. Story)

Not everything is a User Story.

• Refactor: "Upgrade React 16 to 18." (No user value, but business value).
• Bug: "Fix crash on login."
• Spike: "Research Auth0 vs. Cognito."

Don't force these into the "As a user..." format. "As a developer, I want to upgrade React..." is silly. Just state the goal and the benefit: "Upgrade React to fix security vulnerability X."

Summary

1. Start with Context. Why are we doing this?
2. Use Given/When/Then. clear, testable logic.
3. Handle Edge Cases. define the "Sad Path" explicitly.
4. Enforce DoR. Garbage In, Garbage Out.