# Architecture Quality 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:** turn the current frontend/backend architecture audit into a prioritized, docs-backed backlog of follow-up refactor features.

**Architecture:** this feature is docs-only. We will not change runtime code; instead we will reconcile source-of-truth docs with the current codebase, classify findings by subsystem, and publish a backlog that can be split into future single-subsystem refactor features.

**Tech Stack:** Markdown docs in `docs/`, published Docusaurus docs in `apps/docs/docs/`, existing repo search tooling.

---

### Task 1: Consolidate source material

**Files:**
- Read: `docs/research/2026-06-25-backend-audit.md`
- Read: `docs/features/frontend-debt-audit/spec.md`
- Read: `docs/features/backend-architecture-refactor/spec.md`
- Read: `apps/docs/docs/frontend/overview.md`
- Read: `apps/docs/docs/backend/modules.md`
- Read: `docs/roadmap.md`

- [ ] **Step 1: Capture current architecture findings**

Use the existing audit docs plus current source/docs to confirm which items are already closed, which are stale in docs, and which are still open.

- [ ] **Step 2: Check for overlap with completed work**

Verify that the backlog does not reintroduce items already covered by completed refactor docs or published architecture pages.

### Task 2: Write the backlog spec

**Files:**
- Create: `docs/features/architecture-quality-backlog/spec.md`

- [ ] **Step 1: Write the backlog scope**

Document that this feature is docs-only and only produces a prioritized backlog, not runtime code changes.

- [ ] **Step 2: List the backlog items**

Describe the five backlog items in priority order:

```markdown
1. Documentation Source-of-Truth Sync
2. Backend Service Boundary Cleanup
3. Backend Contract Type-Safety Hardening
4. Frontend Session Model Simplification
5. Frontend Query-Key and API Wrapper Hardening
```

- [ ] **Step 3: State the acceptance criteria**

Require explicit risk/dependency notes for every backlog item and a no-runtime-code-change constraint.

### Task 3: Write the execution plan

**Files:**
- Create: `docs/features/architecture-quality-backlog/plan.md`

- [ ] **Step 1: Describe the doc-only architecture**

Explain that the implementation is a documentation workflow: inventory, classify, prioritize, publish.

- [ ] **Step 2: Define the file responsibilities**

State which docs are the source material, which doc is the canonical backlog, and which docs will be updated to reflect it.

- [ ] **Step 3: Add the validation checklist**

Require a final consistency pass against code and existing docs before the backlog is considered ready.

### Task 4: Write the task breakdown

**Files:**
- Create: `docs/features/architecture-quality-backlog/tasks.md`

- [ ] **Step 1: Create small independent doc tasks**

Break the work into small, reviewable documentation tasks:

```markdown
- [ ] Inventory the current frontend/backend architecture debt
- [ ] Remove completed or stale items from the backlog
- [ ] Prioritize the remaining backlog by risk and dependency
- [ ] Cross-link the backlog with roadmap and epics
- [ ] Run a final docs consistency review
```

- [ ] **Step 2: Ensure no code tasks are listed**

This feature must not include implementation tasks for `apps/frontend/src/**` or `apps/backend/src/**`.

- [ ] **Step 3: Reference the docs that will be linked**

Use `docs/roadmap.md` plus the relevant epic/feature docs as the cross-link targets for the published backlog.

### Task 5: Final review

**Files:**
- Read: `docs/features/architecture-quality-backlog/spec.md`
- Read: `docs/features/architecture-quality-backlog/plan.md`
- Read: `docs/features/architecture-quality-backlog/tasks.md`

- [ ] **Step 1: Check for scope creep**

Ensure the documents describe backlog creation only, not code refactoring.

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

Verify that the priority order, scope, and acceptance criteria match across all three files.