A branch in the code is a clue
Suppose an export endpoint returns deleted records when an old client omits a filter. An agent reading that branch could write “exports shall include deleted records by default.” It would accurately describe the implementation while preserving a privacy defect.
Illustrative recovery worksheet. The endpoint, documents and decisions below are invented to show the procedure. Read across the sources before choosing the requirement.
| Source | What it says or shows | How to treat it |
|---|---|---|
| Export handler, revision A | Missing filter includes active and deleted rows. | Observed behavior; no evidence of authority. |
| Existing unit test | Default export expects both rows. | A check of the current implementation, not approval of the behavior. |
| Published API contract v2 | Standard exports contain active records only. | Candidate authority; confirm applicability and owner. |
| Archived migration note | Include deleted rows during a one-off reconciliation. | A scoped exception that may explain the branch. |
| Retained requirement SW-REQ-312 | Deleted records are excluded from customer exports. | Existing obligation to preserve unless an amendment is authorized. |
The conflict is now specific: the standard endpoint implements a historical exception more broadly than its source permits. More code inspection can explain how that happened. It cannot decide whether customers should receive deleted records.
Resolve the conflict without erasing its history
Candidate: standard export excludes deleted records.
Sources: API contract v2; SW-REQ-312 revision 3.
Contradiction: handler at revision A and its default-export test.
Decision: API owner confirms the existing exclusion requirement.
Treatment: fix the handler; revise the conflicting test.
Preserve: active records remain exportable with the same field format.
Exception: reconciliation export requires a separate authorized route.
Open question: are any supported clients relying on the old default?
Owner of compatibility investigation: export maintainer.
Status: intent confirmed; rollout decision pending.Sometimes the owner will choose the opposite outcome: amend an outdated promise because legitimate clients depend on the behavior. Retain that amendment and its authority. Do not silently overwrite the old requirement or treat the newest ticket as approval.
Recover one neighborhood at a time
- Pick a behavior with a consumer. Begin with an endpoint, state transition or business rule. Identify who depends on it.
- Collect sources with revisions. Read the code, tests, interface contract, relevant issues and existing approved requirements. Keep direct references rather than an unattributed summary.
- Write candidates and confidence separately. State the trigger, outcome and scope. Mark inferred intent and unresolved authority clearly.
- Reconcile at the right level. Connect the user outcome to system behavior and the software responsibility. A copied sentence at every level does not explain how the parts deliver the promise.
- Ask the owner the consequential question. In this example: should a standard export ever return deleted records, and which clients may be affected by correcting it?
- Attach checks to the approved result. Exercise active, deleted and mixed records. Check actual exported contents and preserve legitimate behavior.
What to retain in Proof
Proof supports requirements with rationale, parent relationships and trace links, alongside Change records that retain intent, context and open questions. An agent can help investigate sources and draft this material; approval and amendments follow the project's configured authority.
Recovery is a reviewed workflow. A proposed requirement inferred from code is not automatically a product promise. Nor does a complete trace graph establish that all important requirements were discovered.
For the export change, keep the conflicting source, decision, implementation link, corrected test and unresolved client question together. The next agent should be able to learn why that apparently unnecessary filter exists.