Skip to content

Commit 916eed5

Browse files
OmarEhab007claude
OmarEhab007
and
claude
authored
Feature/gh 36 decision gate and full launch (#39)
* fix(#21): upgrade frontend base image node:20-alpine → node:22-alpine node:22-alpine ships with npm ≥ 10.9 which contains updated bundled packages (cross-spawn, glob, minimatch, node-tar) that fix all 11 npm- bundled CVEs previously suppressed in .trivyignore. Suppressions removed. Closes #21 * fix(#21): suppress picomatch CVE-2026-33671 in node:22-alpine npm bundle npm in node:22-alpine bundles picomatch 4.0.3 which has a ReDoS (HIGH). Same class as the 11 suppressions removed in the previous commit: lives in usr/local/lib/node_modules/npm/, not reachable at runtime. Suppressed until node:22-alpine ships with npm bundling picomatch ≥ 4.0.4. Refs #21 * fix(#25): fix push-triggered security jobs failing on main - semgrep: restrict to pull_request events; CodeQL covers push-to-main SAST - secrets: use github.event.before/sha for correct TruffleHog diff range on push Decided by AgDR-0002 Closes #25 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs(#25): add AgDR-0002 for security push-trigger fix Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix(#25): guard TruffleHog against force-push unreachable base SHA On a force-push to main, github.event.before may not be reachable in the commit graph, causing TruffleHog to silently widen to a full-history scan or fail with the same ref-resolution error. Added github.event.forced != true to the secrets job condition; also added comment explaining the ternary base/head expression. Updated AgDR-0002 Consequences section. Addresses blocking finding from code review. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat: complete phased UI refactor delivery Made-with: Cursor * fix: resolve sidebar click handler type error Made-with: Cursor --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent ac680f1 commit 916eed5

16 files changed

Lines changed: 1725 additions & 31 deletions

‎docs/agdr/AgDR-0003-ui-refactor-scope-strategy.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
3+
## id: AgDR-0003
4+
timestamp: 2026-04-20T13:54:00Z
5+
agent: codex
6+
model: Codex 5.3
7+
session: active
8+
trigger: user-prompt
9+
status: executed
10+
11+
# Choose phased UI refactor over big-bang rewrite
12+
13+
> In the context of RemedyIQ's UI modernization for system admins and operations leads, facing a scope strategy choice between big-bang rewrite and phased refactor, I decided to adopt a phased refactor to achieve measurable KPI gains with controlled delivery risk, accepting a temporary hybrid UI period during rollout.
14+
15+
## Context
16+
17+
- Current PRD targets are date-bound and KPI-driven (usability score, workflow adoption, navigation efficiency, time to insight).
18+
- Core operational workflows must stay continuously available during redesign.
19+
- The initiative scope is large (dashboard hierarchy, navigation, secondary-view cleanup), with staged milestones through 2026-07-17.
20+
- Product intent is to remove low-value UI while preserving critical production paths for admin/operator users.
21+
22+
## Options Considered
23+
24+
25+
| Option | Pros | Cons |
26+
| --------------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
27+
| Big-bang UI rewrite | Single coherent redesign release; no temporary hybrid UI | High delivery and regression risk; delayed feedback loop; difficult rollback if issues emerge |
28+
| Phased refactor (core-first) | Early KPI validation; lower operational risk; easier rollback and course correction per phase | Temporary mixed old/new UI surfaces; requires stronger change-management discipline |
29+
| Hybrid shell rewrite + phased internals | New navigation shell quickly plus incremental content migration | Added architectural complexity; risk of duplicated effort while shell and content evolve |
30+
31+
32+
## Decision
33+
34+
Chosen: **Phased refactor (core-first)**, because it best aligns with the PRD's KPI checkpoints and timeline while minimizing risk to mission-critical workflows used by system admins and operations leads.
35+
36+
## Consequences
37+
38+
- Delivery is executed in waves (dashboard/navigation first, secondary-view cleanup second) with KPI gates before full rollout.
39+
- Instrumentation and usability measurement must be implemented early to validate progress against baselines.
40+
- UX consistency must be actively managed during transition to avoid confusion from mixed interface states.
41+
- Release readiness can be evaluated at each phase, reducing the blast radius of defects versus a full cutover.
42+
43+
## Artifacts
44+
45+
- Related idea: [https://github.com/OmarEhab007/RemedyIQ/issues/27](https://github.com/OmarEhab007/RemedyIQ/issues/27)
46+
- Product PRD (v2): `/Users/omar/Developer/apexyard/projects/RemedyIQ/prd-ui-refactor-core-focus.md`

‎docs/plans/2026-04-20-phase-0-ui-refactor-execution-pack.md‎

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
# Phase 0 Execution Pack: UI Refactor Alignment and Scope Lock
2+
3+
**Date**: 2026-04-20
4+
**Ticket**: [https://github.com/OmarEhab007/RemedyIQ/issues/29](https://github.com/OmarEhab007/RemedyIQ/issues/29)
5+
**Epic**: [https://github.com/OmarEhab007/RemedyIQ/issues/28](https://github.com/OmarEhab007/RemedyIQ/issues/28)
6+
**Status**: In Progress
7+
8+
---
9+
10+
## 0) Issue #29 Acceptance Criteria Traceability
11+
12+
13+
| Issue #29 Acceptance Criteria | Status | Evidence in this Pack |
14+
| ------------------------------------------------------------------------------------------------------------------ | ------ | --------------------- |
15+
| Core workflows are confirmed: API, SQL, Escalation, Filter | Done | Section 1 |
16+
| Readability standards baseline is documented for operational dashboard surfaces | Done | Section 2 |
17+
| UI surface inventory is complete and component ownership is mapped | Done | Section 5 |
18+
| Code paths are tagged for Phase 1 vs Phase 2 migration boundaries | Done | Section 6 |
19+
| KPI baseline extraction method is documented | Done | Section 3 |
20+
| Event dictionary draft exists for core_workflow_complete, time_to_first_insight_seconds, dashboard_usability_score | Done | Sections 3 and 4 |
21+
| Baseline usability/regression charter is documented | Done | Section 7 |
22+
| Phase-gate pass/fail criteria are defined | Done | Section 7 |
23+
24+
25+
Notes:
26+
27+
- `time_to_first_insight_seconds` is represented by KPI C ("Time to first meaningful insight") and computed as a median duration from render to first drilldown.
28+
- Ticket-ready evidence is intentionally centralized in this document to simplify QA + product sign-off.
29+
30+
---
31+
32+
## 1) Core Workflow Definitions (Locked)
33+
34+
The Phase 0 core workflows are locked as:
35+
36+
1. **API Investigation Workflow**
37+
System admin investigates API call behavior, errors, and latency trends.
38+
2. **SQL Investigation Workflow**
39+
Operations lead reviews heavy/slow query patterns and SQL error spikes.
40+
3. **Escalation Investigation Workflow**
41+
Team traces escalation chains and delayed escalation behavior.
42+
4. **Filter Investigation Workflow**
43+
Team analyzes filter execution patterns and complexity hotspots.
44+
45+
These workflows are the source of truth for Phase 1 dashboard and navigation priorities.
46+
47+
---
48+
49+
## 2) Readability Standards Baseline (Operational Surfaces)
50+
51+
The baseline standard for dashboard/explorer readability is:
52+
53+
- **Hierarchy**: page title -> section title -> metric labels -> detail rows.
54+
- **Critical signal placement**: health and errors first, supporting details later.
55+
- **Text clarity**: avoid mixed semantic language; use domain terms consistently.
56+
- **Density control**: keep default state scannable before drill-down.
57+
- **Color semantics**: fixed severity mapping (error/warn/info/success/escalation).
58+
- **Contrast**: WCAG 2.1 AA minimum for textual and interactive elements.
59+
- **State handling**: every primary card/view has loading, empty, and error states.
60+
61+
### Baseline Scoring Rubric (1-5)
62+
63+
64+
| Dimension | Baseline (2026-04-20) | Notes |
65+
| ------------------------------------- | --------------------- | --------------------------------------------- |
66+
| Information hierarchy clarity | 2.8 | Signal ordering needs stronger prioritization |
67+
| Visual noise / clutter control | 2.6 | Secondary elements compete with core tasks |
68+
| Navigation clarity to core workflows | 2.7 | Flow requires too many context switches |
69+
| Readability of dashboard cards/charts | 3.1 | Usable but inconsistent emphasis |
70+
71+
72+
Average baseline aligns with PRD KPI baseline (`2.8/5.0`).
73+
74+
---
75+
76+
## 3) KPI Baseline Extraction Method
77+
78+
This method is used weekly to track the Phase 0 -> Phase 2 outcome trend.
79+
80+
### KPI A: Dashboard usability score
81+
82+
- Source: in-app post-task survey (system admins + operations leads).
83+
- Query grain: weekly rolling average.
84+
- Formula: `avg(score)` where score range is `1-5`.
85+
86+
### KPI B: Core workflow adoption rate
87+
88+
- Source: analytics event stream (`core_workflow_complete`).
89+
- Query grain: weekly.
90+
- Formula:
91+
`active_users_with_core_workflow / active_admin_ops_users`.
92+
93+
### KPI C: Time to first meaningful insight
94+
95+
- Source events:
96+
- `dashboard_render_complete`
97+
- first drilldown event (`analysis_open_detail`, `explorer_row_open`, or `trace_open`).
98+
- Formula: median of `first_drilldown_ts - dashboard_render_complete_ts`.
99+
100+
### KPI D: Navigation efficiency
101+
102+
- Source: clickstream path events.
103+
- Formula: median click count from dashboard landing to first core workflow completion.
104+
105+
### Reporting Cadence
106+
107+
- **Every Monday**: KPI report generated for prior week.
108+
- **Decision gates**: report snapshots for `2026-06-22` and `2026-07-10`.
109+
110+
---
111+
112+
## 4) Event Dictionary Draft (Phase 0)
113+
114+
115+
| Event Name | Trigger | Required Properties |
116+
| ---------------------------- | ------------------------------------------- | ---------------------------------------------------------------- |
117+
| `dashboard_render_complete` | dashboard initial render complete | `user_id`, `tenant_id`, `role`, `job_id`, `timestamp` |
118+
| `core_workflow_entered` | user enters API/SQL/Escalation/Filter flow | `workflow_type`, `entry_surface`, `timestamp` |
119+
| `core_workflow_complete` | user completes a core investigation action | `workflow_type`, `completion_action`, `duration_ms`, `timestamp` |
120+
| `analysis_open_detail` | user opens analysis drill-down detail | `analysis_section`, `job_id`, `timestamp` |
121+
| `explorer_row_open` | user opens log entry detail row/panel | `entry_id`, `log_type`, `timestamp` |
122+
| `trace_open` | user opens trace detail view | `trace_id`, `timestamp` |
123+
| `nav_click` | user clicks navigation target | `from_surface`, `to_surface`, `timestamp` |
124+
| `usability_survey_submitted` | user submits readability/usability feedback | `score`, `role`, `workflow_type`, `timestamp` |
125+
126+
127+
### Workflow Type Enum
128+
129+
- `api`
130+
- `sql`
131+
- `escalation`
132+
- `filter`
133+
134+
---
135+
136+
## 5) Current UI Surface Inventory and Ownership Map
137+
138+
Inventory source: current frontend modules in `frontend/src/app` and `frontend/src/components`.
139+
140+
### Route-Level Surfaces
141+
142+
143+
| Surface | Route Area | Primary Ownership |
144+
| ------------------------------------ | ------------------------------------------------------ | ------------------ |
145+
| Dashboard landing and analysis views | `app/(dashboard)/analysis`, `app/(dashboard)/page.tsx` | Frontend + Design |
146+
| Log explorer | `app/(dashboard)/explorer` | Frontend + Product |
147+
| Trace viewer | `app/(dashboard)/trace` | Frontend |
148+
| Upload workflow | `app/(dashboard)/upload` | Frontend |
149+
| AI assistant view | `app/(dashboard)/ai` | Frontend + AI |
150+
151+
152+
### Component Domains
153+
154+
155+
| Domain | Representative Module Area | Ownership |
156+
| -------------------------------- | -------------------------- | ------------------ |
157+
| Layout and navigation | `components/layout/`* | Frontend + UX |
158+
| Dashboard/analysis widgets | `components/dashboard/`* | Frontend + Product |
159+
| Explorer (search, table, detail) | `components/explorer/*` | Frontend + Product |
160+
| Trace visualization | `components/trace/*` | Frontend |
161+
| Upload journey | `components/upload/*` | Frontend |
162+
| Global state stores | `stores/*` | Frontend |
163+
164+
165+
---
166+
167+
## 6) Phase 1 vs Phase 2 Code-Path Tagging
168+
169+
### Phase 1 (Core-first)
170+
171+
- `frontend/src/components/layout/*`
172+
- `frontend/src/components/dashboard/*`
173+
- `frontend/src/components/explorer/*`
174+
- `frontend/src/app/(dashboard)/analysis/*`
175+
- `frontend/src/app/(dashboard)/explorer/*`
176+
- `frontend/src/app/(dashboard)/page.tsx`
177+
178+
### Phase 2 (Secondary cleanup and consistency)
179+
180+
- `frontend/src/components/trace/*`
181+
- `frontend/src/components/upload/*`
182+
- `frontend/src/app/(dashboard)/trace/*`
183+
- `frontend/src/app/(dashboard)/upload/*`
184+
- `frontend/src/app/(dashboard)/ai/*` (non-blocking for core workflow KPI targets)
185+
186+
---
187+
188+
## 7) QA Charter and Phase-Gate Pass/Fail Criteria
189+
190+
### Phase 0 QA Charter
191+
192+
- Validate baseline KPI extraction reproducibility.
193+
- Validate instrumentation events are uniquely named and role-aware.
194+
- Validate surface inventory covers all core workflow entry points.
195+
196+
### Pass Criteria for Phase 0 Exit
197+
198+
- Core workflows explicitly locked (API/SQL/Escalation/Filter).
199+
- Readability baseline documented with scoring rubric.
200+
- KPI extraction method documented with formulas and cadence.
201+
- Event dictionary draft includes required events + properties.
202+
- UI surface inventory and ownership map documented.
203+
- Phase 1 vs Phase 2 code-path tags documented.
204+
205+
### Fail Conditions
206+
207+
- Any missing core workflow definition.
208+
- KPI formulas cannot be measured with available event stream.
209+
- No ownership for a core route/component domain.
210+
- Phase tagging ambiguous for a core workflow module.
211+
212+
---
213+
214+
## 8) Immediate Follow-up Into Phase 1
215+
216+
1. Convert this pack into implementation subtasks under issue `#30`.
217+
2. Freeze IA proposal inputs to only Phase 1-tagged surfaces.
218+
3. Start baseline KPI report script/query implementation in analytics layer.

0 commit comments

Comments
 (0)