From the first commit in October 2024 to V6.0.2 in September 2026: six phases of evolution, five classes of recurring problems, the methods that proved themselves, the evolution of verification, and a look forward. Every claim is written from git history and version records β no recollection, no polish, only evidence.
This repo (UHRR_mac, from 2026-03-06): 206 commits. Parent project UHRR (from 2024-10): ~208 commits. 400+ commits and 35 versions combined.
Mar 48 / Apr 4 / May 35 / Jun 32 / Jul 1 / Aug 55 (the most intense month) / Sep 31. The quiet months were "usage-driven" β the product ran in real QSOs while problems accumulated.
2026-08-09: five versions in one day (V5.7.1 β V5.8.2) β RagChew fixes, ATR SWR guard, IOLoop de-blocking, thread-misplacement fix. A concentrated overhaul burst.
Raspberry Pi/Linux (parent) β macOS (this repo's origin, 2026-03) β Windows installer (V6.0.0, 2026-09). One codebase, three platforms.
Every phase is written directly from the commit chain.
Each has a full "fixed repeatedly until truly solved" story.
| Date | Battle | What Was Fixed |
|---|---|---|
| 2026-03-06 | ba66892 / 1a072b3 | TX main-thread blocking, ATR broadcast thread safety |
| 2026-03-07 | d4a40c2 | New-architecture rollback (the cost of over-engineering) |
| 2026-08-09 | V5.8.1 / V5.8.2 | rigctld I/O into an executor (F3), pinned MAIN_IOLOOP |
| 2026-08-28 | F2 | stream.write() moved off the IOLoop |
| 2026-09-14 | RC-001 F4/F4b | Constructor p.open() β the last blocking call standing |
RNNoise β WDSP β EMNR Gaussian rewrite (digital artifacts) β sample-rate wars (watery sound) β NR2 SSB voice protection (voice suppression, C patch). From "sounds wrong" to four testable assertions: voiceΞ / noiseΞ / LSD / jitter.
ATR-1000 SYNC throttling, anti-disconnect, learning pollution, SWR guard, plus the Bluetooth DAC β the pattern is always the same: proxy isolation + cached answers + pressure control + anomaly observability. Assume every protocol peer can stall.
PTT Safety Monitor (release-failure retry + TOT hard cap), 5-second no-frame auto-release, direction-aware state machine (R3), SWR>2 auto-retune guard, RC-001 forced release on the discard path. Software state can lie to you; the radio cannot β the verdict ultimately sinks to physical quantities.
RC-001 pinned the root cause outside the system for the first time: a generic Bluetooth firmware never acknowledging the jitter-buffer config (error 312) β CoreAudio stalls globally β unrelated USB sound card dragged down. Probes moved into the system layer accordingly (unified log / bluetoothd / power-meter A/B).
Every entry carries commit or document evidence β and we honestly list what did not prove itself.
| Practice | Evidence | Verdict |
|---|---|---|
| spec β design β plan β tasks chain | 08-28 recording four-commit chain, 09-13 NR2 tasks 1β6 | β zero rework on complex changes |
| Red-green acceptance (failing baseline first) | 3dc6319 "all baselines fail" β tasks pass one by one | β the only reliable path for "feels-like" quality |
| Metricized audio evaluation (A/B + Latin square + four metrics) | 09-13 full NR2 acceptance | β ears drift, metrics don't |
| Postmortem culture | PTT_Audio_Postmortem β RC-001 numbered case series | β incidents become assets |
| Revert discipline | d4a40c2, dab904a β two decisive rollbacks | β if the new is worse, go back |
| Feature pruning | V5.7 removed FT8/CW; everything got more stable | β feature entropy is negatively correlated with reliability |
| CHANGELOG + tag discipline | 35 versions, all recorded | β the data foundation of this very retrospective |
| Data as truth | ATR power meter judged modulation when every software layer looked "fine" | β physical quantities pierce log illusions |
| Code-first docs + audit | docs/current/ + cross-check audit | β docs that don't rot |
| Big-bang architecture rewrites | Rolled back twice (AudioWorklet/Worker, buffer strategy) | β not proven |
| "Optimization" without acceptance criteria | Multiple audio regressions caught by the user's ears | β not proven |
The direction never changed: closer to physical truth, further from guessing.
Manual trial and error (early parent project) β fix whatever breaks.
Logs + power-meter observation (V4.5 ATR saga) β first time device readings were cross-checked against software behavior.
spec/plan + manual acceptance (V5.x) β complex changes started carrying a document chain.
Red-green tests + four metrics + A/B listening (V6.0.1) β felt quality became test assertions.
Runtime telemetry (V6.0.2) β IOLoop watchdog / β±οΈ timing probes / .prev death-scene log rotation.
Environmental A/B isolation (V6.0.2) β Bluetooth DAC disconnected as control: 11 transmissions, all properly modulated.
Each one was bought with a real incident or regression.
Fixing points instead of the surface lets the problem return wearing a new face. Thread blocking was fixed five times before it became a discipline. For recurring problem classes: enumerate every possible site, make a rule, install a probe β don't wait for the next incident.
Async moves bugs; it doesn't kill them. Every time you move a blocking call off a critical thread, first answer "where do the data and events go while it blocks?"
An environment problem is not a code problem. Before touching code, extend observability to the system boundary (OS logs, hardware readings). The ATR power meter and bluetoothd logs located the truth faster than any Python log.
Physical quantities are the ultimate assertion. Every software layer can "look fine"; transmit power cannot lie. When you suspect the software chain, find a hardware reading to cross-check first.
One human + AI works β but discipline cannot be skipped. AI accelerates execution, not judgment; AI acceleration without discipline just pays down debt faster into a wall.
Subtraction is an architectural skill. Removing FT8/CW, two rollbacks, menu slimming β every cut raised reliability or usability. Projects that dare to delete features get long-term room to evolve.
Documentation compounds. A 35-version CHANGELOG, a case library, and code-first docs let this retrospective be written entirely from data β no recollection, no polish, only evidence in git.
Sources for this retrospective: git log, CHANGELOG.md (35 versions), the RC-001 reliability case, the FDE practice guide, and the Aladdin V2 methodology β all open on GitHub.