# Change Request: CR-003

> Created: 2026-03-17
> Status: Approved
> Classification: Modification
> Related Feature: FEATURE-049-B (KB Sidebar & Navigation)

## Request Details

**Requestor:** Human (project owner via UI/UX feedback)
**Date Received:** 2026-03-17
**Priority:** Medium

## Description

Update the KB article detail sidebar so the **Details** section displays the knowledge file's frontmatter description when one is available.

This change comes from `x-ipe-docs/uiux-feedback/Feedback-20260317-160429`, which identified that the knowledge inspection section currently omits a useful description field even though the data already exists in the KB file metadata.

## Business Justification

Descriptions help users understand a knowledge file's purpose without scanning the full article body. Showing the description directly in the inspection sidebar improves context, discoverability, and scanning speed while staying within the current article-detail workflow.

## Impact Analysis

### Classification

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

**Reasoning:**
- Same users, same KB article detail workflow, same modal scene
- No new data model, API endpoint, or screen is introduced
- `frontmatter.description` already exists in the backend data model and file payload
- The change is additive UI behavior inside the existing Details section

### Comparison Matrix

| Aspect | CR Requirement | Existing Feature(s) |
|--------|---------------|---------------------|
| Users | Same developers and knowledge workers browsing KB articles | Same users |
| Workflow | Open KB article → inspect metadata sidebar with description included | Open KB article → inspect metadata sidebar without description |
| Data Model | Reuses existing `frontmatter.description` field | Same KB article/frontmatter model |
| UI Elements | Add one wrapped metadata field in article detail sidebar | Existing Details section in article detail sidebar |
| API Endpoints | No changes | Reuses existing `/api/kb/files/{path}` payload |

### Conflict Analysis

**Conflicts Found:** Yes (minor, all expected)

| # | Type | Affected Feature | Severity | Classification | Description |
|---|------|-----------------|----------|----------------|-------------|
| 1 | specification | FEATURE-049-B | Low | expected | Existing spec is largely silent on article-detail metadata fields, so the CR adds explicit acceptance criteria for the description field. |
| 2 | design | FEATURE-049-B | Low | expected | Existing technical design focuses on navigation/tree behavior; no design contradiction exists because the article detail sidebar already renders adjacent metadata. |
| 3 | code | FEATURE-049-B | Low | expected | The current metadata row layout is single-line, so the description field needs a wrapped row variant to avoid cramped text. |
| 4 | mockup | FEATURE-049-B | Low | expected | Current mockup `kb-interface-v1.html` does not show the description field, so a new mockup version is required. |

**Unexpected Conflict Resolution:**
- None. Independent conflict analysis confirmed all detected gaps are expected and low-risk.

**Mitigation Strategy:**
- Render the field only when `frontmatter.description` exists and is non-empty
- Add a wrapped metadata row style for long text
- Version the article-detail mockup to `kb-interface-v2.html`
- Update the feature specification with explicit article-detail metadata criteria

### Affected Components

| Component | Impact Level | Details |
|-----------|--------------|---------|
| `src/x_ipe/static/js/features/kb-browse-modal.js` | Medium | Add conditional description rendering in the article Details section |
| `src/x_ipe/static/css/kb-browse-modal.css` | Low | Add wrapped metadata row styling for long description text |
| `tests/frontend-js/kb-browse-modal-article-detail.test.js` | Medium | Add focused frontend tests for description rendering |
| `x-ipe-docs/requirements/EPIC-049/FEATURE-049-B/specification.md` | Medium | Add version history entry, linked mockup update, and article-detail ACs/FRs/UX rules |
| `x-ipe-docs/requirements/EPIC-049/mockups/kb-interface-v2.html` | Low | New mockup version reflecting the sidebar description field |

### Dependencies

- Existing KB article file payload with `frontmatter.description`
- Existing article detail sidebar rendering in `kb-browse-modal.js`
- Existing KB mockup source `kb-interface-v1.html`

## Proposed Approach

1. Read `frontmatter.description` in `_renderArticleScene(data)` and render it in the Details section when present.
2. Add a wrapped metadata row style so multi-line descriptions fit the sidebar cleanly.
3. Create `kb-interface-v2.html` from the current mockup and update the article detail scene to show the new field.
4. Update FEATURE-049-B specification and version history to reflect the CR and mockup version.
5. Add frontend tests for rendering and omission behavior, then run the existing test suite.

## Mockup Impact

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

| Original Mockup | Path | Status After CR |
|-----------------|------|-----------------|
| KB Article Detail v1 | `x-ipe-docs/requirements/EPIC-049/mockups/kb-interface-v1.html` | superseded for article-detail scene by v2 |

**Updated Mockup(s):**

| New Mockup | Path | Based On | Changes Applied |
|------------|------|----------|-----------------|
| KB Article Detail v2 | `x-ipe-docs/requirements/EPIC-049/mockups/kb-interface-v2.html` | `kb-interface-v1.html` | Added Description field to Details section and wrapped metadata styling |

## Approval

- [x] Classification approved by DAO (`DAO-111`)
- [x] Conflict analysis reviewed by DAO (`DAO-111`)
- [x] Approach approved for execution
- [x] Ready for execution

## Execution

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

**Actions Taken:**
- [x] CR document created in feature folder
- [x] Conflict analysis completed and documented
- [x] Specification Version History updated with CR link
- [x] Existing mockup referenced and new version created
- [x] Next task type set: `x-ipe-task-based-feature-refinement`

## Links

- Feature Specification: [specification.md](./specification.md)
- Requirement Details Index: [requirement-details-index.md](../../requirement-details-index.md)
- UI/UX Feedback: [Feedback-20260317-160429](../../../uiux-feedback/Feedback-20260317-160429/feedback.md)

---

## Change History

| Date | Change | By |
|------|--------|----|
| 2026-03-17 | CR-003 created — article detail sidebar now shows description when available | Ember 🔥 (DAO-108, DAO-111) |
