# Consolidated Refactoring Plan (From 5-Agent Audit)

## Inputs
- Software architect report
- Frontend SolidJS report
- Backend Rust report
- Technical lead report
- QA integration/E2E report

## Clarifications Required Before Implementation
1. Theme creation contract:
   - Draft allowed with empty topic/categories, or mandatory valid values on create?
2. Schedule GET contract:
   - `404` when absent, or `200` with `null`?
3. Canonical theme defaults:
   - `max_items_per_category`/`summary_length` should be 4/3 or 5/2?
4. Theme scoping policy:
   - Are import/export/preferred operations always theme-scoped?
5. Terminology:
   - Fallback category label (`Autre` vs `Divers`)
   - Source-link extraction mode still required or deprecated

## Executive Summary
- The codebase has good foundations (clear layering intent, provider abstraction, strong backend unit coverage), but there is significant **spec/implementation drift** in theme/schedule/source contracts.
- Highest risk is correctness, not style: multi-theme data scoping and contract mismatches can break core user flows.
- Complexity is concentrated in a few large files; decomposition should happen only after correctness and reliability fixes.

## Priority Backlog

## P0 (Immediate)
1. Fix theme-scoped source correctness:
   - Ensure bulk/CSV import preserves `theme_id`
   - Scope preferred-source updates by theme
   - Make CSV export theme-aware
2. Fix theme creation flow contract mismatch:
   - Align UI create payload and backend validation
3. Add tests for P0 flows:
   - Multi-theme isolation integration tests
   - End-to-end create theme happy path

## P1 (Next)
1. Unify schedule API contract across docs/backend/frontend/tests.
2. Align theme defaults across migration/backend/frontend/docs.
3. Harden scheduler reliability:
   - deterministic integration tests
   - timeout parity with manual generation
4. Add deterministic SSE progress integration tests.
5. Add Brave fallback/rate-limit/max-age pipeline integration coverage.

## P2 (Then)
1. Decompose backend synthesis pipeline module by phase.
2. Decompose large frontend pages (`ThemeManager`, `Providers`, `Settings`) into hooks/components.
3. Remove direct `fetch` in pages; enforce API client boundary.
4. Remove hardcoded UI strings; enforce i18n conventions.
5. Replace silent `.ok()` error swallowing with warn/metric patterns.

## P3 (Opportunistic)
1. Convention enforcement via lint/codemods.
2. Clean reactive anti-patterns (render-time side effects).
3. Performance optimizations (N+1 phase-2 checks, set-based inserts).

## Suggested Delivery Sequence (For Follow-up Team)
1. Decision sprint (0.5-1 day): finalize 5 open clarifications.
2. Correctness sprint (1-2 weeks): all P0 + tests merged.
3. Reliability sprint (1 week): scheduler/SSE/fallback/rate-limit/max-age tests + runtime parity fixes.
4. Simplification sprint (1-2 weeks): decomposition of largest backend/frontend hotspots.
5. Governance sprint (2-3 days): lint/conformance checks to prevent drift.

## Acceptance Criteria
1. No spec drift for theme/schedule/source contracts (tests and docs aligned).
2. Multi-theme operations fully isolated and verifiably correct.
3. Scheduled generation reliability covered by deterministic integration tests.
4. SSE and fallback branches have deterministic coverage in CI.
5. Largest hotspots reduced in size and complexity with no behavior regression.