112 lines
4.1 KiB
Markdown
112 lines
4.1 KiB
Markdown
# 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.
|