moex-vibe/docs/features/architecture-quality-backlog/plan.md

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:

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:

- [ ] 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.