Context
The #700→#705 pattern cost ~6s per iOS relaunch for months: a safety revert (runner teardown on relaunch) that was correct when made, silently outlived the recovery machinery (readiness preflight + invalidate/restart) that removed its reason to exist. Nothing recorded "this teardown exists because stale runners hang replays; revisit when recovery lands." The perf PRs (#1010/#1011/#1021/#1024) now carry such comments at the decision sites, but that's convention by accident.
Expectation
A short section in CONTRIBUTING (or the relevant ADR): any deliberately slow/conservative choice (teardown-to-be-safe, retry-instead-of-cache, serialization) must carry an inline comment naming (1) the failure it prevents and (2) the condition under which it should be reconsidered. Optionally a grep-able marker (e.g. // CONSERVATIVE:) so periodic audits are one search. Acceptance: documented style + the 2-3 existing sites retrofitted as examples.
Context
The #700→#705 pattern cost ~6s per iOS relaunch for months: a safety revert (runner teardown on relaunch) that was correct when made, silently outlived the recovery machinery (readiness preflight + invalidate/restart) that removed its reason to exist. Nothing recorded "this teardown exists because stale runners hang replays; revisit when recovery lands." The perf PRs (#1010/#1011/#1021/#1024) now carry such comments at the decision sites, but that's convention by accident.
Expectation
A short section in CONTRIBUTING (or the relevant ADR): any deliberately slow/conservative choice (teardown-to-be-safe, retry-instead-of-cache, serialization) must carry an inline comment naming (1) the failure it prevents and (2) the condition under which it should be reconsidered. Optionally a grep-able marker (e.g.
// CONSERVATIVE:) so periodic audits are one search. Acceptance: documented style + the 2-3 existing sites retrofitted as examples.