Proof · Engineering practice
How do stakeholder, system and software requirements connect?
Requirements decomposition turns a stakeholder outcome into system behavior and then into obligations for specific software components. Each child should explain its contribution to the parent, including assumptions and boundary behavior. More requirement files alone do not establish a useful refinement.
One tenancy promise, three levels of evidence
Illustrative example: an administrator may manage only the tenant they are authorized to administer. A useful decomposition makes the system boundary and software responsibilities explicit.
| Level | Requirement | Evidence |
|---|---|---|
| Stakeholder | A tenant administrator cannot read or change another tenant’s records. | Acceptance scenarios with two tenants and real administrative operations. |
| System | Every administration request must bind the authenticated actor and target tenant before data access. | System tests for authorized, cross-tenant and missing-identity requests. |
| Software | The server rejects an actor/tenant mismatch; repository queries require the authorized tenant key. | Unit and integration checks for both components, including a rejected request that performs no write. |
Record which identity provider is trusted, which operations are in scope and what background jobs may do. A repository query test cannot alone establish the stakeholder outcome if another endpoint bypasses that repository.
Review what each child adds
For each parent, identify the observable outcome and the architecture that must deliver it. Allocate responsibilities, name the component interfaces, and check that the children cover failure paths as well as nominal behavior. Inspect both directions: every child needs a reason, and every parent obligation needs an accountable implementation and evidence path.
Children may reuse the same property while adding a narrower trigger, scope, bound or component responsibility. That can be legitimate refinement. A child that merely copies the parent into another folder gives the reviewer no new explanation.
Existing code, docs and tickets can supply candidate requirements. Resolve conflicts with retained approved intent under the applicable policy; decomposition does not authorize a weaker promise.
Scaffold children, then refine their content
proof req decompose SYS-REQ-010 --into software --component repo,server
proof req decompose SYS-REQ-010 --into software --component repo,server --write
proof audit --check spec_lint_decomposition_adds_refinement
These examples assume SYS-REQ-010, the software specification and the named components exist. The first command previews child scaffolds; --write saves them. The scaffolds carry parent links and draft content. They are not automatically a correct architectural decomposition.
The refinement lint uses lexical signals, including near-identical text with a configurable Jaccard threshold of 0.85 and no new output variable. It also recognizes legitimate changes in scope and allocation. It is a warning-level heuristic for review, not a proof that children imply their parent. Do not add dummy variables to silence it.
Verify the parts and the assembled outcome
Check link consistency, review the meaning of each refinement and run evidence at the appropriate level. An acceptance criterion still needs evidence of its user-visible outcome even when every child has a passing unit test. Contradictory assumptions or an omitted interface can defeat a complete-looking hierarchy.
Keep parent identities and approved revisions after the implementation task closes. A later agent can retrieve the tenancy promise and its earlier decisions rather than infer the rule again from one changed query.
Continue with checking requirement links and checking coverage across the declared requirement set.