From 3e054ee6c4b1173486a348a949a39bcd8d9899d5 Mon Sep 17 00:00:00 2001 From: Sergey Krylov Date: Wed, 24 Jun 2026 07:10:40 +0300 Subject: [PATCH] docs(frontend): add docs sync plan --- docs/features/frontend-docs-sync/plan.md | 108 ++++++++++++++++++++++ docs/features/frontend-docs-sync/tasks.md | 21 +++++ 2 files changed, 129 insertions(+) create mode 100644 docs/features/frontend-docs-sync/plan.md create mode 100644 docs/features/frontend-docs-sync/tasks.md diff --git a/docs/features/frontend-docs-sync/plan.md b/docs/features/frontend-docs-sync/plan.md new file mode 100644 index 0000000..9af42ae --- /dev/null +++ b/docs/features/frontend-docs-sync/plan.md @@ -0,0 +1,108 @@ +# Frontend Docs Sync 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:** Bring `docs/inbox.md`, `docs/roadmap.md`, and frontend feature docs back in sync with the current frontend state so the docs reflect reality, not intermediate migration history. + +**Architecture:** This is a docs-only maintenance workflow. First reconcile the current state of frontend docs with the codebase and with each other, then remove stale ideas or mark them as already covered, then verify the resulting documentation set is internally consistent. No runtime code changes are part of this feature. + +**Tech Stack:** Markdown docs, git, targeted source search, existing frontend specs/plans, existing roadmap/inbox conventions. + +--- + +### Task 1: Reconcile current docs state + +**Files:** +- Read: `docs/inbox.md` +- Read: `docs/roadmap.md` +- Read: `docs/epics/FrontendDebtBacklog.md` +- Read: `docs/features/frontend-debt-audit/spec.md` +- Read: `docs/features/frontend-debt-audit/plan.md` +- Read: `docs/features/frontend-fsd-cleanup/spec.md` +- Read: `docs/features/frontend-fsd-final/spec.md` +- Read: `docs/features/frontend-infrastructure-tooling/spec.md` +- Search: `apps/frontend/src/**/*` + +- [ ] **Step 1: Confirm the current frontend state that docs must reflect** + +Run: + +```bash +rg -n "TODO|FIXME|@ts-ignore|eslint-disable|\.\./" apps/frontend/src docs/features docs/inbox.md docs/roadmap.md +``` + +Expected: matches, if any, are explainable by already documented work or are limited to the maintenance docs being updated. + +- [ ] **Step 2: Identify stale or duplicated documentation** + +Run: + +```bash +git grep -n "frontend" docs/inbox.md docs/roadmap.md docs/features +``` + +Expected: a list of items that are either still active ideas, already-backed-up features, or stale intermediate notes. + +### Task 2: Update inbox and roadmap wording + +**Files:** +- Modify: `docs/inbox.md` +- Modify: `docs/roadmap.md` + +- [ ] **Step 1: Rewrite inbox entries that are now covered by specs** + +Keep only the ideas that are still hypotheses. Any frontend cleanup idea that now has its own spec must be rephrased as a follow-up or removed from inbox. + +- [ ] **Step 2: Ensure roadmap lists only current candidates** + +Keep the roadmap focused on concrete feature specs and the `Frontend Debt Backlog` epic. Remove vague duplicate wording that re-describes already-specified work. + +### Task 3: Align feature docs with the epic + +**Files:** +- Modify: `docs/features/frontend-debt-audit/spec.md` +- Modify: `docs/features/frontend-docs-sync/spec.md` +- Modify: `docs/features/frontend-infrastructure-hardening/spec.md` +- Modify: `docs/features/frontend-shared-boundary-cleanup/spec.md` +- Modify: `docs/features/frontend-test-hygiene/spec.md` +- Modify: `docs/epics/FrontendDebtBacklog.md` + +- [ ] **Step 1: Ensure each feature spec references the epic** + +All four feature specs should clearly state that they belong to `Frontend Debt Backlog` and that they are follow-up work after the audit. + +- [ ] **Step 2: Keep the epic order explicit** + +Make sure the order in the epic remains: + +1. `frontend-docs-sync` +2. `frontend-infrastructure-hardening` +3. `frontend-shared-boundary-cleanup` +4. `frontend-test-hygiene` + +### Task 4: Self-check the docs set + +**Files:** +- Read: `docs/inbox.md` +- Read: `docs/roadmap.md` +- Read: `docs/epics/FrontendDebtBacklog.md` +- Read: `docs/features/frontend-docs-sync/spec.md` +- Read: `docs/features/frontend-debt-audit/spec.md` + +- [ ] **Step 1: Check for contradictions** + +Confirm that docs-only work is not described as runtime implementation and that the epic does not duplicate roadmap entries unnecessarily. + +- [ ] **Step 2: Check spec coverage** + +Confirm that the docs sync feature covers inbox, roadmap, and spec linkage, while audit/backlog remains a separate feature. + +- [ ] **Step 3: Verify the diff is docs-only** + +Run: + +```bash +git diff --name-only +``` + +Expected: only `docs/` files changed. diff --git a/docs/features/frontend-docs-sync/tasks.md b/docs/features/frontend-docs-sync/tasks.md new file mode 100644 index 0000000..17c85b0 --- /dev/null +++ b/docs/features/frontend-docs-sync/tasks.md @@ -0,0 +1,21 @@ +# Frontend Docs Sync — tasks + +Статус: pending + +## 1. Синхронизировать inbox и roadmap + +- [ ] Прочитать `docs/inbox.md` и убрать или переформулировать записи, которые уже покрыты отдельными specs +- [ ] Прочитать `docs/roadmap.md` и оставить только актуальные candidate features +- [ ] Проверить, что `Frontend Debt Backlog` и его подфичи описаны без дублирования смысла + +## 2. Привести frontend docs к текущему состоянию + +- [ ] Проверить `docs/features/frontend-debt-audit/spec.md` и `docs/features/frontend-docs-sync/spec.md` на согласованность +- [ ] Проверить `docs/features/frontend-infrastructure-hardening/spec.md`, `docs/features/frontend-shared-boundary-cleanup/spec.md`, `docs/features/frontend-test-hygiene/spec.md` на явную связь с epic +- [ ] Сверить порядок реализации в `docs/epics/FrontendDebtBacklog.md` + +## 3. Финальная проверка + +- [ ] Убедиться, что документация не обещает изменение runtime-поведения +- [ ] Проверить `git diff --name-only` и подтвердить, что изменены только `docs/`-файлы +- [ ] Убедиться, что в `docs/inbox.md` не осталось устаревших миграционных заметок без статуса