# Change Request: CR-004

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

## Request Details

**Requestor:** Human (UIUX Feedback)
**Date Received:** 2026-03-13
**Priority:** Medium
**UIUX Feedback ID:** Feedback-20260313-165013

## Description

Add KB Reference integration to the Workplace Ideation compose pane. Four tightly coupled requirements:

1. **KB Reference Button:** On the same line as the Submit Idea button, add a "KB Reference" button on the leftmost side of the action bar.
2. **Open KB Reference Picker:** When the button is clicked, open the existing KB Reference Picker modal. Record which idea-folder is invoking it so that insert knows the target.
3. **Insert Knowledge References:** On insert, write a `.knowledge-reference.yaml` file to the idea folder linking the selected knowledge file paths. Format:
   ```yaml
   knowledge-reference:
     - path/to/file1
     - path/to/file2
   ```
4. **Reference Count Label:** After inserting references, display a reference count label. When clicked, show an inline popup listing referenced knowledge items with type icons (folder/file).

## Business Justification

Connecting the Knowledge Base to the Ideation workflow enables idea authors to attach relevant KB articles and files as references when composing ideas. This increases KB utilization, improves idea quality with supporting materials, and fulfills FEATURE-049-G's design intent of "cross-workflow invocation from any workflow phase."

## Impact Analysis

### Classification

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

**Reasoning:**
- FEATURE-049-G (KB Reference Picker) was designed as a "cross-workflow modal for selecting KB articles/folders" — this CR adds the compose pane as one such workflow integration point.
- The KB Reference Picker itself does not need modification — it already supports `onInsert` callback and dispatches `kb:references-inserted` events.
- Works within current system boundaries: same users, reuses existing picker modal, small API modification.
- No new screens or data models (`.knowledge-reference.yaml` is a simple file, not a new data model).

### Comparison Matrix

| Aspect | CR Requirement | Existing Feature(s) |
|--------|---------------|---------------------|
| Users | Idea authors (same) | Idea authors |
| Workflow | Compose → attach KB refs → submit | Compose → submit (no KB refs) |
| Data Model | .knowledge-reference.yaml in idea folder | No KB reference file |
| UI Elements | KB Reference button + count label + popup | Only Submit Idea button in compose actions |
| API Endpoints | Modify /api/ideas/upload (add kb_references field) | Accepts files only |

### Conflict Analysis

**Conflicts Found:** Yes

| # | Type | Affected Feature | Severity | Classification | Description |
|---|------|-----------------|----------|----------------|-------------|
| 1 | design | Workplace compose | Medium | unexpected | `.workplace-compose-actions` has single-button layout; adding second button requires flex layout CSS changes |
| 2 | dependency | ideas_routes + ideas_service | Medium | expected | `/api/ideas/upload` needs new `kb_references` form field + YAML writer |
| 3 | design | workplace.js + kb-reference-picker.js | Low | expected | Event listener or callback pattern integration needed |
| 4 | code | workplace.js (setupComposer) | Low | expected | Button HTML + picker instantiation needed |
| 5 | code | workplace.js (submitComposedIdea) | Low | expected | FormData field append for kb_references |
| 6 | design | workplace.js | Low | expected | Reference count badge UI — no mockup yet |
| 7 | specification | IdeasService | Low | expected | YAML schema documentation needed |
| 8 | dependency | kb_routes.py | Low | expected | Feature detection + graceful degradation |

**Unexpected Conflict Resolution:**
- Conflict #1 (button layout): Mitigated via design specification — use `display: flex; justify-content: space-between` on `.workplace-compose-actions` to place KB button left, Submit button right. KB button styled as `btn-outline-secondary` (secondary to Submit).

**Mitigation Strategy:**
- Button layout CSS changes scoped to `.workplace-compose-actions` only — no cascading impact.
- Backend YAML writing is additive — doesn't change existing upload behavior.
- KB Reference Picker is unmodified — only consumer code is added.

### Affected Components

| Component | Impact Level | Details |
|-----------|--------------|---------|
| workplace.js (compose pane) | High | Add KB Reference button, count label, popup, event handling |
| workplace.js (submitComposedIdea) | Medium | Include .knowledge-reference.yaml in submission |
| ideas_routes.py | Medium | Accept kb_references form field |
| ideas_service.py | Medium | Write .knowledge-reference.yaml to idea folder |
| workplace CSS | Low | Flex layout for multi-button action bar |
| kb-reference-picker.js | None | No changes — used as-is via onInsert callback |

### Dependencies

- FEATURE-049-G (KB Reference Picker) — must be functional (already implemented)
- `/api/ideas/upload` endpoint — must be extended to handle kb_references
- KB API endpoints (`/api/kb/tree`, `/api/kb/files`, `/api/kb/search`) — must be available

## Proposed Approach

1. **Frontend (workplace.js):**
   - Add "KB Reference" button (leftmost) in `.workplace-compose-actions`
   - On click: instantiate KBReferencePicker with `onInsert` callback
   - Track `idea-folder` context for the insert target
   - Store selected references in component state
   - Render reference count label + click popup after insert
   - On submit: include references in FormData

2. **Backend (ideas_routes.py + ideas_service.py):**
   - Parse `kb_references` field from form data
   - Write `.knowledge-reference.yaml` to the created idea folder
   - YAML format: `knowledge-reference: [list of paths]`

3. **CSS:**
   - Update `.workplace-compose-actions` to flex layout

## Mockup Impact

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

| Original Mockup | Path | Status After CR |
|-----------------|------|-----------------|
| KB Interface v1 (Scene 3 — Reference Picker) | x-ipe-docs/requirements/EPIC-049/mockups/kb-interface-v1.html | unchanged (picker reused as-is) |

**Updated Mockup(s):**

| New Mockup | Path | Based On | Changes Applied |
|------------|------|----------|-----------------|
| (To be created during feature refinement) | TBD | N/A — new compose pane layout | Button placement, count label, popup |

## Approval

- [x] Classification approved (via DAO — auto_proceed mode)
- [x] Conflict analysis reviewed (via DAO)
- [x] Approach approved (via DAO)
- [x] Ready for execution

## Execution

**Classification Result:** modification
**Conflicts Resolution:** mitigated

**Actions Taken:**
- [x] CR document created in feature folder
- [x] Conflict analysis completed and documented
- [x] Specification Version History updated with CR link
- [ ] Mockup to be created during feature refinement phase
- [x] Next task type set: x-ipe-task-based-feature-refinement

## Links

- Feature Specification: [specification.md](./specification.md)
- Requirement Details: [requirement-details-part-20.md](../../requirement-details-part-20.md)
- UIUX Feedback: [Feedback-20260313-165013](../../../uiux-feedback/Feedback-20260313-165013/feedback.md)

---

## Change History

| Date | Change | By |
|------|--------|----|
| 2026-03-13 | CR created from UIUX feedback Feedback-20260313-165013 | Pulse 💓 (Agent) |
