109 lines
4.0 KiB
Markdown
109 lines
4.0 KiB
Markdown
# 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.
|