Proof · Engineering practice
How do I analyze the impact of a software change?
Change impact analysis identifies which behavior, dependencies and evidence may be affected by a change. Use recorded requirement relationships to guide the investigation, then check the actual code and boundaries. Reachability in a graph is a review candidate set, not a complete prediction of runtime effects.
A cache refactor can affect a retained persistence promise
Illustrative example: SYS-REQ-096 requires warm-cache persistence. Its implementation link points to pkg/cache/cache.go, its test checks restart recovery, and a design document describes the serialization format. A refactor changes the file while the requirement stays unchanged.
proof trace impact SYS-REQ-096 --format table
This command refreshes source-annotation trace state and traverses recorded relationships for the named requirement. Use its linked requirements, code, tests and documents as review inputs.
| Review candidate | Question |
|---|---|
| Cache implementation | Did locking, serialization or error handling change? |
| Restart test | Does it exercise persisted data written by the candidate? |
| Dependent startup requirement | Can consumers still read records after restart? |
| Design document | Does the described format and recovery behavior remain accurate? |
An unlinked consumer will not appear just because it exists. Search callers, configuration, deployment topology and historical failures where those could extend the impact. Record newly discovered relationships.
Separate a recorded link from a suspected dependency
For the cache refactor, keep a small investigation record before choosing the test set. This is a worked planning example; none of these rows is a new execution result.
| Reach category | What we know | Required follow-up |
|---|---|---|
| Mapped | SYS-REQ-096 links cache.go to the persistence promise and restart test. | Inspect the changed serialization path, then run a write/restart/read check. |
| Suspected | Startup code calls the cache reader, but its compatibility promise is not linked. | Inspect the caller and supported data versions; record the relationship if justified. |
| Unmapped | An operations script may also consume the persisted file. Its owner and expected format are unknown. | Find the consumer and owner. Keep this gap visible and use broader integration checks rather than claiming narrow impact. |
The mapped set is a starting point, not a safe exclusion list. When a consumer cannot be investigated, record the remaining uncertainty and who can decide whether the proposed scope is acceptable. A larger test run may help, but it cannot invent the missing contract.
Decide whether the agreement changed
proof workflow check --stage implement --only authored_delta_expected --verbose
For source-native projects, the authored delta expected check examines recorded ownership and implementation changes that need an authored impact decision. It is not a behavioral equivalence checker. Overlay-audit projects use different trace and evidence workflows.
If the refactor preserves the approved requirement and design intent, an authorized reviewer can record that conclusion with its rationale:
proof review impact SYS-REQ-096 --decision no-authored-change \
--reason "Reviewed cache refactor; persistence format and restart contract remain unchanged"
The command records a review; it does not prove the rationale. Current reviews bind requirement content and artifact fingerprints. For Go, authored-behavior fingerprinting avoids treating ordinary comments or formatting as behavior changes. A new externally visible format, default or error needs an authorized contract amendment, not a no-change stamp.
Select and run evidence after investigating reach
Graph traversal answers “what is linked?” Behavioral impact asks “what can change?” Test selection asks “which executions will cover it?” Keep those questions separate. The impact command alone neither computes a complete runtime call graph nor runs the required tests.
Proof also has an affected-test planning workflow; use its declared selection scope rather than assuming the impact table is itself a test plan. Include broader integration or full-suite checks when unlinked dependencies, shared state or configuration make narrow selection insufficient.
For the cache example, observe writing data, restarting the service and reading through the real consumer. A passing helper test alone does not establish persistence across restart. Retain the candidate revision and every open impact question.
Keep the decision current and enforce it deliberately
Recovered observations may reveal a missing requirement. Treat that as candidate intent and reconcile it with the persistent agreement. Do not downgrade the promise because the current patch cannot satisfy it.
An audit or workflow result only prevents merge when the provider requires it for the current candidate and bypass policy preserves the boundary. After code or relevant requirements change again, review affected fingerprints and rerun the evidence that no longer applies.
See maintaining traceability and reporting the impact and its evidence.
Follow one changed input through to an observation
A dependency path identifies what to investigate. The runnable retention example then executes the behavior: two retry cases fail after a configuration change. Its package keeps missing intent and per-requirement evidence visible. An impact diagram alone could not establish that result.