Commit 866ea760 authored by Vacaliuc, Bogdan's avatar Vacaliuc, Bogdan
Browse files

README, 00: index new docs 11 and 12



- README: add 11 and 12 to the reading map.
- README one-slide version: summarize the technical-debt surface
  (17 categories, tiered by cost/payoff) and the parameter-
  propagation pipeline (4 deepcopy layers, Qt signal timing drives
  everything, no Qt types in back-end, two _as_ints bug).
- 00: add bullets 7 (technical debt surface, tiered) and 8
  (parameter propagation, 4-deepcopy chain, git archaeology of
  fixes).

Co-Authored-By: default avatarClaude Opus 4.7 (1M context) <noreply@anthropic.com>
parent 01ed1737
Loading
Loading
Loading
Loading
+21 −0
Original line number Diff line number Diff line
@@ -130,6 +130,27 @@ decision matrix.
   import wins.  The bodies are near-identical so nothing has broken
   yet, but it is accidental, not principled.  Pick one, delete the
   others.
7. **Technical-debt surface is large but triageable.** A 17-category
   enumeration in [11-technical-debt.md](11-technical-debt.md) groups
   concrete items by cost-to-fix and payoff.  Tier-1 items (the two
   `_as_ints`, the three-copy QuickNXS scaling, stale `peak_finding.py`,
   dead algorithm registration) total ~1 day of work and remove several
   silent numerical discrepancies.  Tier-2 items (unified MRR
   parameter-construction, type drift fixes, equivalence test harness)
   are the 1-2-day hackathon-scale deliverables.  Tier-3 items
   (Configuration refactor, DataInfo consolidation, Qt-threading)
   are post-hackathon follow-ups.
8. **The parameter-propagation pipeline is a 4-deepcopy chain.**
   [12-parameter-propagation-and-qt-leakage.md](12-parameter-propagation-and-qt-leakage.md)
   walks every Qt widget → Configuration → CrossSectionData → MRR
   step, shows that no Qt types leak into back-end code, but that
   `Configuration` class-attribute mutable globals and Qt-signal
   timing are the actual source of reported "configuration
   propagation" defects.  Git archaeology documents the pattern's
   history: commits `aa32022` (introduce deepcopy), `dd7a400` (update
   tests), `21d4d91` (SEGV fix from Qt signal lifetime), `a2d16a8`
   (replot on global config change), `44d829d` (active-run sync), all
   address symptoms of the same class-attribute-as-global pattern.

## Out-of-scope insights worth noting

+20 −0
Original line number Diff line number Diff line
@@ -27,6 +27,8 @@ trusting `docs/developer/` in either upstream repo — both are skeletal
| See what the hackathon must decide, and known unknowns | [08-risks-and-open-questions.md](08-risks-and-open-questions.md) |
| Look up a term / acronym / file name | [09-glossary-and-pointers.md](09-glossary-and-pointers.md) |
| Open the `MagnetismReflectometryReduction` black box — PyExec flow, inner Mantid primitives, the four silent default-value disagreements between consumers | [10-mantid-algorithms-deep-dive.md](10-mantid-algorithms-deep-dive.md) |
| See the full technical-debt inventory (duplication, dead code, magic numbers, type drift, global state, Qt lifecycle, doc gaps, version pins, test debt, deployment) | [11-technical-debt.md](11-technical-debt.md) |
| Trace a parameter from Qt widget through Configuration to the MRR call, audit where Qt lifecycle leaks into back-end flow, read the git archaeology of parameter-propagation fixes | [12-parameter-propagation-and-qt-leakage.md](12-parameter-propagation-and-qt-leakage.md) |

## One-slide version

@@ -55,6 +57,24 @@ trusting `docs/developer/` in either upstream repo — both are skeletal
  `RoundUpPixel`, `AcceptNullReflectivity`) plus `UseSANGLE` and a
  post-hoc QuickNXS scaling.  Full treatment in
  [10-mantid-algorithms-deep-dive.md](10-mantid-algorithms-deep-dive.md).
- The **technical-debt surface** is enumerated in
  [11-technical-debt.md](11-technical-debt.md) across 17 categories —
  duplicated code (including 3-way `SingleReadoutDeadTimeCorrection`,
  3-way `DataInfo`, 3-way QuickNXS scale formula), dead code,
  hardcoded constants (`QStep=-0.01` in one path, slit-distance
  fallbacks), load-bearing defaults, type drift (`BinningType` vs
  int), Configuration class-attribute mutable globals, Qt widget
  lifecycle coupling (SEGVs fixed 2026-03-21), three-way algorithm
  registration races, and documentation gaps.
- The **parameter-propagation pipeline** is 4 deepcopy layers deep
  ([12](12-parameter-propagation-and-qt-leakage.md)): Qt widget →
  UI handler → Configuration → DataManager → per-CrossSection
  deepcopy → MRR.  No Qt *types* leak into the back-end, but Qt
  *lifecycle* and *signal timing* drive the whole chain, and class
  attributes on Configuration bypass the deepcopy isolation.  Two
  local `_as_ints` in `data_set.py` produce a reproducible
  off-by-one in pixel ranges between two call sites — a concrete
  example of the debt.

## PDF of this knowledge base