Decision records and safe review handoff
What this concept is
A review handoff records the change's purpose, evidence, unresolved risks and acceptance decision. An ADR preserves why a consequential option was selected under stated constraints. A rollback plan explains how to recover behavior, not merely which commit to revert.
Why it matters here
Learners need to distinguish structural refactoring from a behavior correction. The tenant repair intentionally changes faulty behavior; calling the entire change a refactor hides its risk. Reverting to a known leaking version is not a safe recovery plan.
Concrete example
Consider two options for this fixed snapshot: an uncached tenant-filtered scan, or a cache keyed by (tenant,id). The uncached version is simpler; a cache retains results and needs copying and key discipline. Without performance measurements, caching is not required. Record the chosen option, constraints, rejected alternative, cost, and a trigger for reconsideration such as adding updates. A future update API invalidates the fixed-snapshot assumption and needs a new decision.
Common confusion / misconception
Reversibility has degrees. A public API change can be migrated at a cost, while even a private helper rename may have tooling consequences. Reverting source does not retract data already disclosed. An ADR is not approval from a reviewer who never saw it; a solo exercise must label simulated feedback honestly.
How to use it
Keep regression, behavior repair and optional cleanup understandable as separate steps. In the local teaching branch, a red regression commit is deliberately marked; released changes must meet the actual project's checks. Write a PR summary with problem, resulting behavior, test commands/results and limitations. Preserve superseded ADRs with links to their replacements. Choose approve, request changes or need more evidence, and state why.
Check yourself
What evidence is missing if the author says only “all tests pass”? Which safe fallback avoids returning to the faulty lookup? What event would make the fixed-snapshot ADR obsolete?
Mini drill or application
Write a short ADR comparing cache and no-cache designs. Give a recovery plan that preserves tenant filtering. Ask another learner to reproduce your packet; if working alone, perform a delayed clean-directory rerun and label it self-review.
Read this only if stuck
Use Michael Nygard's ADR explanation for decision history and Refactoring for separating behavior-preserving changes from bug fixes. No full-book reading is required.