Requirements to Code

On a safety-critical vehicle you cannot merely write software that works — you must be able to demonstrate, mechanically and repeatably, that every line exists because something asked for it and that something tests it. This page is a complete worked tutorial of the two-tier requirement scheme that makes that possible: HLSR (high-level software requirements) describing what the software must do, LLSR (low-level software requirements) describing how a specific function does it, the annotations that bind LLSRs to code, the tests that discharge them, and the pipeline scripts that fail the build when any link in that chain is broken.

Worked throughout on an invented example — a free-inertial drift monitor for a generic launch vehicle. Everything here is a pattern, not a product: identifiers, wording and directory names are chosen to be copied into a new repository. Related reading: Rocket navigation for the system this kind of monitor lives inside, and the drift test for the physics the example requirements describe.

1 · Why two tiers at all

The instinct is to write one list of requirements. That fails for a reason worth understanding, because it explains every design choice that follows.

Requirements serve two audiences who need incompatible things. A systems engineer, a customer or a regulator needs statements about observable vehicle behaviour, stable across redesigns, reviewable without reading code: "the vehicle shall detect a degraded inertial sensor before committing to flight." A developer needs statements precise enough to implement and test a single function: "this function shall return FAULT when the computed radial error rate exceeds the configured threshold." Force those into one document and you get either requirements too vague to test or a "requirements" document that is really source code in prose, and which must change every time you refactor.

The split pays for itself the first time you refactor. Splitting one function into three changes three LLSRs and touches no HLSR, no customer document, and no certification argument — because the observable behaviour did not change. That containment is the entire point.

2 · The chain, end to end

Six artefacts, each with exactly one job. Read this diagram first; the rest of the page is one section per arrow.

3 · The example we will build

A small, self-contained capability with enough structure to exercise every part of the scheme: a monitor that decides whether the inertial sensor is healthy enough to fly on, by comparing the vehicle's own free-inertial solution against a surveyed truth while it sits on the pad.

The layout — worth copying verbatim into a new repository, because the scripts assume it:

4 · Step 1 — write the HLSRs

An HLSR is a structured record, not a sentence. The prose matters, but so do the fields around it: they are what make the requirement reviewable, traceable and verifiable.

4.1 Start from the operational need

Begin with what somebody actually wants, in their words. For our example, three statements from a concept-of-operations review:

None of these is testable yet. "Degraded" is undefined, "early enough" is not a number, and "silently" is a judgement. Turning them into requirements is the systems engineering work.

4.2 Write them in the mandated form

Use one sentence pattern and never deviate, because tooling and reviewers both rely on it:

Applying the pattern to N1–N3 gives three HLSRs:

4.3 What each field is for

4.4 Six tests for a bad requirement

5 · Step 2 — decompose into LLSRs

Now the developer's turn. The HLSR says the software must declare a fault within 2 s; the LLSRs say which function does what, branch by branch.

5.1 The identifier scheme

Every LLSR has a structured id. Structure is what lets a script check it, so the format is rigid:

5.2 Declare them in the header

LLSRs go immediately above the declaration, in the header, where every reviewer of the function will see them. @post states what is true after the call — a postcondition, which is exactly what a requirement about behaviour is.

5.3 Implement, marking the paths

The implementation carries a short comment naming the LLSR each branch discharges. This is the line a reviewer checks against the header, and the one that makes a stale annotation obvious.

Note the ordering constraint in the first guard, and that it is load-bearing: if the latch check came first a NaN would be evaluated against the limit, and NaN > limit is false, so a broken sensor would read HEALTHY. That is precisely the kind of detail an LLSR should capture — it is behaviour, not style, and the test below exists to keep it true.

6 · Step 3 — generate the trace

The trace is a flat CSV linking every LLSR to the HLSR it serves. It is generated from the annotations; hand-editing it is how traces rot.

The third row is the interesting one. The input guard is derived: true — no requirement asked for a NaN check — but it still traces to 4001, because its reason for existing is to keep 4001 honest. That is the pattern for defensive code: derived, but not orphaned.

7 · Step 4 — verify, and say what you verified

A test that exercises a requirement but does not say so is invisible to the process. One macro call fixes that: it records, at runtime, that this test claims coverage of that LLSR.

Two conventions that keep coverage honest as the code grows:

• Several LLSRs per test is fine when one scenario genuinely exercises them together — call VERIFIES once per LLSR. Prefer separate tests when the failures would be distinct.
• Verified-by-parent needs recording. When a caller's test necessarily exercises a callee's LLSR, say so in a comment block listing those ids, so the coverage script can credit them rather than reporting a gap that is not real.

8 · Step 5 — make CI enforce all of it

Everything above is a convention, and conventions decay unless something mechanical objects. Four scripts, each answering one question, each able to fail the pipeline.

The --fail-under 100 deserves a comment, because it looks unreasonable and is not. Statement coverage of 100% is often impractical; requirement coverage of 100% is simply the statement that every behaviour you claimed to implement has at least one test naming it. If an LLSR genuinely cannot be unit-tested, the answer is an explicit, reviewed exception with a recorded justification — not a lower threshold that quietly permits any gap.

9 · Bootstrapping a new repository

The order matters: each step makes the next one enforceable. Do them in this sequence and the process holds itself up.

10 · Where this goes wrong

A pattern connects all six: each is a local shortcut whose cost lands on somebody else, later — usually during verification, when schedule pressure is highest and options are fewest. That is exactly why these checks belong in CI rather than in a style guide. A style guide asks; a pipeline declines.

11 · Further reading

• DO-178C, Software Considerations in Airborne Systems and Equipment Certification, RTCA. §5 defines the high-level/low-level split this page describes and §6 the verification objectives; the traceability tables of Annex A are what the CI scripts are ultimately producing evidence for.
• DO-331, model-based supplement — relevant if requirements or design are captured as models rather than text.
• NASA-STD-8739.8, Software Assurance and Software Safety Standard — a readable treatment of bidirectional traceability and why derived requirements get extra scrutiny.
• ISO 26262-6 (automotive) and IEC 61508-3 (industrial) — the same two-tier structure under different names, useful for seeing which parts are essential rather than domain convention.
• INCOSE Guide for Writing Requirements — the sentence patterns and quality rules of §4.2 and §4.4, with far more examples.

Related pages: Rocket navigation — the architecture a monitor like this sits inside · Ground alignment & the drift test — deriving the threshold the example requirements refer to · NASA nav-filter best practices — the engineering-standards view of estimator design.