# Frontend Debt Audit and Backlog 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:** Audit the current frontend technical debt, classify what is closed vs open, and turn the open work into a prioritized backlog with roadmap/inbox sync.

**Architecture:** This is a docs-first workflow. First collect evidence from the codebase and existing docs, then synthesize the findings into a compact backlog, then update `inbox.md` and `roadmap.md` so the project docs match the current frontend state. No runtime code changes are part of this feature.

**Tech Stack:** Markdown docs, git, targeted source searches, repo conventions, existing frontend specs/plans.

---

### Task 1: Collect audit evidence

**Files:**
- Read: `docs/inbox.md`
- Read: `docs/roadmap.md`
- Read: `docs/features/frontend-fsd-cleanup/spec.md`
- Read: `docs/features/frontend-fsd-cleanup/plan.md`
- Read: `docs/features/frontend-fsd-final/spec.md`
- Read: `docs/features/frontend-fsd-final/plan.md`
- Read: `docs/features/frontend-infrastructure-tooling/spec.md`
- Read: `docs/features/frontend-infrastructure-tooling/plan.md`
- Read: `apps/frontend/package.json`
- Search: `apps/frontend/src/**/*`

- [ ] **Step 1: Verify the current frontend debt signals**

Run:

```bash
rg -n "TODO|FIXME|@ts-ignore|eslint-disable|\.\./" apps/frontend/src docs/features
```

Expected: either no matches in `apps/frontend/src`, or matches that are explicitly explainable as already planned work in `docs/features/`.

- [ ] **Step 2: Read the current frontend specs and roadmap entries**

Run:

```bash
git grep -n "frontend" docs/features docs/inbox.md docs/roadmap.md
```

Expected: a compact list of the currently documented frontend workstreams and cleanup items.

### Task 2: Synthesize the backlog

**Files:**
- Modify: `docs/features/frontend-debt-audit/spec.md`
- Modify: `docs/features/frontend-debt-audit/plan.md`
- Create/Modify: `docs/features/frontend-debt-audit/tasks.md`

- [ ] **Step 1: Record the audit clusters in the feature docs**

Capture the open-work clusters as separate follow-up candidates under the `Frontend Debt Backlog` epic, at minimum:

- docs synchronization / stale specification cleanup;
- frontend infrastructure hardening;
- shared API and boundary cleanup.
- frontend test hygiene.

Keep each cluster independent and do not merge implementation work into the audit feature itself.

- [ ] **Step 2: Write the audit tasks file**

`docs/features/frontend-debt-audit/tasks.md` should contain a checkbox list with the following work items:

1. reconcile current state against docs;
2. classify open vs closed items;
3. split the open items into follow-up features;
4. update inbox and roadmap;
5. verify the documentation diff is self-consistent.

### Task 3: Sync inbox and roadmap

**Files:**
- Modify: `docs/inbox.md`
- Modify: `docs/roadmap.md`

- [ ] **Step 1: Add the audit note to inbox**

Add a short inbox entry that captures the working hypothesis: frontend maintenance should now be handled as a small set of explicit follow-up features instead of one monolithic cleanup effort.

- [ ] **Step 2: Add or update the roadmap candidate entry**

Add a roadmap item for `frontend-debt-audit` and, if needed, keep the existing infrastructure tooling entry as a follow-up candidate rather than a live implementation promise.

### Task 4: Self-check the documentation set

**Files:**
- Read: `docs/features/frontend-debt-audit/spec.md`
- Read: `docs/features/frontend-debt-audit/plan.md`
- Read: `docs/features/frontend-debt-audit/tasks.md`
- Read: `docs/inbox.md`
- Read: `docs/roadmap.md`

- [ ] **Step 1: Check for contradictions**

Confirm that the spec only promises audit/backlog work and does not imply code changes.

- [ ] **Step 2: Check for missing follow-up clusters**

Confirm that every open frontend debt item from the audit is mapped into one of the follow-up clusters or explicitly marked as deferred.

- [ ] **Step 3: Verify the diff is docs-only**

Run:

```bash
git diff --name-only
```

Expected: only files under `docs/` changed.