docs(adr): add state management implementation plan (0008)

[Parship12]

Add ADR 0008 as the implementation / phased migration companion to ADR 0004

[Copilot]

Pull request overview

This PR is a comprehensive rewrite of ADR 0004 (State Management Strategy for Jaeger UI), transforming it from an extensive 1425-line evaluation document into a concise, action-oriented 220-line decision and implementation roadmap.

Changes:

• Status update: Changed from "Proposed" to "In progress" and dated 2026-04-04, reflecting active implementation work
• Document restructuring: Simplified the evaluation while preserving key decision rationale, removing detailed deep-dives (which are preserved in git history per line 56)
• Clear decision statement: Upfront commitment to Zustand + TanStack Query with explicit rejection table for Context and Redux-only approaches
• Phased migration plan: Organized into 4 phases (Foundations, UI State, Server State, Cleanup) with 16+ specific sub-tasks, tracking progress with checkmarks
• Enhanced cross-references: Stronger links to ADR 0005 and ADR 0002, acknowledging the interconnected nature of architecture decisions
• README.md update: Updated the ADR summary line to reflect the new structure and decision clarity

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
docs/adr/README.md	Updated ADR-0004 description to emphasize decision clarity and phased migration plan aligned with ADR 0005
docs/adr/0004-state-management-strategy.md	Complete strategic rewrite from evaluation-heavy to decision-and-action focused, with detailed phased migration roadmap

---

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.21%. Comparing base (01c7e88) to head (59ee5b8).
⚠️ Report is 8 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3704      +/-   ##
==========================================
+ Coverage   89.19%   89.21%   +0.01%     
==========================================
  Files         330      330              
  Lines        9894     9900       +6     
  Branches     2567     2570       +3     
==========================================
+ Hits         8825     8832       +7     
+ Misses        927      926       -1     
  Partials      142      142              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[yurishkuro]

the research part was valuable, you now just provide decisions / claims without backing. I suggest writing a new ADR that focuses on implementation plan and leaving this one alone as the motivation / reference.

[Parship12]

@yurishkuro ptal

[yurishkuro]

When I look at ADR-4 it has research / comparison / decision, and it has a high level migration strategy. But it does not have the final design (similar to ADR-5 with the current design).

Perhaps your ADR-8 should focus on being the representation of the current state which keeps morphing into future / desired state so that eventually it could serve as a claer architectural document of "this is how we do things". Meanwhile updates regadring migration steps should go back to ADR-4, since it already has that but the steps could be expanded with more details that you tried adding here.

[Parship12]

Perhaps your ADR-8 should focus on being the representation of the current state which keeps morphing into future / desired state so that eventually it could serve as a claer architectural document of "this is how we do things". Meanwhile updates regadring migration steps should go back to ADR-4, since it already has that but the steps could be expanded with more details that you tried adding here.

Ok, I will update it.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[yurishkuro]

Love the table! There's just one thing that gives me pause - why have a split brain situation between Zustand state and URL state? Is this a transient migration artifact or long term state? Why not consolidate everything in the URL state, which makes shared URLs much more descriptive / usable?

[Parship12]

let's imagine 2 types of things:

1. which span is my mouse hovering over right now? as we move our mouse across the trace timeline, this changes...say 60 times per second. If we try to save that in the URL, Will not the URL would be changing 60 times per second? browsers would crash.

2. Which of the 10,000 spans did I manually expand? A span id looks like: a3f2b1c4d5e6f7a8. If we expand 200 spans, we have to stuff 200 of those into the URL. The URL would become thousands of characters long.