How to write user stories your developer actually understands

A founder came to us last quarter with a feature list: “User management. Dashboard. Reports. Notifications. Integrations.” Five words. The development quote? Somewhere between $18,000 and $140,000 depending on which agency read those five words.

The problem isn’t that agencies give bad quotes. The problem is that “dashboard” means a different thing to every person who reads it. One agency reads “dashboard” as 3 widgets showing monthly totals. Another reads it as a real-time analytics platform with custom date ranges, export functionality, role-based views, and 15 chart types.

User stories fix this. A user story turns “dashboard” into “As an admin, I want to see total revenue and active users for the last 30 days so I can report to investors.” Now every agency quotes the same thing. The variance drops from 8x to 1.5x.

The template that works

Every user story follows one format:

As a [role], I want to [action] so that [outcome].

That’s it. No technical details. No design specs. No “and also.” One role, one action, one reason. If you’re using “and” in the action, you need two stories.

The three parts matter:

Role tells the developer which user type this applies to. “Admin” has different permissions than “customer.” A story without a role gets built for the wrong audience.

Action describes exactly what the user does. Not “manage accounts” — that’s 15 different actions. “Reset a customer’s password from the admin panel.” Specific. Testable. Quotable.

Outcome explains why this action matters. This is what developers use to make design decisions. If the outcome is “so I can respond to support tickets faster,” the developer knows speed matters. If the outcome is “so I can maintain an audit trail,” the developer knows logging matters. Same action, different implementation.

15 user stories from real projects

These are from actual projects we’ve built. Notice how specific each one is — and how each one could be independently estimated and tested.

Booking system ($38,000 project):

1. As a customer, I want to see available time slots for the next 14 days so that I can book without calling.
2. As a provider, I want to block specific dates so that I’m not booked during holidays.
3. As an admin, I want to see all bookings for today in one view so that I can manage walk-ins alongside online bookings.

Marketplace ($85,000 project): 4. As a buyer, I want to filter listings by price, location, and category so that I find relevant results in under 5 seconds. 5. As a seller, I want to receive an email when someone messages me about a listing so that I don’t miss inquiries. 6. As a seller, I want to see my total earnings and pending payouts so that I can track my revenue.

SaaS dashboard ($52,000 project): 7. As a team admin, I want to invite users by email and assign roles so that I control who sees what. 8. As a user, I want to export my report as a PDF so that I can share it with stakeholders who don’t have accounts. 9. As an admin, I want to see which team members logged in this week so that I can follow up with inactive users.

Customer portal ($24,000 project): 10. As a client, I want to see all my invoices in one place so that I don’t have to search my email. 11. As a client, I want to upload documents and see which ones my advisor has reviewed so that I know where things stand. 12. As an advisor, I want to leave notes on a client’s profile that only other advisors can see so that handoffs don’t lose context.

E-commerce ($45,000 project): 13. As a shopper, I want to save items to a wishlist so that I can come back and purchase later. 14. As a shopper, I want to see estimated delivery dates before checkout so that I know when to expect my order. 15. As a store owner, I want to set up automatic discount codes that expire after a specific date so that I can run time-limited promotions.

Each story is one sprint task. A developer reads it, estimates it (2 hours, 8 hours, 3 days), and knows exactly when it’s done.

The 3 mistakes that inflate your quote

Mistake 1: Epic stories. “As a user, I want to manage my account.” That’s not a story — it’s a feature. It hides 8-12 smaller stories inside it: update profile, change password, upload avatar, manage notifications, link payment method, view activity history, delete account, change email. An agency that quotes “manage account” as one item will come back with change orders. An agency that breaks it into 10 stories gives you an accurate number.

Mistake 2: Technical stories. “The system should use PostgreSQL with Redis caching.” That’s an implementation decision, not a user need. User stories describe what people do, not how the code works. Let the developer pick the database — your job is to describe the behavior. The product requirements document covers technical decisions separately.

Mistake 3: Missing acceptance criteria. “As a user, I want to search for products.” Done when… what? When it searches by name? By category? By price range? With autocomplete? With fuzzy matching? Add acceptance criteria: “Done when: user can search by name or category, results load in under 2 seconds, and the page shows ‘no results found’ with suggestions when nothing matches.”

From user stories to project scope

User stories are the building blocks. Project scope is the wall.

Group your stories by feature. Count them. Estimate effort per story (your developer does this). Add it up. That’s your scope — not a vague “build a marketplace” but “47 user stories across 6 features, estimated at 480 development hours.”

Now you can have real conversations: “What if we cut feature 4 and ship 5 stories from feature 6 in V2 instead?” That removes 12 stories and $9,000 from the quote. You’re negotiating on specifics, not vibes.

A well-written set of user stories is the difference between a quote you can trust and a number someone made up. If your agile team doesn’t start with stories, they’re not doing agile — they’re guessing.

---

Want help turning your idea into user stories? Send us your concept in plain English — we’ll send back the first 10 stories for free. Send your concept.