Requirements are contracts between the people who specify a system and the people who build it. Most projects fail at this layer, before a single line of code is written. The discipline is older than software, well understood, and routinely skipped.
The acceptance test was scheduled for two hours. It ran for six, and the system was never the problem. The problem was one sentence in the specification, written eighteen months earlier: “the display shall update responsively.” The customer had pictured a quarter of a second. The team had built for two. Both readings were reasonable. Neither was in the document, and so the afternoon went to a negotiation that should have taken five minutes on the day the sentence was written, back when a number would have cost nothing.
A requirement is a written statement that defines, precisely, what the system must do or constrain itself to. It is a contract between the people who specify what is needed and the people who build it, binding both sides to the same definition of done. A wish, a preference, or a description of the future is something else, and the difference only shows up when it is expensive.
Why they exist. Without contracts, every interpretation is equally valid. Two engineers reading the same vague phrase walk away with different mental models, build different things, and discover the mismatch at integration or, worse, at acceptance. The cost of arguing about requirements at the start of a project is hours. The cost of arguing about them at the end is the project.#
The mental model. Ordering a custom suit. “Make me a nice suit” produces something the tailor thinks is nice, which may be far from what you wanted. “Charcoal grey wool, single-breasted, two buttons, sleeves to my wrist bone, trousers no break” produces a suit that matches what you ordered or fails an objective check. Requirements are the second sentence. They close the gap between “what you meant” and “what got built.”#
The discipline. Every requirement is testable, traceable, and unambiguous. Testable means you can construct an objective check that says yes or no. Traceable means you know where it came from and what depends on it. Unambiguous means two competent engineers reach the same conclusion when they read it. A requirement that fails any of the three is a wish in formal clothing.#
One program I joined had been stalled, cancelled, and restarted more than once, and the codebase showed it: a sprawling attempt to do everything anyone had ever mentioned, because the scope changed every quarter and nothing had ever been written down firmly enough to say no to. There were, in any practical sense, no requirements. Every feature request was as valid as every other, so every one of them got half-built, and the half-built features were the architecture.
The lesson. A requirement is also the thing that lets you decline. Without a written definition of what the system is, there is no written definition of what it is not, and a system that is everything ships as nothing.
If you cannot test it, it is a wish. If you cannot trace it, it is decoration. If you cannot agree on what it means, it is a future fight. Requirements engineering is the discipline of refusing to let any of those three slide.
A requirement is a contract: testable, traceable, unambiguous, and the only written way to say no.
Good requirements have a recognizable shape. The shape exists because it forces every author to confront the parts that vague language hides: what subject, what action, under what condition, with what tolerance. Once you internalize the shape, writing them becomes mechanical; the discipline is in refusing the shortcuts that hide any of the four parts.
The aerospace and defense world standardized on one verb, SHALL, for binding requirements, and the convention is worth adopting whatever your domain. SHALL means “this is required.” SHOULD is a recommendation, MAY is a permission, WILL describes expected behavior. Mixing them leaks ambiguity into the contract.
One requirement, four parts. Every part has a job, and a sentence missing any of them has a hole where the argument will later be.
Example: a power consumption requirement
Weak: “The system should be efficient and not use too much power.”#
Strong: “The system SHALL consume less than 12 W average power and 25 W peak power during normal operation, measured at the +28 V input over a 1-hour duty cycle.”#
Quantity: under 12 W average, under 25 W peak (numbers).
Conditions: +28 V input, 1-hour duty cycle (testable).
Notice what the weak version is missing: every quantity. “Efficient” means whatever the reader thinks it means. “Too much” is undefined. “Should” is non-binding. The strong version is testable because it is specific, and it is specific because the author refused to let any of the four parts remain implicit.
Low signal
A requirement you can argue about
“The system should be efficient.” Two competent engineers read it and picture two different targets. Acceptance becomes a negotiation, held at the worst possible time: the end.
vs
High signal
A requirement you can test
“…SHALL consume less than 12 W average, measured at +28 V over a 1-hour duty cycle.” One objective check, one yes-or-no, agreed by everyone before a line is built.
One requirement, one statement. A requirement that contains the word “and” is usually two requirements wearing one number, and at acceptance you will have to decide whether half-passing counts. Failure mode: compound requirements that pass partially and fail partially, with no clear answer overall.
Verifiable.
You can construct an objective test. There is a measurement, a procedure, a yes-or-no answer. “User-friendly” is unverifiable; “90% of users complete task X in under 30 seconds” is verifiable. Failure mode: requirements checked off on opinion rather than measurement.
Unambiguous.
Two competent engineers read it and reach the same conclusion. If you have to explain what a requirement means in conversation, the requirement has failed; rewrite it. Failure mode: the same words producing different implementations on different teams, discovered at integration.
Complete.
Specifies behavior in all relevant cases: nominal, off-nominal, fault, edge. The error case is part of the requirement rather than an oversight. Failure mode: the system handles the happy path and crashes when reality deviates. Six months later, in the field.
An adjective in a requirement is a number somebody decided to argue about later.
Subject, SHALL, quantity, condition: write all four, every time, and the adjectives take care of themselves.
3.3Name the verification method when you write it#
A requirement is finished when it says how it will be proven. The habit that makes this mechanical is to assign one of four verification methods to every requirement at the moment it is written, in a column right next to it. If no method fits, the requirement is unverifiable as written, and you have found that out on the cheapest possible day.
Method
What it means
Reach for it when
Evidence it produces
Inspection
Look at the thing, or its documents, and confirm the property is present.
The requirement is about presence, labeling, dimensions, materials, or conformance to a written interface.
A signed checklist, a drawing, a photo, a document review record.
Analysis
Prove it on paper: calculation, modeling, simulation, or data from a representative test extrapolated to the required condition.
A direct test would take as long as the mission, destroy the article, or require conditions you cannot produce.
The analysis itself, with its assumptions and inputs recorded, and the measured data it rests on.
Demonstration
Operate the system and observe that it does the thing, with a qualitative pass criterion.
The requirement is about a capability or a procedure, and a witness can see it happen.
A witnessed run with the steps and outcome recorded.
Test
Operate the system under controlled conditions and measure the result against a numeric criterion.
The requirement has a number in it and the number can be measured.
Measured data, the instrument used, the conditions, and a pass or fail against the limit.
Two things follow from the table. First, the method shapes the wording: a requirement to be verified by Test needs a limit and a condition; one verified by Analysis needs its assumptions nameable. Second, a requirement verified by Analysis still needs measured inputs. “Operates for 180 days” will be proven by a power budget, and the power budget is only evidence once its currents came from a bench rather than a datasheet. Verification shows how each method turns into a procedure; the point here is to choose the method while the ink is wet.
Inspection, Analysis, Demonstration, or Test: pick one as you write, and a requirement that resists all four is a requirement to rewrite.
What it is. Taking a high-level mission requirement and breaking it down through layers, system, subsystem, component, until each leaf is small enough that one team can verify it independently. The decomposition tree is what makes a complex project tractable; it is how a multi-thousand-page specification turns into individual responsibilities a team can act on.#
Why it matters. No single engineer can verify a mission-level requirement directly. “The system shall communicate with the ground station” spans antennas, radios, protocols, security, schedules, and ground hardware. You cannot test it as one thing. The decomposition turns that one impossible test into a tree of possible ones, each owned by someone with the expertise to verify it. When the leaf tests pass, the parent passes by construction.#
The mental model. An organizational chart. The CEO has a goal that no one person can execute alone. Each layer below decomposes it into specific accountabilities. At the bottom of the chart, work happens. Above it, ownership is allocated.#
One mission sentence becomes three system requirements, one of those becomes three subsystem requirements, and so on down to leaves a single team can test. Every leaf points up to a parent.
Example: from mission to component
Level 1 (mission): “The satellite SHALL provide 1 Mbps continuous data to ground users.”#
Reading the tree. Each level derives from the level above. If a Level 1 requirement changes, say the data rate becomes 10 Mbps, you walk the tree downward and reassess every leaf. Some will be unaffected. Others will need to change. The tree is what makes change tractable; without it, a top-level change becomes a whole-system audit.#
How it fails. The most common failure is requirements that are inventions rather than decompositions, added without a parent. A leaf that derives from no higher-level need is either dead code waiting to happen or a hidden scope addition nobody approved. If a requirement has no parent, it has no business in the spec.#
Decompose until each leaf is something one team can test, and insist that every leaf point up to a parent.
What it is. A directed graph linking each requirement to the design elements that satisfy it, the test cases that verify it, and the higher-level requirements it derives from. In practice it is a matrix, a spreadsheet, a database, or a tool, that lets you ask three questions and get an answer:#
For any requirement, which tests verify it?
For any test, which requirements does it cover?
For any design element, which requirements does it implement?
One requirement, traced both ways: up to the customer request it came from, down to the element that implements it and the tests that prove it.
Why it matters. Without traceability, the project loses memory. A change request comes in: “the data rate is now 10 Mbps instead of 1 Mbps.” What does that affect? Without traceability, the only honest answer is “a lot of things, we will find out as we go.” With it, you can name the affected requirements, design elements, and tests in minutes, and the cost of the change is knowable rather than estimated.#
The mental model. Building permits in a city. Each modification has a permit, the permit references the original plans, the plans reference the building code, and an inspector can walk any chain backward. When you renovate, the chain tells you what you are affecting. When something fails, the chain tells you what was supposed to prevent it.#
Reading the matrix. Each row says: this requirement comes from this customer request, is implemented by this design element, will be verified by these test cases, and is currently in this state. The status column tells you at a glance which requirements have proven evidence behind them. The matrix becomes the project’s memory.#
An interface message I inherited carried several fields that a scheduling change had quietly made meaningless. They were awkward to carry under the new design and, as far as anyone could tell, nobody on the other end read them. Removing them was about twenty minutes of work. The reason they stayed was that nobody could say for certain who consumed them, and the only way to find out was to ask the customer directly, which I did. Every one of those fields was a design element with no requirement above it. The matrix, had there been one, would have said so in a glance.
The lesson. Traceability is cheapest when it answers a question before anyone has to ask it in a meeting. A field with no parent costs twenty minutes to delete and a month of meetings to be sure about.
For small projects, a spreadsheet is fine. As complexity grows, dedicated tools earn their keep by making queries fast and keeping links current. The discipline is making and maintaining the links. The tool makes the discipline cheaper to sustain.
Link every requirement to its source, its design element, and its test, and the matrix answers in minutes what a change costs.
Requirements come in several shapes. Different kinds answer different questions, and a complete specification names them deliberately rather than mixing them into one undifferentiated list. The names matter less than the discipline of recognizing each kind when you write it.
Functional
What the system does: the actions, transformations, and behaviors in scope. “Decode AIS messages.” “Trigger alarm on detection.” “Log events to non-volatile storage.”
Performance
How well it does it: speed, capacity, throughput, accuracy, with numbers. “Process 100 messages per second.” “Latency under 10 ms.” “Position accuracy within 5 m.”
Interface
How it talks to other systems: protocols, formats, signaling, timing at the boundary. “Send NMEA-0183 over RS-232 at 4800 baud.” “Accept TCP connections on port 8080.”
Environmental
Conditions it must survive: temperature, vibration, humidity, EMI, radiation, with numbers. “Operate from -40 C to +85 C.” “Withstand 10 g vibration.”
Safety
What harm it shall never cause and how it shall fail: hazard mitigation and failure-mode behavior. “Fail to safe state on power loss.” “Provide manual override.”
Quality attributes
Cross-cutting properties, reliability, maintainability, security, usability, quantified to be testable. “MTBF above 10,000 hours.” “Mean time to repair under 30 minutes.”
Naming the type forces clarity. A requirement labeled “functional” that says “the system shall be reliable” is misclassified: reliability is a quality attribute, and the requirement is unverifiable as written. The type tag pushes back on vague requirements at the moment they are written, which is much cheaper than catching them at acceptance.
Tag every requirement with its kind; the tag exposes the vague ones while they are still cheap to fix.
The same handful of mistakes show up across most projects, and each has a recognizable signature once you know to look for it.
Confusing requirements with design.
Weak: “Use AES-256 encryption.” Strong: “Protect data per NSA Type 1 standards.” The first sentence locks the implementation. The second states the actual need and lets the designer choose the means. Requirements specify what and how well; the design specifies how. This is principle 1.4 at work.
Missing error cases.
Weak: “Display sensor reading.” Strong: “Display sensor reading. Show INVALID when the sensor is offline. Show OUT OF RANGE when the value exceeds limits.” Real systems spend most of their lives off the happy path. The error case is part of the requirement.
Untestable requirements.
Weak: “System should be user-friendly.” Strong: “90% of users SHALL complete task X in under 30 seconds without training.” If you cannot construct an objective test, the requirement is a wish.
Scope creep via adjectives.
Weak: “Robust, scalable, flexible system architecture.” Each adjective is a hidden requirement with no acceptance criteria, no priority, and no budget. They sound good in slides and become argument fuel at acceptance. Strip them, or turn each one into a number.
Design in the requirement, happy path only, adjectives instead of numbers: the four mistakes to read for before anyone signs.
3.8Case study: from the summary to a requirement set#
The sentinel’s project summary is a page of promises written in plain English, which is exactly what it should be. Turning those promises into a requirement set is the work of this chapter, and the moves are the same every time: find the subject, find the quantity, find the condition, name the method. Three of the promises get the full treatment below; the rest follow in a table.
Subject. The whole system, end to end: a chainsaw starts near a node, and an alert reaches the post. Any narrower subject would let a slow link hide behind a fast detector.
Quantity. “Minutes” is a feeling, so ask the customer for the number behind it. The answer was “over ten and we cannot get there in time,” so the requirement takes five and keeps the difference as margin.
Condition. Measured from what, to what, and how often does it have to hold? From the onset of the sound to the alert on the base-station screen. A hard 100% is untestable and a mesh will drop the occasional packet, so the requirement claims 95% of events and the test counts them.
Method. There is a number and it can be measured, so Test: a calibrated chainsaw recording played at a node at a logged time, and a timestamp on the alert.
SR-001, alert latency (Test)
The system SHALL deliver an alert to the base station within 5 minutes of the onset of a detectable event, for at least 95% of events, measured from the start of a calibrated chainsaw playback at any deployed node to receipt of the alert at the base station.
“It runs for a season on a battery”
Subject. One node.
Quantity. A season is 180 days, on one battery, with no visit in between.
Condition. Temperature moves a lithium cell’s capacity, so the requirement names the preserve’s range rather than leaving the test to a warm lab.
Method. A direct test takes 180 days, which is longer than the research phase. So the method is Analysis, the power budget, resting on measured average current from a 72-hour bench run, with a full-season field trial as validation later.
SR-002, node endurance (Analysis, with measured inputs)
A node SHALL operate continuously for 180 days on one battery at ambient temperatures from 10 C to 35 C with no maintenance visit, as shown by a power budget whose average-current inputs are measured over a 72-hour run of the deployed firmware.
“It keeps you from chasing phantom chainsaws”
Subject. The system, per node, because a false alert from any node sends someone driving.
Quantity. Ask what rate the rangers would tolerate before they stopped trusting it. “More than one a week and we would ignore it.” One per node per week, then.
Condition. Over a long enough window that a quiet week is proof rather than luck: 30 days, with the preserve confirmed free of logging activity.
Method. Test, with field data: count alerts, confirm each against the log.
SR-003, false alerts (Test)
The system SHALL raise no more than 1 false alert per node per 7 days, measured over a 30-day field trial during which no logging activity occurs within detection range of any node.
Every row traces upward to a sentence in the summary. That is decomposition arriving for free: the plain-English page was the Level 1 statement all along, and the requirements are its children.
ID
Requirement
Parent in the summary
Method
SR-001
Alert at the base station within 5 minutes of event onset, 95% of events.
“You learn about it within minutes.”
Test
SR-002
A node operates 180 days on one battery, 10 C to 35 C, no maintenance.
“It runs for a season on a battery.”
Analysis
SR-003
At most 1 false alert per node per 7 days over a 30-day trial.
“Keeps you from chasing phantom chainsaws.”
Test
SR-004
With three or more nodes detecting one event, the reported location is within 300 m of the true location, 90% of events.
“Several hearing the same event narrow it to a spot worth driving to.”
Test
SR-005
Node bill-of-materials cost under $40 at a quantity of 100.
“Cheap enough to leave or collect at the end.”
Analysis
SR-006
One person installs a node with hand tools in under 10 minutes, including logging its position.
“Fixed to a tree, switched on and logged at its location once.”
Demonstration
SR-007
An alert from any node reaches the gateway across up to 4 relay hops.
“Nodes pass the tiny alert from one to the next.”
Test
SR-008
A chainsaw operating 300 m from a node is detected within 60 seconds, 90% of trials.
“Scatter enough of them to cover the ways a crew would get in.”
Test
IR-001
Node-to-gateway alert messages conform to the alert message definition in the interface control document.
“The gateway forwards it to your station.”
Inspection
What became visible. SR-008 sets the node spacing, which sets the node count, which drives the budget line the customer cares most about: it was hiding inside “scatter enough of them.” SR-002 and SR-005 pull against each other, since a bigger battery is the easy way to meet one and the sure way to miss the other, and the power budget in Fundamentals is the analysis that will settle it. None of this tension was invented by writing it down. It was always there. Writing it down is what lets the team see it before the field does.#
Each plain-English promise in the summary became a numbered requirement with a method, and the tensions between them showed up on paper instead of in the field.
Running a healthy requirements process comes down to a small number of habits practiced consistently. None of them are intellectually difficult; the difficulty is in keeping every one of them under schedule pressure.
Start with stakeholder needs: requirements come from real needs rather than imagined ones. The first question is always “who needs this and why.”
One requirement per statement: compound requirements hide complexity and complicate verification. Split them.
Number every requirement: persistent IDs (SR-001, IR-002) survive renumbering and let you reference requirements unambiguously across documents.
Name the verification method as you write: Inspection, Analysis, Demonstration, or Test. A requirement with no method is a requirement with no plan.
Maintain traceability continuously: the matrix is your memory. Update it as the design evolves rather than as a year-end exercise.
Review with stakeholders: get sign-off before development. Late discovery of a misunderstood requirement is the most expensive bug class there is.
Version control requirements: they will change, and you will need to know what they were when you made earlier commitments.
Distinguish needs from wants: separate “must have” from “should have” from “nice to have.” Treating everything as critical means nothing actually is.
Test the requirements before testing the system: can each one actually be verified with the approach you have? If the answer is no, fix the requirement now rather than at acceptance.
Requirements engineering looks tedious from the outside. It is the most leveraged work on a project. Hours invested here save weeks downstream, in misaligned teams, missed acceptance criteria, change-order disputes, and rework. The teams that take requirements seriously ship; the teams that skip it spend the second half of the project relitigating what they thought they agreed to at the start.
Find the vaguest sentence in your current spec, the one with an adjective doing the work of a number, and rewrite it with all four parts: subject, SHALL, quantity, condition.
Add a method column to your requirements list and fill it in. Every row that resists a method is a row to rewrite.
Pick one requirement and trace it both ways: up to the customer sentence it came from, down to the test that will prove it. If either end is missing, you have found this week’s work.
Number them, name the method, keep the matrix current, and get sign-off before the build: hours here are weeks later.
This chapter on one page
Each line is the sentence to remember from its section. The number takes you back to it.
3.1A requirement is a contract: testable, traceable, unambiguous, and the only written way to say no.
3.2Subject, SHALL, quantity, condition: write all four, every time, and the adjectives take care of themselves.
3.3Inspection, Analysis, Demonstration, or Test: pick one as you write, and a requirement that resists all four is a requirement to rewrite.
3.4Decompose until each leaf is something one team can test, and insist that every leaf point up to a parent.
3.5Link every requirement to its source, its design element, and its test, and the matrix answers in minutes what a change costs.
3.6Tag every requirement with its kind; the tag exposes the vague ones while they are still cheap to fix.
3.7Design in the requirement, happy path only, adjectives instead of numbers: the four mistakes to read for before anyone signs.
3.8Each plain-English promise in the summary became a numbered requirement with a method, and the tensions between them showed up on paper instead of in the field.
3.9Number them, name the method, keep the matrix current, and get sign-off before the build: hours here are weeks later.