# RSS Cache Preservation Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Prevent failed RSS refreshes from replacing existing subscription cache entries with empty arrays.

**Architecture:** RSS parser failures become real failures, not empty successful results. Subscription cache actions gain a `replaceExisting` option so RSS callers can avoid destructive empty writes while non-empty updates continue normally.

**Tech Stack:** Vue 2, Vuex, JavaScript, Electron datastore handlers, Vitest or existing project test runner.

---

## Wave Plan

| Wave | Tasks | Files touched | Safe to parallelize? |
|------|-------|---------------|----------------------|
| 1 | Task 1 | `src/renderer/helpers/subscriptions.js` | single task |
| 2 | Task 2 | `src/renderer/store/modules/subscription-cache.js` | single task |
| 3 | Task 3 | `src/renderer/components/SubscriptionsVideos.vue`, `src/renderer/components/SubscriptionsShorts.vue`, `src/renderer/components/SubscriptionsLive.vue` | single task |
| 4 | Task 4 | test files discovered from project test layout | single task |

## File Structure

- `src/renderer/helpers/subscriptions.js`: owns RSS parsing and should distinguish invalid RSS from a valid empty RSS feed.
- `src/renderer/store/modules/subscription-cache.js`: owns persistence and in-memory cache mutation for subscription cache entries.
- `src/renderer/components/SubscriptionsVideos.vue`: owns subscription video RSS refresh calls.
- `src/renderer/components/SubscriptionsShorts.vue`: owns shorts RSS refresh calls.
- `src/renderer/components/SubscriptionsLive.vue`: owns live RSS refresh calls.

### Task 1: RSS Parser Failure Semantics

**Wave:** 1
**Blocks:** Task 3
**Blocked by:** —

**Files:**
- Modify: `src/renderer/helpers/subscriptions.js`

- [ ] **Step 1: Update parser failure behavior**

Change `parseYouTubeRSSFeed` so XML parser errors or missing channel metadata throw an error. Keep valid feeds with zero `<entry>` nodes as `{ name, videos: [] }`.

- [ ] **Step 2: Manually verify parser branches**

Run targeted tests if available. If no existing unit test harness covers this helper, verify through the component tests added in Task 4.

### Task 2: Non-Destructive Cache Writes

**Wave:** 2
**Blocks:** Task 3
**Blocked by:** —

**Files:**
- Modify: `src/renderer/store/modules/subscription-cache.js`

- [ ] **Step 1: Add `replaceExisting` guard to cache actions**

For video, shorts, and live cache update actions, accept `replaceExisting = true`. If `replaceExisting` is false and incoming `videos` is an empty array, return without calling datastore handlers or committing cache mutations.

- [ ] **Step 2: Preserve default behavior**

Do not change existing callers unless they opt into `replaceExisting: false`.

### Task 3: Mark RSS Refresh Writes as Non-Destructive

**Wave:** 3
**Blocks:** Task 4
**Blocked by:** Task 1, Task 2

**Files:**
- Modify: `src/renderer/components/SubscriptionsVideos.vue`
- Modify: `src/renderer/components/SubscriptionsShorts.vue`
- Modify: `src/renderer/components/SubscriptionsLive.vue`

- [ ] **Step 1: Update RSS cache dispatches**

For dispatches fed by RSS refresh results, pass `replaceExisting: false`.

- [ ] **Step 2: Keep non-RSS API refreshes unchanged**

Do not pass `replaceExisting: false` for non-RSS refresh paths that may legitimately clear stale results.

### Task 4: Verification

**Wave:** 4
**Blocks:** —
**Blocked by:** Task 3

**Files:**
- Test: existing test files if present, otherwise verify with focused lint/test commands.

- [ ] **Step 1: Run relevant unit tests**

Run the narrowest available test command for renderer helpers/store modules.

- [ ] **Step 2: Run lint or full test command if narrow tests are unavailable**

Use the project's package scripts and report any failures that are unrelated to this change.