Refactoring as Discovery: Stabilising Through Boundaries and Explicit Contracts

This week’s focus

This period was shaped by an extended refactor and stabilisation effort driven by persistent system inconsistencies. The primary constraint was lack of reliability across UI, orchestration, and persistence, leading to a focus on identifying root causes and restoring a stable baseline before resuming product evolution.

What actually happened

• A prolonged refactoring phase exposed instability across charts, UI behaviour, intelligence triggering, and goal computation
• Multiple sources of truth and tight coupling between UI and backend created inconsistent system behaviour
• Snapshot retrieval and fallback logic caused incorrect UI outputs, especially in multi-language scenarios
• Chart generation and rendering failed across historical data due to orchestration and context mismatches
• Persistence issues emerged around serialization, schema mismatch, and incorrect primary key usage
• Several fixes were implemented to ensure charts persisted, loaded, and rendered correctly across restarts
• PR and documentation were enhanced post-generation to reflect actual system behaviour and architectural decisions
• The system reached a “stable enough” state, prompting a decision to stop refactoring and resume the learning loop

Key trade-offs

• Deferred deeper architectural changes (e.g., snapshot unification, atomic persistence) to avoid further destabilisation
• Chose incremental fixes over full redesign of persistence and orchestration layers
• Avoided merging snapshot models due to high risk despite structural misalignment
• Accepted temporary partial-state inconsistencies in favour of maintaining delivery momentum
• Prioritised restoring system usability over achieving architectural completeness

What changed in my thinking

• Stability requires not only fixing structure but constraining how future changes are produced.
• Instability was not caused by isolated bugs but by implicit contracts across system layers
• Single source of truth is a prerequisite for predictable system behaviour
• Orchestration must own execution flow; UI-triggered behaviour introduces hidden coupling
• Deterministic components provide reliability where LLM-driven behaviour introduces variability
• Serialization and data boundaries are core architectural concerns, not implementation details
• Documentation can act as an active governance mechanism rather than passive reference

Architecture signals

• Architecture must be enforced at build-time via agent constraints, not only validated post-build
• Implicit contracts between layers are a primary source of system instability
• Single source of truth is a foundational constraint for reliability
• Execution ownership must be explicit and centralised (e.g., orchestration layer)
• Deterministic execution should replace LLM delegation for core system behaviour
• Persistence models should be identity-driven when supporting multiple dimensions
• Serialization defines system boundaries and interoperability contracts

Key takeaways

• Preventing structural drift requires build-time guardrails, not only post-hoc validation
• Make system boundaries explicit early to prevent cascading instability
• Eliminate multiple sources of truth before scaling system complexity
• Assign clear ownership of execution to avoid implicit behaviour
• Prefer deterministic implementations for core system responsibilities
• Use documentation as a validation tool, not just a record

Assumptions invalidated

• Once stabilised, the system structure will be naturally preserved during future iterations
• UI can safely trigger backend intelligence generation
• week-based keys are sufficient for persistence in multi-dimensional systems
• LLM-driven components are adequate for core system functionality
• fallback logic is harmless in retrieval paths
• serialization is a low-level concern rather than an architectural one

System evolution

• Transition from implicit, loosely defined interactions to explicitly bounded architecture
• Shift from LLM-centric execution to deterministic core with selective augmentation
• Adoption of a learning-driven operating model (use → learn → evolve)

Looking ahead

Focus shifts to resuming the weekly learning loop and advancing the interaction layer (e.g., notifications, conversational interfaces). Architectural improvements remain identified but deferred, with emphasis on validating the system through real usage before further refactoring.

---

• Architecture signals & invalidated assumptions

Note: This Weekly Learning was produced using the Ideas to Life Weekly Learning system. See: Weekly Learning system map