feat(directives): scavenge sweep 2/5 (docs/reports/2026-05-11 + 2026-06-01): 2 directives

Lifted:
- profile_first_optimize_second: profile and measure the actual bottleneck
  before any architectural change (RAG init, not AI SDKs, was the bottleneck)
- surface_gaps_at_discovery_not_checkpoint: surface scope gaps and
  architectural deviations the moment they are discovered, not at a
  checkpoint (the 'all good!' footnote pattern is bad UX)
This commit is contained in:
ed
2026-07-04 01:05:07 -04:00
parent f130cc6813
commit a89d0cb30e
4 changed files with 20 additions and 0 deletions
@@ -0,0 +1,9 @@
# profile_first_optimize_second
## v1
**Why this iteration:** Lifted from `docs/reports/2026-05-11/ai_decoupling_revert_report.md` §"Lessons Learned". The agent decoupled the AI client SDK imports from the main GUI under the assumption that the heavy SDKs caused startup latency; profiling later showed RAG initialization was the actual 5+ second bottleneck. The decoupling work was reverted; the lazy RAG import fix landed instead. The principle generalizes: do not reach for an architectural change until profiling has named the specific bottleneck.
**Source:** `docs/reports/2026-05-11/ai_decoupling_revert_report.md:116-121`
---
**Lifted:** 2026-07-03 (scavenge sweep batch 2/5: docs/reports/2026-05-11 + 2026-06-01)
@@ -0,0 +1 @@
# Profile and measure the actual bottleneck before attempting any architectural change to address it