Writing Salesforce requirements: user stories your partner can build

Good Salesforce requirements describe the outcome a person needs and the rule that governs it, not the screen or button that delivers it. Write each one as a short user story naming the role, the need and the reason. Then add acceptance criteria a tester can pass or fail, plus the definitions, volumes, exceptions and visibility rules behind it. That gives your partner something buildable and gives you something to test against.

Why do vague requirements turn into rework and change orders?

A partner can only estimate and build what is written down. Anything left vague gets filled with an assumption, and you usually discover that assumption during testing.

Take "improve lead management." Sales hears faster routing; marketing hears better source reporting. The partner builds one reading, and the other returns as a change request with rebuild and retesting attached.

The cure is not longer documents. It is sharper statements: who needs something, what must happen, under which conditions, and how everyone will know it works.

Should you describe the outcome or the solution you have in mind?

Describe the outcome and the business rule. Leave the choice of field, flow, component or layout to the people who know the platform.

"Add a VIP checkbox" is a solution. The underlying need might be that service agents must spot accounts with a premium support contract and handle their cases first. Stated as a need, the partner can weigh a field, a highlights panel, a case priority rule or entitlements. The outcome stays fixed while the design stays open.

There are fair exceptions. If a regulator, auditor or downstream system demands a specific format, say so and explain why. A constraint with a reason is a requirement. A preference without one is a design suggestion.

What does a buildable Salesforce user story look like?

Use the pattern: as a [role], I want [capability], so that [outcome]. The role must be real and the capability testable.

For example: as an inside sales rep, I want territory web leads assigned to me automatically, so that I call while interest is fresh. Four habits help:

• Name a job title or team, never "the user" or "the system."
• Keep one capability per story. If the sentence needs a second "and," split it.
• Make the "so that" clause carry real value. It is what the sponsor uses to rank stories later.
• Keep the story to one sentence and push the detail into acceptance criteria.

When is a user story on its own not enough?

When the work depends on calculations, data rules, integrations or compliance, the story needs supporting material. One sentence cannot carry a commission formula or a field mapping.

Attach what the builder needs: a decision table for routing, an integration field list, sample records, a report sketch or the governing policy text. Link these to the story instead of cramming them into it.

How do you write acceptance criteria that can be passed or failed?

Write conditions specific enough that two testers would reach the same verdict. Given/when/then statements and plain checklists both work; using one format consistently matters more than which one.

Given/when/then states the starting situation, the action and the expected result. Here are Salesforce-flavored examples:

• Lead assignment: Given a web lead with a West territory postal code, when it is saved, then the next West rep in rotation owns it. The new owner gets an email alert.
• Approval threshold: Given a discount above the finance limit, when the rep submits the opportunity, then a regional manager must approve before quoting.
• Field visibility: Given a support agent, when they open an account, then they see the contract end date. They cannot see margin fields or report on them.
• Report output: Given closed-won deals for the quarter, when the sales director opens the pipeline dashboard, then totals by stage and owner reconcile with the finance figure.

Include at least one negative case per story: what must not happen, or who must not see something. Defects tend to hide in the situations nobody bothered to write down.

Which business rules and data definitions need writing down?

Record every rule the system must enforce and every term that teams use differently. Mismatched definitions are a common reason leaders stop trusting reports.

"Active customer" is the classic case. Sales may mean anyone who bought last year, finance anyone with a live contract, and service anyone holding a support entitlement. Choose one definition, name its owner and write it down.

• Definitions: active customer, qualified lead, churned account, booked revenue. Each needs an exact rule and an owner.
• Business rules: who may change a stage, what makes a field mandatory, when a discount needs sign-off.
• Volumes: records created per day, total records to migrate, users per role, and peaks such as quarter end.
• Exceptions: key accounts that bypass routing, deals allowed to skip a stage, a region with different tax handling.

Exceptions deserve extra effort. Teams describe the normal path easily and forget the odd cases that eat their day.

Which non-functional needs should your requirements cover?

Non-functional needs describe how the system must behave rather than what it does. They are easy to forget and costly to retrofit.

• Security and visibility: who can view, edit or export which records, and which teams must be kept apart.
• Performance: how quickly key pages and searches should respond, and how much delay is acceptable on synced data.
• Audit: which field changes must be tracked, for how long, and who reviews them. Standard field history has limits, so raise long retention needs early.
• Integrations: which systems exchange data, in which direction, how often, and which one wins a conflict.
• Mobile: which tasks happen on a phone, and whether people need to work without a signal.

How should you rank and slice stories so value ships early?

Rank stories by business value, then split large ones into thin slices that each work end to end. A thin slice people are using teaches you more than a complete feature stuck in testing.

MoSCoW is a simple start: Must have, Should have, Could have, Won't have this time. Its weakness is that everything drifts into Must. Limit Must to what the first release truly cannot launch without, and have the sponsor approve that list.

Slice by workflow, not by technical layer. Skip the data-model-then-automation-then-reports plan. First deliver a rep logging a qualified lead that the manager sees on a report. Then add routing, then approvals. Each slice is testable and usable, and early feedback improves the next one.

Why should you define the reports leaders need first?

Reports dictate the data the system must capture. Once you know the questions leadership will ask, you know which fields, statuses and dates users must record.

Ask each leader for the handful of numbers they check most and the decisions those numbers drive. Mock it up, even in a spreadsheet, then work backwards. Every column needs a field, every filter needs a dependable value, and every trend needs a date someone actually enters.

This surfaces gaps early. A win rate by lead source report fails if lead source is optional or filled in loosely.

How do weak requirements compare with buildable ones?

Most weak requirements leave a key word for the builder to interpret. The rewrites below add a role, a reason and testable criteria.

How do you trace each story from requirement to test?

Give every story an ID and carry it onto the related design notes, build items and test scripts. That shows each requirement was built and tested, and nothing unplanned slipped in.

Acceptance criteria turn almost directly into test steps. Each given/when/then line becomes a scenario a business tester runs and signs off. Our guide to Salesforce user acceptance testing covers planning and running those sessions. A simple matrix is enough: story, criteria, test case, result, sign-off.

When a requirement changes mid-project, update the story and its criteria first, then the tests. Editing a test without touching the story quietly hides a scope change.

Which tools work for writing and tracking Salesforce requirements?

Any backlog tool with IDs, statuses, priorities and attachments will do. Jira, Azure DevOps or a carefully kept spreadsheet can all work; discipline matters more than software.

Some teams prefer to keep project work inside Salesforce itself. Salesforce has published an app called Agile Accelerator on AgentExchange (formerly AppExchange) for managing stories, sprints and work items in an org. Review the listing, recent updates and who supports it before you commit. Whatever you pick, agree with your partner where the master copy of each story lives, so nobody edits two versions.

What mistakes do business teams make when writing requirements?

• Copying the old system: rebuilding every legacy field and screen instead of stating what work they support.
• Covering only the happy path: no exceptions, no negative cases and no volumes.
• Leaving terms undefined: "priority account," "active" or "closed" left to each reader.
• Writing stories too big to test, such as one story for a whole department's process.
• Ranking by committee: every wish lands in Must and nobody has authority to say no.
• Naming no answerer: nobody on your side responds quickly to questions, so the builder guesses.

What should a Salesforce requirement template include?

Keep it short enough that business owners will fill it in:

• ID and a short title.
• User story: As a..., I want..., so that....
• Acceptance criteria, including at least one negative case.
• Business rules and definitions the story depends on.
• Data: fields involved, expected volumes and source systems.
• Non-functional notes: visibility, audit, integration and mobile.
• Priority and target release.
• Requester, the business owner who answers questions, and the approver.
• Links to mock-ups, sample records and test cases.

Draft the story and criteria yourself, then review the rest with your partner. Ask them to flag anything ambiguous before they estimate it.