How to Write Functional Requirements: One Realistic Spec, Written Badly and Then Well

Every article about functional requirements gives you the same three things: a definition, a comparison table against non-functional requirements, and a bullet list of examples like "the system shall allow users to log in". You can read all three in four minutes, and none of it will help you on the day you have to write a real one.

The hard part is not knowing what a functional requirement is. The hard part is that your first real set will look fine and be wrong. It will have design decisions dressed up as requirements. It will have three requirements hiding inside one sentence. It will have the word "correctly" doing the work that a business rule should be doing. And it will be missing the one requirement the business actually cares about, because that requirement was never said out loud in the workshop.

So this article does what the others do not. Below is one realistic set of functional requirements for one realistic project, written twice. First the way it gets written on attempt one, with every flaw annotated. Then the same requirements rewritten properly, with the reasoning for each change, traced to the business objective above them and the use case below them. The finished specification is downloadable at the end.

This is part of a series that takes one project from business need to sequence diagram, one artifact per post. If you have read the use case example, you already know the project. If not, the brief is five lines and it is next.

The project context

FlexWell Gyms runs 40 branches. Members currently cancel by phoning their home branch or by cancelling their bank mandate, which creates failed-payment chases and angry reviews. Cancellations arriving via the bank rather than the gym run at 31% of all cancellations. The business wants online self-serve cancellation with one save offer shown before the member confirms. Retention owns the save offer. Finance needs a clean final-payment calculation. The member portal exists; this flow is being added to it.

Two things were settled before anyone wrote a functional requirement, and both matter for what follows.

The business objective. The project is not "build a cancel button". It is this:

BO-01 Reduce the share of cancellations arriving through bank-mandate withdrawal from 31% to under 10% within two quarters of launch, by giving members a self-serve online cancellation that is easier than cancelling at the bank.

Every functional requirement below has to earn its place against that sentence. If a requirement makes online cancellation harder than phoning the bank, it works against the project, however reasonable it sounds.

The stakeholder requirements. Four groups, four interests, two of them in tension:

Notice that SR-01 and SR-02 pull against each other. The member wants out fast. Retention wants one more conversation. The functional requirements are where that tension gets resolved, and the bad version below resolves it by accident, which is the worst way.

One convention before we start, because this series uses it throughout: BO is a business objective, SR a stakeholder requirement, FR a functional requirement, NFR a non-functional requirement, BR a business rule, and UC a use case. The use case post already introduced BR-01 to BR-03; they are referenced below, not rewritten.

Where functional requirements sit

Short version, so the rest makes sense. A functional requirement states what the solution must do: a behaviour, observable from outside, that a tester could confirm. It sits one level below the stakeholder requirement that justifies it, and one level above the use case step or user story that details it. A non-functional requirement states how well the solution must do it: how fast, how available, how secure, under what load. The two are written in the same document and confused in most of them. Non-functional requirements get their own post in this series; this one stays on functional.

---

The bad version, annotated

This is not a parody. It is assembled from patterns that show up in most first attempts, and like the bad use case, it looks acceptable at a glance because the document has a heading that says Functional Requirements and a numbered list underneath it. The annotations are in bold brackets.

Functional Requirements: Membership Cancellation

1. The system should allow users to cancel their membership easily.

[B1: Three problems in one line. "Users" is not an actor; FlexWell has members, branch staff, retention agents and finance, and this project serves one of them. "Easily" cannot be tested; two testers will disagree about whether a flow is easy. And "should" has no force. A requirement is a statement of obligation; if the system may not do it, it is not a requirement, it is a wish.]

2. The cancel button must be red and placed at the bottom of the Membership tab.

[B2: This is a design decision, not a requirement. The business does not need a red button; it needs a way for a member to request cancellation that is easy to find. Colour, placement and tab structure belong to the designer, will change in the next redesign, and will be wrong on the mobile app. Writing them as requirements means every redesign is a change request against the spec.]

3. The system must show a save offer.

[B3: To whom? When in the flow? Which offer? How many times? The brief says retention gets exactly one offer, before confirmation. This line could be satisfied by showing an offer on the login page to every member every day. The most commercially important requirement in the project is here as five words with no conditions on them.]

4. The system must cancel the membership and send an email and update the billing system.

[B4: Three requirements wearing one number. When billing fails but the email sends, has this requirement passed or failed? Nobody can say, because it was never split. The rule is one requirement, one behaviour, one test. Compound requirements are the single most common reason a tester writes "partially passed" and a developer writes "works on my machine".]

5. The system must be fast.

[B5: This is a non-functional requirement, and a useless one. Fast compared to what, measured how, under what load? It will be filed under functional because the author did not know there was another place to put it. Move it, and give it a number: the page that shows the cancellation consequences must render within 2 seconds at the 95th percentile. Now it can fail a test.]

6. Members in notice period cannot cancel.

[B6: Two mistakes. First, it is phrased as a restriction on the member, not a behaviour of the system; what does the system actually do when such a member tries? Second, it is a business rule disguised as a requirement, and the rule is not even right: a member already in a notice period has already cancelled, so the real question is what the system shows them. Rules get stated once, with an ID, and referenced. They do not get restated in slightly different words across six requirements.]

7. The member logs in, goes to My Account, clicks Membership, then clicks Cancel, then confirms.

[B7: This is a use case step sequence pasted into a requirements list, and a bad one, because it is navigation rather than behaviour. The functional requirement is that an authenticated member can request cancellation from their membership overview. How they get there is the use case's job, and the use case already says it without the click-by-click.]

8. The system must calculate the final payment correctly.

[B8: "Correctly" according to what? There is a pro-rating rule, a notice period, a frozen rate and a rate card. If none of them are referenced, "correctly" means "whatever the developer decides on the day". This requirement should point at BR-01 and BR-03 by number, and the acceptance measure should be a worked example with a date and an amount.]

9. The system must integrate with the billing system.

[B9: Integration is not a behaviour. What goes to billing, when, and what comes back? What happens when it does not come back? The brief says finance needs a clean final-payment calculation; this requirement does not mention a payment at all.]

10. The system should not let members cancel if they owe money.

[B10: Nobody asked for this. It is not in the brief, it is not in any stakeholder requirement, and it works directly against BO-01: a member who cannot cancel online goes back to cancelling at the bank, which is the 31% problem. It is also legally doubtful in several markets. Invented requirements like this appear because they feel like good business sense. The source column exists precisely to catch them: a requirement with no source is a requirement to delete or escalate, never to keep.]

11. Retention must be able to see cancellations.

[B11: An actor that is a department, a verb that is "see", and an object with no detail. See what fields, for what period, in what tool? Retention asked for two things in the workshop: the reason a member gave, and whether the offer was accepted. Neither is here.]

12. The system must handle errors gracefully.

[B12: Meaningless as written, and dangerous because it looks like error handling has been considered. The real question is specific: when the retention offer service is down, does the member wait, get blocked, or proceed without an offer? When billing fails, is the cancellation confirmed or not? Each of those is a decision, each decision is a requirement, and "gracefully" is how the author avoided making them.]

Twelve lines, twelve annotations, and the summary is short: the bad version describes the interface instead of the behaviour, bundles several requirements into single sentences, references no rules and no sources, and never decides what happens when something fails. It also has no IDs, no priorities and no traceability, which means that when the project runs out of budget, nobody can say which of these twelve matters least.

And one thing it does not contain at all. Nowhere does the bad version say that the member must see the end date and the final payment before confirming. That is the first line of SR-01. It is the whole reason a member would choose the portal over the bank. It got lost because the author wrote the requirements from imagination rather than from the stakeholder requirements, and imagination produces the flow you would build, not the one the business asked for.

---

The good version

Same project, rewritten. Read it once top to bottom, then the reasoning that follows.

Scope. Online self-serve cancellation of an individual membership by the member, in the existing member portal. Out of scope: cancellations processed by branch staff, cancellations initiated by finance, corporate memberships, and changes to the rate card.

Priority uses MoSCoW: Must for launch, Should for launch if capacity allows, Could for a later release.

---

FR-01 Request cancellation

The system shall allow an authenticated member whose membership status is Active or Frozen, and who has no open payment dispute, to request cancellation of that membership from their membership overview.

• Rationale: the member's entry point, with the eligibility conditions stated once.
• Traces to: SR-01, UC-01 preconditions and step 1.
• Acceptance measure: a member in status Active and a member in status Frozen can each start the flow; a member in status Cancelled, Pending or with an open dispute cannot, and sees FR-02.
• Priority: Must

FR-02 Explain why cancellation is unavailable

When a member who does not meet the FR-01 conditions attempts to request cancellation, the system shall display the specific reason and the channel for resolving it, and shall not create a cancellation request.

• Rationale: an unexplained dead end sends the member to the bank, which is the outcome BO-01 exists to prevent.
• Traces to: BO-01, SR-01, SR-04.
• Acceptance measure: for each ineligible state there is a distinct message naming the state and the next step; no cancellation record is created.
• Priority: Must

FR-03 Show consequences before confirmation

Before the member confirms a cancellation request, the system shall display the membership end date per BR-01, the final payment amount and date per BR-03, and the date on which access ends.

• Rationale: the first line of SR-01 and the main reason to prefer the portal over the bank.
• Traces to: SR-01, UC-01 step 2, BR-01, BR-03.
• Acceptance measure: for a member confirming on 10 March with a 30-day notice period and a monthly rate of 45 EUR, the screen shows an end date of 9 April, a final pro-rated amount per the rate card, and the payment date; the same values appear in FR-07 and FR-10.
• Priority: Must

FR-04 Present one save offer

After the member's first confirmation and before final confirmation, the system shall request a save offer from the retention offer service and, when an offer is returned, shall present the offer and its terms to the member exactly once in the flow.

• Rationale: retention's one shot, placed where the brief put it: before the cancellation is final, not before the member has seen the consequences.
• Traces to: SR-02, UC-01 step 4, BR-02.
• Acceptance measure: an eligible member sees one offer, at this point and nowhere else in the flow; the offer shown is the one the service returned; the offer is not shown to a member the service reports as ineligible.
• Priority: Must

FR-05 Continue without an offer

When the retention offer service returns no offer, or does not respond within the time limit set in NFR-03, the system shall proceed to final confirmation without presenting an offer and shall record the miss with a reason code of either "ineligible" or "timeout".

• Rationale: the member's cancellation is never blocked by retention's infrastructure. The miss is recorded so retention can see what it lost and why.
• Traces to: BO-01, SR-01, UC-01 alternate flow 4a and exception flow 4b.
• Acceptance measure: with the offer service stopped, the flow completes in full; the miss record exists with reason "timeout"; with the service returning "no offer", the miss record exists with reason "ineligible".
• Priority: Must

FR-06 Apply an accepted offer

When the member accepts the save offer, the system shall apply the offer terms to the membership, keep the membership status Active, record the offer redemption against the member, display the new terms, and end the cancellation flow without creating a cancellation.

• Rationale: a different success, for a different stakeholder, with its own end state.
• Traces to: SR-02, UC-01 alternate flow 5a, BR-02.
• Acceptance measure: after acceptance, status is Active, the redemption is recorded with the offer ID and date, no cancellation record exists, and the member can see the new terms in their membership overview.
• Priority: Must

FR-07 Final confirmation

Before recording a cancellation, the system shall require the member to confirm a second time on a screen that restates the end date and the final payment amount from FR-03.

• Rationale: the offer step sits between the first and second confirmation, so the consequences must be restated after it; a member who has just declined an offer should not have to remember numbers from two screens ago.
• Traces to: SR-01, UC-01 step 6 and 7.
• Acceptance measure: the values on the final confirmation screen equal the values shown in FR-03 for the same member and date.
• Priority: Must

FR-08 Record the cancellation

On final confirmation, the system shall set the membership status to Cancelled, record the end date, and submit the final payment to the billing service, such that either all three complete or none do.

• Rationale: finance's requirement for no partial states. Three effects, one requirement, because they succeed or fail together; the containment of a billing failure is FR-09, not an exception buried here.
• Traces to: SR-03, UC-01 step 8 and failure postcondition.
• Acceptance measure: after confirmation, status is Cancelled, end date is recorded, the billing service holds the scheduled payment; if any step fails before commit, none of the three is persisted.
• Priority: Must

FR-09 Contain a billing failure

When the billing service does not acknowledge the final-payment submission within the time limit in NFR-03, the system shall still complete the status change and end date from FR-08, flag the account for finance review, create an operations task, and inform the member that the cancellation is confirmed and that final-payment details will follow within one business day.

• Rationale: the decision made explicit. A member's cancellation never fails because of an internal billing fault, or they go back to the bank. The failure is absorbed internally.
• Traces to: BO-01, SR-01, SR-03, UC-01 exception flow 8a.
• Acceptance measure: with the billing service stopped, the member sees the confirmation message with the one-business-day note; status is Cancelled; a finance review flag and an operations task exist for the account.
• Priority: Must

FR-10 Send the cancellation confirmation

On completion of FR-08, the system shall send the member a cancellation confirmation containing the end date, the final payment amount and date, the date access ends, and the steps to rejoin.

• Rationale: the member's written record, and the thing they would otherwise phone to ask for.
• Traces to: SR-01, UC-01 step 9.
• Acceptance measure: the message is received and its four values equal those recorded in FR-08 and shown in FR-07; delivery timing is NFR-04.
• Priority: Must

FR-11 Record the cancellation reason and offer outcome

On completion of FR-08, the system shall record the cancellation reason category chosen by the member from the managed list, and the save-offer outcome (accepted, declined, not offered with reason code), against the cancellation.

• Rationale: the two things retention asked for by name. Reporting on them is a separate requirement for a later release; capturing them is not optional, because data not captured at the moment of cancellation cannot be reconstructed.
• Traces to: SR-02, UC-01 step 10.
• Acceptance measure: every cancellation record carries a reason category from the managed list and one of the three offer outcomes; a cancellation with FR-05 reason "timeout" shows "not offered: timeout".
• Priority: Must

FR-12 Handle a frozen membership

When the membership status is Frozen, the system shall calculate the end date in FR-03 from the scheduled unfreeze date per BR-01 and the final payment at the frozen rate per BR-03, and shall state on the consequences screen that the notice period runs from the unfreeze date.

• Rationale: the state the bad version never thought about, and the one most likely to generate a support call.
• Traces to: SR-01, SR-03, UC-01 alternate flow 2a, BR-01, BR-03.
• Acceptance measure: for a member frozen until 1 June with a 30-day notice period, the end date shown is 1 July and the final amount uses the frozen rate.
• Priority: Must

---

Deliberately not in this list

• "The system must be fast" became NFR-01 (consequences screen renders within 2 seconds at the 95th percentile), NFR-03 (the time limit for the offer service and the billing service, proposed at 3 seconds and 5 seconds respectively) and NFR-04 (confirmation message dispatched within 5 minutes). The behaviour when a limit is exceeded is functional and lives in FR-05 and FR-09. The limit itself is non-functional. Keeping them apart is what lets the limit be tuned without reopening the behaviour.
• Button colour and placement went to the design brief.
• "Should not let members cancel if they owe money" was removed. It has no source and contradicts BO-01. It is logged as open question OQ-02 for finance and legal, because the right answer may be "allow cancellation, then pursue the debt", and that is their call, not the analyst's.
• Retention reporting is a separate requirement set for release 2. FR-11 captures the data it will need.

Open questions

• OQ-01 Does a save offer that timed out (FR-05, reason "timeout") count as the member's one offer under BR-02 for the rolling 12 months? Owner: retention lead. Not blocking build; blocking the BR-02 eligibility logic in the offer service.
• OQ-02 Members with an outstanding balance: block, allow and pursue, or allow with a warning? Owner: finance controller with legal. Blocking FR-01's condition list if the answer is "block".

---

Why each fix matters

One actor, one verb, one behaviour. The bad version says "users" four times and never says "member". Every good requirement names the actor and the trigger: an authenticated member, from their membership overview, requests cancellation. The scoping decisions that the bad version left implicit are now in FR-01, in one place, and FR-02 says what happens to everyone else.

Behaviour, not interface. FR-01 survives a redesign, a mobile app and a kiosk at the front desk. The red button at the bottom of the tab survives none of them. The test for whether something is a requirement or a design decision is to ask whether a second designer could satisfy it differently and still be right. If yes, it is design.

One requirement, one test. FR-08 has three effects and is still one requirement, because the three succeed or fail together, and that is the point of it. Bad requirement 4 had three effects that fail independently and no statement about what happens when one of them does. The difference is whether the author decided.

Rules are referenced, not restated. BR-01 and BR-03 appear by number in FR-03, FR-07 and FR-12. If the notice period changes from 30 days to 14, one rule changes and three requirements stay true. In the bad version the rule was half-stated in requirement 6 and implied in requirement 8, and a change would mean hunting for every place the author paraphrased it.

Every requirement has a source, and a source catches inventions. Bad requirement 10 could not have survived a traces-to column, because there was nothing to put in it. The column is not bureaucracy. It is the mechanism that stops good business sense from quietly becoming scope.

Failure is a decision. FR-05 and FR-09 are where the analyst ranked the stakeholders: the member's cancellation beats retention's infrastructure, and it beats billing's infrastructure too. Both are written down so retention and finance can object now, in review, rather than in production. "Handle errors gracefully" was the sentence that let the bad version avoid making either call.

Traceability runs in both directions. Read upward: FR-04 exists because of SR-02, which exists because retention has a stake in BO-01. Read downward: FR-04 is detailed by UC-01 step 4, which has an alternate flow 4a that is FR-05. A reviewer can start at any line and walk to the business objective or to the use case step. That walk is what separates requirements from a feature list, and it is the first thing an experienced reviewer tries.

Which comes first, the use case or the functional requirements?

Both audiences ask this, so it gets a direct answer. In practice they are written together and refined against each other. The use case gives you the flow and forces you to confront the alternate and exception paths; the functional requirements give you the testable statements and the traceability. On this project the use case came first as a draft, the requirements were extracted from it and from the stakeholder requirements, and then the use case was corrected where the requirements exposed a gap (FR-12 is the reason alternate flow 2a exists). If you are told to write one and not the other, write the functional requirements, because they are what the tester, the developer and the sponsor can each sign.

User stories, for teams that use them, sit at a different level: a story is a placeholder for a conversation, a functional requirement is the record of what the conversation decided. The two coexist on most mature teams and the acceptance criteria post in this series shows how FR-04 becomes a story with Gherkin criteria without losing the traceability.

Download the finished specification

The good version above is available as a formatted functional requirements specification, the way it would land in a requirements pack or a portfolio: scope, conventions, the four stakeholder requirements, FR-01 to FR-12 with rationale, traceability and acceptance measures, the non-functional requirements it references, the open questions, and a one-page traceability table from BO-01 down to UC-01.

Use it as a reference for structure, then write your own on a different domain, because every reader of this page now has FlexWell.

Write one yourself, then check it against this list

Reading the annotations is not the same as catching the flaws in your own work. Pick one of the other project briefs from the portfolio example: the logistics firm's proof-of-delivery app is the best one for this exercise, because it has a real integration and real failure modes. Write eight to twelve functional requirements, wait a day, then audit them against B1 to B12. B1, B4, B8 and B12 survive almost every first attempt.

If you want the audit done for you, with a grade and specific feedback rather than a checklist, that is what BAvolta's Case Lab is for: you read the stakeholder messages, run the discovery, produce the requirements and the use case, and get structured critique on each one. On Pro, the artifacts export to PDF and land in your portfolio. Module 1 and your first Case Lab case are free. No card needed.

Frequently Asked Questions

What is the difference between functional and non-functional requirements?

A functional requirement states what the system must do: a behaviour a tester can observe, such as presenting a save offer once before final confirmation. A non-functional requirement states how well it must do it: a response time, an availability target, a security constraint. The behaviour when a non-functional limit is breached is itself functional, which is why FR-05 and NFR-03 reference each other.

How many functional requirements should one use case have?

Typically five to fifteen. UC-01 has twelve above. If a use case produces thirty, it is probably two use cases, and if it produces two, the requirements are probably compound and need splitting.

Should I write "shall", "must" or "should"?

Pick one word for obligation and use it everywhere. This specification uses "shall" for every requirement and "should" nowhere, so that "should" cannot creep in as a weaker category. Some teams use "must"; that is fine. Mixing them is not, because readers will treat "should" as optional whether you meant it or not.

Do agile teams write functional requirements?

Most do, under a different name and in smaller pieces. A user story with good acceptance criteria is a functional requirement with a conversation attached. What agile teams drop is the big up-front document, not the discipline of stating testable behaviour with a source.

What is the difference between a functional requirement and a business rule?

A business rule is a constraint of the business that would exist without any system: the notice period is 30 days, a member gets one save offer per year. A functional requirement is what the system does with that rule: calculate the end date per BR-01 and display it before confirmation. Rules are stated once and referenced by ID; requirements reference them.

Who signs off functional requirements?

The sponsor signs the set against the business objective, each stakeholder group signs the requirements that trace to their stakeholder requirement, and the delivery lead confirms the set is buildable and the acceptance measures are testable. A requirement nobody will sign for is one to question.