# Change Request: CR-003

> Created: 2026-03-13
> Status: Approved
> Classification: Modification
> Related Feature: FEATURE-049-G (KB Reference Picker)

## Request Details

**Requestor:** Human (Product Owner)
**Date Received:** 2026-03-13
**Priority:** Medium
**Source:** UIUX Feedback — Feedback-20260313-102717

## Description

8-point UIUX redesign of the KB Reference Picker modal, based on direct user feedback with annotated screenshot. Changes focus on folder navigation UX, theme consistency, layout standardization, and reference path format.

### Change Items

| # | Change | Current Behavior | Requested Behavior |
|---|--------|------------------|-------------------|
| 1 | Folder non-selectable | Folders have checkboxes for selection | Folders are navigation-only; clicking shows sub-folders/files in right panel |
| 2 | Tree from KB root | Tree shows flat folder list | Tree shows KB root with hierarchical sub-folders (reference ideation tree, folders only) |
| 3 | No dark theme | Dark theme with CSS custom properties | Light theme |
| 4 | Standard modal size | 80vw, max 900px width, 85vh height | Standard modal dimensions (both height and width) |
| 5 | Scrollable content | Fixed-height panels | Content areas scrollable when content overflows |
| 6 | Tag line separation | All tags on single line | Lifecycle tags and domain tags on separate lines |
| 7 | Breadcrumb nav + folder checkbox | No breadcrumb; folder checkboxes in tree | Right panel top: breadcrumb navigation bar; far-right checkbox to select current folder |
| 8 | Full path links | Relative paths (e.g., `knowledge-base/research/...`) | Full paths (e.g., `x-ipe-docs/knowledge-base/xxxx`) |

## Business Justification

1. **Folder navigation UX**: Checkboxes on folders is confusing — standard file browsers navigate into folders, don't select them. Moving folder selection to the breadcrumb area with explicit checkbox provides clearer intent.
2. **Theme consistency**: The dark theme is inconsistent with the rest of the application UI. Light theme aligns with the overall product design.
3. **Layout standardization**: Standard modal size provides consistent experience across the application.
4. **Reference integrity**: Full paths (`x-ipe-docs/knowledge-base/...`) are needed for proper cross-document linking in the project.
5. **Scanability**: Separating lifecycle and domain tags improves visual scanning and categorization.

## Impact Analysis

### Classification

**Type:** Modification to FEATURE-049-G

**Reasoning:**
- Uses existing data model: same `/api/kb/tree`, `/api/kb/config`, `/api/kb/files`, `/api/kb/search` endpoints (no API changes)
- Same target users: all X-IPE users working in any workflow phase
- Extends existing workflow: same browse → select → copy/insert flow
- Reuses existing UI component: same modal, restructured layout
- No new screens, APIs, or data models needed
- Scoring: MODIFICATION 7 vs NEW_FEATURE 0

### Comparison Matrix

| Aspect | CR Requirement | Existing Feature |
|--------|---------------|-------------------|
| Users | Same (all workflow users) | All workflow users |
| Workflow | Browse → navigate folders → select files/folders → copy/insert | Browse → checkbox select → copy/insert |
| Data Model | Same (tree, config, files) | tree, config, files from APIs |
| UI Elements | Same modal, restructured layout (breadcrumb, light theme, scrollable) | Two-panel dark modal with checkboxes |
| API Endpoints | Same 4 endpoints | `/api/kb/tree`, `/api/kb/config`, `/api/kb/files`, `/api/kb/search` |

### Conflict Analysis

**Conflicts Found:** Yes (7 expected, 0 unexpected)

| # | Type | Affected Artifact | Severity | Classification | Description |
|---|------|------------------|----------|----------------|-------------|
| 1 | specification | FR-049-G-04 (Folder tree rendering) | Medium | expected | Currently specifies checkboxes on folders → CR removes folder checkboxes |
| 2 | specification | FR-049-G-03 (Modal layout) | Low | expected | Specifies 80vw/max 900px → CR wants standard size |
| 3 | specification | UI/UX Requirements (Layout) | Medium | expected | Specifies dark theme → CR requires light theme |
| 4 | specification | AC-049-G-05a (Selection management) | Low | expected | Specifies "file or folder checkbox" → CR changes folder selection to breadcrumb area |
| 5 | specification | BR-049-G-01 (Reference format) | Low | expected | Specifies `knowledge-base/...` relative paths → CR wants `x-ipe-docs/knowledge-base/...` full paths |
| 6 | technical-design | _renderTreePanel() | Medium | expected | Describes checkbox-based folder selection → needs navigation-based approach |
| 7 | code | kb-reference-picker.css | High | expected | Entire stylesheet uses dark theme → needs light theme rewrite |

**Unexpected Conflict Resolution:** N/A — all conflicts are expected (explicitly requested by CR).

**Mitigation Strategy:**
- All spec/design/code changes will be applied during Feature Refinement → Technical Design → Code Implementation workflow
- Existing mockup (kb-interface-v1.html Scene 3) preserved; new mockup version to be created

### Affected Components

| Component | Impact Level | Details |
|-----------|--------------|---------|
| specification.md | High | FR-049-G-03, FR-049-G-04, AC-049-G-05a, BR-049-G-01, UI/UX sections need updates |
| technical-design.md | High | Tree rendering, modal layout, CSS architecture sections need updates |
| kb-reference-picker.js | High | Tree panel behavior, breadcrumb nav, path formatting, folder selection logic |
| kb-reference-picker.css | High | Full light theme rewrite, standard modal sizing, scrollable panels, tag layout |
| tests (kb-reference-picker.test.js) | Medium | Tests for folder selection, path format, theme assertions need updates |

### Dependencies

- No new dependencies introduced
- Existing dependencies unchanged (FEATURE-049-A, FEATURE-049-C, EPIC-039 shell pattern)

## Proposed Approach

1. **Feature Refinement**: Update specification.md with new ACs reflecting all 8 changes
2. **Technical Design Update**: Revise architecture for navigation-based tree, breadcrumb component, light theme
3. **Code Implementation**: Rewrite JS (tree navigation, breadcrumb, path formatting) + CSS (light theme, standard sizing, scrollable layout)
4. **Acceptance Testing**: Verify all 8 changes against updated ACs

## Mockup Impact

**UI/UX Change:** Yes
**Existing Mockups Referenced:**

| Original Mockup | Path | Status After CR |
|-----------------|------|-----------------|
| KB Interface v1 (Scene 3) | x-ipe-docs/requirements/EPIC-049/mockups/kb-interface-v1.html | superseded by v2 |

**Updated Mockup(s):**

| New Mockup | Path | Based On | Changes Applied |
|------------|------|----------|-----------------|
| KB Reference Picker v2 | (to be created during refinement) | Scene 3 of kb-interface-v1.html | Light theme, standard modal, folder navigation, breadcrumb, tag separation, full paths |

## Approval

- [x] Classification approved (DAO — auto mode, confidence 0.92)
- [x] Conflict analysis reviewed (all 7 expected, 0 unexpected)
- [x] Approach approved (modification → refinement → design → implementation)
- [x] Ready for execution

## Execution

**Classification Result:** modification
**Conflicts Resolution:** all_expected

**Actions Taken:**
- [x] CR document created in feature folder (CR-003.md)
- [x] Conflict analysis completed and documented (7 expected, 0 unexpected)
- [x] Specification Version History updated with CR link
- [ ] [Next: Feature Refinement] Specification ACs and FRs updated
- [ ] [Next: Implementation] Existing mockup referenced, new mockup version to be created
- [ ] [Next: Refinement] Specification Linked Mockups section updated
- [x] Next task type set: x-ipe-task-based-feature-refinement

## Links

- Feature Specification: [specification.md](./specification.md)
- Technical Design: [technical-design.md](./technical-design.md)
- Requirement Details: [requirement-details-part-20.md](../../requirement-details-part-20.md)
- UIUX Feedback: [Feedback-20260313-102717](../../../uiux-feedback/Feedback-20260313-102717/feedback.md)
- Existing Mockup: [kb-interface-v1.html (Scene 3)](../mockups/kb-interface-v1.html)

---

## Change History

| Date | Change | By |
|------|--------|----|
| 2026-03-13 | CR created from UIUX Feedback-20260313-102717 | Drift 🌊 (Agent) |
