Neither is automatically wrong. The code shows what the system currently does; an approved, current requirement or product decision is the evidence of what it is meant to do. Find that intended behavior first, then determine whether the code, the design document, or the underlying requirement has diverged.
Start with the intended behavior, not the artifact that looks more convincing
A running implementation does not prove that its behavior is correct. A design document does not prove that its description is current, approved, or clear. The deciding question is: what outcome was authorized to meet the user or stakeholder need?
Trace the disputed behavior to the strongest applicable evidence: a validated requirement, acceptance criterion, approved product or system decision, or external specification. Check who approved it, which version applies, when it took effect, and why it was chosen. NASA’s software engineering requirements require projects to identify inconsistencies between requirements, plans, and software products and initiate corrective action; they also call for validating requirements against customer needs. NASA’s requirements document is agency guidance, so check whether it applies to your project rather than treating it as a universal mandate: NASA NPR 7150.2.
Work out what kind of mismatch you have
Describe the discrepancy in observable terms: the affected workflow, interface or configuration, the behavior you expected, the behavior you observed, and the versions involved. Then classify how the artifacts came apart.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →#1 Best Overall
- Implementation drift: The approved requirement has not changed, but the code no longer meets it.
- Documentation drift: An approved behavior changed, but the design document still describes the old one.
- Unpropagated change: A requirement changed, but the design, code, tests or user documentation did not all follow.
- Conflicting requirements: Two approved statements prescribe incompatible outcomes; the conflict needs an authorized decision.
- Ambiguity: The requirement admits multiple reasonable interpretations, and the team has implemented one without establishing that it was intended.
NASA’s software design and traceability guidance treats both missing implementation of design elements and code without a parent design element as findings to investigate—not automatic proof of which artifact is right.
Use traceability to test both directions
Follow the chain from need to requirement, design, code and tests. A requirement with no implementation may indicate omitted work; code with no linked requirement or design rationale may be accidental, obsolete, or a justified implementation detail whose documentation is missing. Either way, the gap merits investigation.
Rank #2
Traceability works best in both directions: from an approved requirement to the implementation and from code back to the reason it exists. NASA requires projects to provide and maintain traceability from software design to code. Its handbook explains how links can reveal missing implementation or unexplained code, while warning that those links do not update themselves when artifacts change. See the NASA Software Engineering Handbook guidance.
Decide whether to change the code, document or requirement
Bring the discrepancy and its evidence to the responsible product or system owner, and involve affected stakeholders when the intended outcome is uncertain. Requirements should connect to evidence and rationale; the UK Home Office’s Design from evidence guidance emphasizes that connection, while NASA calls for validating requirements against customer needs.
Rank #3
- If intent is clear and current: Correct whichever artifact diverges, and update dependent materials.
- If the intended behavior has changed: Approve the requirement or design change, assess its effects, and then update implementation and verification materials.
- If intent remains unclear: Record an open decision with an owner. Do not silently make one interpretation authoritative by changing the code or document first.
Ambiguity can affect what implementers are required to build, not merely how a sentence is edited. The W3C Process provides a formal standards example of resolving ambiguity through a process that can affect implementation requirements.
Update the chain and verify the approved result
Once the decision is made, update the affected requirement, design, code, tests, release notes and user-facing documentation as applicable. Preserve the decision and its rationale so a future maintainer can distinguish a deliberate change from drift.
- Link the approved requirement or decision to the design element and implementation it governs.
- Update automated or manual tests to check the approved behavior.
- Run the relevant tests and record results against the applicable versions.
- Check that code and documentation still agree after the change, and repair traceability links that changed with them.
Tests provide evidence that requirements have been met; they do not decide whether the requirement itself reflects the right need. NASA describes testing as verification against requirements and design, and calls for implementation verification. The Home Office guidance makes the evidence role explicit: tests show whether requirements have been met, not whether the requirement was the right one in the first place.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Keep documentation useful as the system evolves
Design documents are valuable when they explain intended behavior and remain connected to the system. The UK National Cyber Security Centre advises maintaining simple supplementary material alongside an evolving system: Produce clean and maintainable code. Where a machine-readable specification fits the project, it may also support automated correctness checks.
Recommended Free Tools
Best Value
For teams establishing a formal requirements-engineering approach, ISO/IEC/IEEE 29148:2018 is the second edition of a standard covering requirements engineering. Its applicability depends on the project; it does not impose one universal hierarchy for every team’s artifacts.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
