portfolio/.ralph/agent/scratchpad.md

# Scratchpad — Comprehensive Codebase Refactor

## 2026-02-17 — Iteration 1: Planning Phase 0.1

### Baseline
- Total src lines: 13,242
- Starting phase in App.tsx: `useState<Phase>('boot')` (line 48)

### Current state
Fresh start. No checklist items completed yet. The plan.md file contains leftover content from a previous objective (profile-content rollout). Will overwrite with new plan.

### Analysis for Phase 0.1
- Task: Change `useState<Phase>('boot')` → `useState<Phase>('pmr')` in `src/App.tsx` line 48
- This is a single-character change that skips the boot/ECG/login sequence
- All components and imports remain untouched
- Verification: `npm run build` passes
- This is the simplest possible first step — confidence 100

## 2026-02-17 — Iteration 2: Build Phase 0.1

### Completed
- Changed `useState<Phase>('boot')` → `useState<Phase>('pmr')` in `src/App.tsx` line 48
- `npm run build` passes cleanly
- Marked 0.1 complete in Ralph/PROMPT.md and .ralph/plan.md
- Next up: Phase 1.1 — Migrate medications.ts history into skills.ts

## 2026-02-17 — Iteration 3: Coordinating Phase 1.1

### Backpressure status
- lint: pass (0 errors, 5 pre-existing warnings)
- typecheck: pass (clean)
- build: pass (6.62s)
- Phase 0.1 confirmed complete — App.tsx line 48 shows `'pmr'`

### Plan for Phase 1.1
- Task: task-1771291778-077f — Migrate medications.ts prescribingHistory into skills.ts
- medications.ts is dead code (zero imports) but contains rich prescribingHistory data
- Need to: merge data into skills.ts, update SkillMedication type, delete medications.ts
- Delegating to Refactor Planner via work.start to analyse and produce a detailed plan

## 2026-02-17 — Iteration 4: Build Phase 1.1

### Analysis
- medications.ts had 18 entries (262 lines), skills.ts had 21 entries (240 lines)
- ID mapping: 17 of 18 medication entries matched skills (med-dashboard had no match — Dashboard Development is subsumed by Power BI)
- 3 skills had no medication counterpart: excel, change-management, financial-modelling, executive-comms — they don't get prescribingHistory

### Changes made
1. `src/types/pmr.ts`: Added `prescribingHistory?: PrescribingHistoryEntry[]` to `SkillMedication` interface
2. `src/types/pmr.ts`: Removed dead `Medication` interface (was only used by medications.ts)
3. `src/data/skills.ts`: Added prescribingHistory arrays to 17 matching skill entries
4. Deleted `src/data/medications.ts`

### Verification
- lint: pass (0 errors, 5 pre-existing warnings)
- typecheck: pass (clean)
- build: pass (4.13s)
- No broken imports (medications.ts had zero consumers)

## 2026-02-17 — Iteration 5: Build Phase 1.2

### Analysis
- `timelineNarrative` in `profile-content.ts` contained ~155 lines of narrative data for 8 timeline entities
- `getTimelineNarrativeEntry()` was called 32 times in `timeline.ts` — 4 calls per entity (description, details, outcomes, codedEntries)
- No other consumers of the function or the `TimelineNarrativeId`/`TimelineNarrativeEntry` types

### Changes made
1. `src/data/timeline.ts`: Inlined all narrative data (description, details, outcomes, codedEntries) directly into each TimelineEntity object; removed import of `getTimelineNarrativeEntry`
2. `src/data/profile-content.ts`: Removed entire `timelineNarrative` section (~155 lines)
3. `src/lib/profile-content.ts`: Removed `getTimelineNarrativeEntry()` function and its type imports (`TimelineNarrativeId`, `TimelineNarrativeEntry`)
4. `src/types/profile-content.ts`: Removed `TimelineNarrativeCodeEntry`, `TimelineNarrativeEntry`, `TimelineNarrativeId` types and `timelineNarrative` field from `ProfileContent` interface

### Verification
- lint: pass (0 errors, 5 pre-existing warnings)
- typecheck: pass (clean)
- build: pass (4.41s)
- All narrative data preserved — identical runtime output

## 2026-02-17 — Iteration 6: Coordinating Phase 1.3

### Backpressure status (resolving build.blocked event)
- lint: pass (0 errors, 5 pre-existing warnings)
- typecheck: pass (clean)
- build: pass (4.19s)
- Phases 0.1, 1.1, 1.2 all verified complete

### Analysis of profile-content.ts after Phase 1.2
After removing timelineNarrative, `src/data/profile-content.ts` is now 246 lines containing:
1. **profile** section: sectionTitle, patientSummaryNarrative, latestResults, sidebar copy — all UI labels/strings
2. **experienceEducation**: educationEntries (4 items with title/subtitle/keywords), UI labels
3. **skillsNarrative**: summary text, UI labels + categories
4. **resultsNarrative**: 4 achievement entries (title/subtitle/keywords/kpiId)
5. **searchChat**: quickActions (4 items), LLM systemPrompt (~110 lines)

### Consumers (from grep):
- `getLatestResultsCopy, getProfileSectionTitle, getProfileSummaryText` → PatientSummaryTile.tsx
- `getSidebarCopy` → Sidebar.tsx
- `getExperienceEducationUICopy` → TimelineInterventionsSubsection.tsx
- `getSkillsUICopy` → RepeatMedicationsSubsection.tsx, SkillsAllDetail.tsx
- `getLLMCopy` → llm.ts
- `getSearchQuickActions, getAchievementEntries, getEducationEntries` → search.ts

### Plan for Phase 1.3
The objective says to split profile-content.ts into focused concerns:
- LLM system prompt → inline into llm.ts or dedicated file
- Education narrative → merge into documents.ts or educationExtras.ts
- Keep only genuinely unique content in profile-content.ts

However, looking at the current state, profile-content.ts is a cohesive text/copy store (246 lines) with clear structure and typed accessors. The LLM prompt is the largest chunk (~110 lines) and is the best candidate for extraction. The education entries and achievements are compact and well-organized.

Delegating to Refactor Planner to analyse and produce detailed plan for this phase.

## 2026-02-17 — Iteration 7: Planning Phase 1.3

### Analysis
After Phase 1.2, profile-content.ts is 246 lines with 5 sections. The LLM systemPrompt (~110 lines) is the dominant chunk with a single consumer (llm.ts). Education entries carry `keywords` not present in documents.ts, so merging would bloat Document type. Achievement entries are compact and unique.

### Decision
Extract LLM prompt only → new `src/data/llm-prompt.ts`. Keep education, achievements, quick actions, and UI labels in profile-content.ts as a cohesive "UI copy and search metadata" store.

### Changes planned
1. Create `src/data/llm-prompt.ts` with `LLM_SYSTEM_PROMPT` const
2. Remove `searchChat.llm` from `src/data/profile-content.ts`
3. Remove `LLMCopy` from types and `getLLMCopy()` from accessors
4. Update `src/lib/llm.ts` to import directly from `@/data/llm-prompt`
5. Result: profile-content.ts drops from ~246 to ~135 lines

Plan written to .ralph/plan.md. Emitting plan.ready.

## 2026-02-17 — Iteration 8: Build Phase 1.3

### Changes made
1. Created `src/data/llm-prompt.ts` — exported `LLM_SYSTEM_PROMPT` const (110 lines)
2. `src/data/profile-content.ts` — removed entire `llm` property from `searchChat` section (246 → 133 lines, net -113 lines)
3. `src/types/profile-content.ts` — removed `LLMCopy` interface, removed `llm` field from `searchChat` in `ProfileContent`
4. `src/lib/profile-content.ts` — removed `getLLMCopy()` function and `LLMCopy` import
5. `src/lib/llm.ts` — import changed from `getLLMCopy` to direct `LLM_SYSTEM_PROMPT` import; `buildSystemPrompt()` returns the const directly

### Verification
- lint: pass (0 errors, 5 pre-existing warnings)
- typecheck: pass (clean)
- build: pass (6.44s)
- No remaining references to `getLLMCopy` or `LLMCopy` anywhere in src/
- `buildSystemPrompt()` returns identical string at runtime

### Post-state
- profile-content.ts: 133 lines — cohesive UI copy + search metadata store
- llm-prompt.ts: 110 lines — self-contained LLM system prompt
- Phase 1.3 complete. Next: Phase 1.4 (evaluate thin re-export layers)

## 2026-02-17 — Iteration 9: Coordinating Phase 1.4

### Backpressure status (resolving build.blocked event — was stale)
- lint: pass (0 errors, 5 pre-existing warnings)
- typecheck: pass (clean)
- build: pass (4.21s)
- Phases 0.1, 1.1, 1.2, 1.3 all verified complete

### Analysis for Phase 1.4
Two thin re-export layers to evaluate:

1. **`src/data/constellation.ts`** (9 lines) — 5 consumers:
   - useForceSimulation.ts, useTimelineAnimation.ts, SkillDetail.tsx, CareerConstellation.tsx, screen-reader-description.ts
   - Caches `buildConstellationData()` result at module level — valuable; without it each consumer would call the build function independently
   - **Decision: KEEP** — serves a real purpose (module-level caching + clean API surface)

2. **`src/data/tags.ts`** (10 lines) — 1 consumer (Sidebar.tsx)
   - Derives `Tag[]` from `getTopTimelineSkills()` with color assignment
   - Only one consumer, so could inline into Sidebar.tsx
   - However, it's clean derived data with a clear responsibility, and inlining would mix data derivation with UI
   - **Decision: KEEP** — clean separation of concerns, minimal overhead

### Action
Both files are justified re-export/derivation layers. Add brief comments explaining why the indirection exists, then move to Phase 2.1.

Delegating to Refactor Planner to produce the plan for Phase 1.4 + Phase 2.1.

## 2026-02-17 — Iteration 10: Planning Phase 1.4 + Phase 2.1

### Analysis
- Phase 1.4 is trivial: add clarifying comments to constellation.ts and tags.ts (both kept)
- Phase 2.1 analysis complete:
  - `hexToRgba`: 3 identical definitions in DashboardLayout, WorkExperienceSubsection, TimelineInterventionsSubsection
  - `prefersReducedMotion`: 6 module-level definitions (5 local + 1 in constellation/constants.ts)
  - 5 files already import from constellation/constants.ts — those will continue to work via re-export
  - 5 files with inline/hook/useState patterns are intentionally different and should NOT be changed

### Decision
- Move both `hexToRgba` and `prefersReducedMotion` to `src/lib/utils.ts`
- Re-export `prefersReducedMotion` from `constellation/constants.ts` to avoid changing 5 existing importers
- Remove 3 local `hexToRgba` defs and 5 local `prefersReducedMotion` defs
- Combined 1.4 + 2.1 into one iteration since 1.4 is comments-only

### Plan written to .ralph/plan.md. Emitting plan.ready.

## 2026-02-17 — Iteration 11: Build Phase 1.4 + Phase 2.1

### Phase 1.4 — Re-export layer comments
- Added clarifying comment to `src/data/constellation.ts` (module-level caching purpose, 5 consumers)
- Added clarifying comment to `src/data/tags.ts` (data derivation separated from UI)
- Both files kept as-is — justified indirection layers

### Phase 2.1 — Utility extraction
1. `src/lib/utils.ts`: Added `hexToRgba()` function and `prefersReducedMotion` const
2. `src/components/DashboardLayout.tsx`: Removed local `hexToRgba` (6 lines) + `prefersReducedMotion` (1 line), added import from `@/lib/utils`
3. `src/components/WorkExperienceSubsection.tsx`: Removed local `hexToRgba` (6 lines) + `prefersReducedMotion` (1 line), added import from `@/lib/utils`
4. `src/components/TimelineInterventionsSubsection.tsx`: Removed local `hexToRgba` (6 lines) + `prefersReducedMotion` (1 line), added import from `@/lib/utils`
5. `src/components/CommandPalette.tsx`: Removed local `prefersReducedMotion` (1 line), added import from `@/lib/utils`
6. `src/components/ChatWidget.tsx`: Removed local `prefersReducedMotion` (1 line), added import from `@/lib/utils`
7. `src/components/constellation/constants.ts`: Replaced local `prefersReducedMotion` with re-export from `@/lib/utils` (preserves 5 existing `./constants` importers)

### Verification
- `hexToRgba` defined in exactly 1 file: `src/lib/utils.ts`
- `prefersReducedMotion` module-level const in exactly 1 file: `src/lib/utils.ts` (ProjectsTile uses intentionally different useState+effect pattern)
- lint: pass (0 errors, 5 pre-existing warnings)
- typecheck: pass (clean)
- build: pass (4.23s)
- Net lines removed: ~26 (3×7 hexToRgba + 5×1 prefersReducedMotion - 8 new import lines + 9 new lines in utils.ts)
- Phases 1.4 and 2.1 complete. Next: Phase 2.2

## 2026-02-17 — Iteration 12: Coordinating Phase 2.2

### Backpressure status (resolving build.blocked event — was stale)
- lint: pass (0 errors, 5 pre-existing warnings)
- typecheck: pass (clean)
- build: pass (4.17s)
- Phases 0.1, 1.1, 1.2, 1.3, 1.4, 2.1 all verified complete

### Plan for Phase 2.2
- Task: Audit codebase for other repeated patterns used 3+ times
- Candidates from objective: date formatting, color manipulation, responsive breakpoint checks, animation config objects
- Delegating to Refactor Planner via work.start to analyse and identify consolidation targets

## 2026-02-17 — Iteration 13: Planning Phase 2.2

### Audit Results

Comprehensive search across all src/ files found these duplicated patterns:

#### 1. STATUS COLOR MAPS — 4 locations, 1 inconsistency (HIGH)
- `Card.tsx` and `DetailPanel.tsx`: identical 5-color maps `{ teal, amber, green, alert, purple }`
- `PatientSummaryTile.tsx` and `KPIDetail.tsx`: identical 3-color maps `{ green, amber, teal }`
- `ProjectsTile.tsx` vs `ProjectDetail.tsx`: **INCONSISTENT** — `Ongoing` is `#0D6E6E` in tile but `#D97706` in detail; `Live` is `#059669` in tile but `#0D6E6E` in detail
- Note: index.css also defines `--amber`, `--alert`, `--purple` CSS vars

#### 2. DEFAULT ORG COLOR FALLBACK — 9 occurrences (MEDIUM)
- `consultation.orgColor ?? '#0D6E6E'` repeated 6 times in WorkExperienceSubsection and 3 times in DashboardLayout
- Should be a named constant

#### 3. MOTION-SAFE TRANSITION PATTERN — 7 occurrences (MEDIUM)
- `prefersReducedMotion ? { duration: 0 } : { duration: X, ease: 'easeOut' }` in DashboardLayout (2x), WorkExperienceSubsection, ChatWidget (2x), TimelineInterventionsSubsection, MobileAccordion
- Vary only by duration and delay — perfect for a utility function

#### 4. SHADOW rgba(26,43,42,...) — 15+ occurrences (LOW-MEDIUM)
- Already partly in CSS vars (`--shadow-sm`, `--shadow-md`, `--shadow-lg`)
- Some inline JS usages can't easily use CSS vars (D3 flood-color, dynamic hover)
- Worth extracting base color `26,43,42` as a constant but low ROI for a function since opacities vary and most are unique contexts

#### 5. BREAKPOINT CHECKS — border case (3 for 640, 2 for 768) (LOW)
- `window.innerWidth < 640` in 3 files (useForceSimulation, AccessibleNodeOverlay, CareerConstellation)
- These are inside different contexts (hooks, components, D3) — extracting a constant is simple but extracting a function adds minimal value since the comparison is trivially clear
- Breakpoint values already in tailwind.config.js and CLAUDE.md

### Decision: What to extract

**Extract (3+ occurrences, clear shared concern):**

1. **STATUS_COLORS map** → `src/lib/theme-colors.ts`
   - Full map: `{ teal, amber, green, alert, purple }` (used by Card, DetailPanel)
   - KPI subset: `{ green, amber, teal }` (used by PatientSummaryTile, KPIDetail)
   - Project map: fix inconsistency, single definition (used by ProjectsTile, ProjectDetail)

2. **DEFAULT_ORG_COLOR constant** → `src/lib/theme-colors.ts`
   - `'#0D6E6E'` — replace 9 inline fallbacks

3. **motionSafeTransition() utility** → `src/lib/utils.ts`
   - `(duration, ease?, delay?) => prefersReducedMotion ? { duration: 0 } : { duration, ease, delay }`
   - Replace 7 inline ternaries

**Skip (below threshold or low ROI):**
- Shadow rgba: already in CSS vars, remaining inline usages are in varied contexts
- Breakpoint constants: only 3 occurrences of 640 check, trivially clear inline
- Date formatting: only 2 occurrences
- Section heading styles: varied enough across components to not warrant extraction

## 2026-02-17 — Iteration 14: Build Phase 2.2

### Changes made

#### Change 1: Created `src/lib/theme-colors.ts` — centralised color maps
- `DOT_COLORS`: 5-color map (teal, amber, green, alert, purple)
- `KPI_COLORS`: 3-color subset (green, amber, teal) derived from DOT_COLORS
- `PROJECT_STATUS_COLORS`: 3-status map (Complete=green, Ongoing=amber, Live=teal) — fixes ProjectsTile inconsistency
- `DEFAULT_ORG_COLOR`: '#0D6E6E' constant

#### Change 2: Added `motionSafeTransition()` to `src/lib/utils.ts`
- `motionSafeTransition(duration, ease?, delay?)` — returns motion-safe transition object

#### Files updated (13 total):
1. `Card.tsx` — removed local `dotColorMap`, import `DOT_COLORS`
2. `DetailPanel.tsx` — removed local `dotColorValueMap`, import `DOT_COLORS`
3. `PatientSummaryTile.tsx` — removed local `colorMap`, import `KPI_COLORS`
4. `KPIDetail.tsx` — removed local `colorMap`, import `KPI_COLORS`
5. `ProjectsTile.tsx` — removed local `statusColorMap` (had wrong values), import `PROJECT_STATUS_COLORS`
6. `ProjectDetail.tsx` — removed local `statusColorMap`, import `PROJECT_STATUS_COLORS`
7. `WorkExperienceSubsection.tsx` — import `DEFAULT_ORG_COLOR` + `motionSafeTransition`, replaced 6 hardcoded fallbacks + 1 transition ternary
8. `DashboardLayout.tsx` — import `DEFAULT_ORG_COLOR` + `motionSafeTransition`, replaced 3 hardcoded fallbacks + 2 transition ternaries
9. `ChatWidget.tsx` — import `motionSafeTransition`, replaced 2 transition ternaries
10. `TimelineInterventionsSubsection.tsx` — import `motionSafeTransition`, replaced 1 transition ternary
11. `MobileAccordion.tsx` — import `motionSafeTransition` from `@/lib/utils`, replaced 1 transition ternary

### Verification
- `dotColorMap` / `dotColorValueMap`: zero matches in src/ ✅
- `statusColorMap`: zero matches in src/ ✅
- `orgColor ?? '#0D6E6E'`: zero matches in src/ ✅
- `prefersReducedMotion ? { duration: 0 }`: zero matches in src/ ✅
- lint: pass (0 errors, 5 pre-existing warnings) ✅
- typecheck: pass (clean) ✅
- build: pass (4.40s) ✅
- Project status inconsistency fixed (ProjectsTile now matches ProjectDetail) ✅

### Post-state
- Phase 2.2 complete. All Phase 2 items done. Next: Phase 3.1