# DeerFlow Frontend Merge Recovery

## What This Is

This project is a brownfield recovery and alignment effort for DeerFlow frontend after branch merges introduced regressions and overwrites. It restores missing new-system capabilities while aligning visual styling to the established legacy UX language. It is primarily for the internal development team maintaining chat, artifacts, and skill bootstrap workflows.

## Core Value

Keep the frontend visually familiar while preserving and hardening new-system behavior end to end.

## Requirements

### Validated

- ✓ Chat thread routing, history rendering, and message streaming are already in production workflows — existing
- ✓ Artifact browsing and file detail rendering are already integrated into workspace flows — existing
- ✓ Core frontend/backend API integration for threads, uploads, and skills exists and is operational — existing

### Active

- [ ] Restore merge-overwritten logic from key author history (including Titan-owned behavior) where still required
- [ ] Align visual layer to legacy UI expectations without regressing new-system architecture
- [ ] Keep iframe communication and markdown download flows working in the merged codebase
- [ ] Add and stabilize E2E tests for thread reuse, input/compose, and message/history integrity
- [ ] Produce a clean staged/commit strategy that separates visual, logic, and test concerns

### Out of Scope

- Full redesign of the workspace information architecture — not required for merge recovery
- Backend feature expansion unrelated to merge regression scope — defer to future milestone
- New product features beyond current chat/artifact/skill flows — avoid scope creep during stabilization

## Context

- The repository is a brownfield monorepo with active frontend and backend development.
- Recent branch merges introduced broad frontend diffs with mixed staged/unstaged states.
- Conflict hotspots include chat routing, skill bootstrap API contracts, memory settings, and high-churn workspace components.
- Key objective from the team: visual alignment to old code style, logical alignment to new system capabilities.
- There is explicit concern that some Titan-authored logic paths were overwritten during conflict resolution.

## Constraints

- **Compatibility**: Must keep existing routes and query behaviors (`thread_id`, `isnew`, `xclaw_used`) stable — avoid breaking external entry links
- **Quality**: Changes must be split into reviewable commits by concern (style vs logic vs tests) — enables safer rollback
- **Scope**: Focus on frontend merge recovery first — do not expand into unrelated roadmap items
- **Verification**: E2E and targeted regression checks must be present before considering recovery complete

## Key Decisions

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| Preserve old visual language while keeping new-system logic primitives | Minimizes user disruption while retaining technical evolution | — Pending |
| Treat merge recovery as a dedicated milestone with explicit conflict inventory | Reduces accidental loss during ad-hoc edits | — Pending |
| Prioritize Titan-overlap files for first-pass reconciliation | Highest risk of silent behavior regression | — Pending |
| Split commits by concern area (style, logic, tests) | Improves review quality and rollback safety | — Pending |

## Evolution

This document evolves at phase transitions and milestone boundaries.

**After each phase transition** (via `/gsd-transition`):
1. Requirements invalidated? -> Move to Out of Scope with reason
2. Requirements validated? -> Move to Validated with phase reference
3. New requirements emerged? -> Add to Active
4. Decisions to log? -> Add to Key Decisions
5. "What This Is" still accurate? -> Update if drifted

**After each milestone** (via `/gsd-complete-milestone`):
1. Full review of all sections
2. Core Value check - still the right priority?
3. Audit Out of Scope - reasons still valid?
4. Update Context with current state

---
*Last updated: 2026-04-07 after initialization*