making the mess clean plans added
This commit is contained in:
hamid
@@ -0,0 +1,148 @@
|
||||
# Phase 0 — Inventory & scaffold
|
||||
|
||||
**Depends on:** nothing · **Blocks:** every other phase · **Size:** one session
|
||||
|
||||
## Goal
|
||||
|
||||
Before anything is moved, merged, or deleted, produce two things:
|
||||
|
||||
1. **A disposition for every one of the ~260 markdown files in the repo** — so that "summarize
|
||||
without losing data" is a checkable claim rather than a hope.
|
||||
2. **The empty `docs/` skeleton** with a real entry point, so later phases have somewhere to write.
|
||||
|
||||
Plus one piece of housekeeping every later phase needs: a **fresh OpenAPI snapshot**, because the
|
||||
committed one is 16 days behind the server code.
|
||||
|
||||
This phase writes almost no prose. It is a survey.
|
||||
|
||||
---
|
||||
|
||||
## Inputs
|
||||
|
||||
- The whole repo. Specifically: `dev/` (199 files), `product/` (48), root (4), `client/` (5),
|
||||
`server/` (6), `telegram-otp-bot/` (2), `.claude/skills/` (1), `.githooks/` (1).
|
||||
- [`../README.md`](README.md) — the target tree and the decisions.
|
||||
|
||||
## Outputs
|
||||
|
||||
| File | What it is |
|
||||
| --- | --- |
|
||||
| `docs/_plan/inventory.md` | The disposition table — every markdown file, one row |
|
||||
| `docs/README.md` | The single entry point: a map of `docs/`, `product/`, `archive/` and what belongs where |
|
||||
| `docs/rules/index.md` `docs/integration/index.md` `docs/flows/index.md` `docs/status/index.md` `docs/roadmap/index.md` | Stub indexes, each with a one-line purpose and a "populated by phase N" note |
|
||||
| `docs/integration/openapi/swagger.v1.json` | Regenerated from the running server |
|
||||
| `docs/_plan/open-contradictions.md` | Running list of doc-vs-doc and doc-vs-code conflicts spotted during the survey — later phases resolve these |
|
||||
|
||||
---
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. Build the inventory
|
||||
|
||||
Walk every `.md` file (exclude `node_modules`, `bin`, `obj`, `.git`). For each, record:
|
||||
|
||||
| Column | Meaning |
|
||||
| --- | --- |
|
||||
| `path` | repo-relative |
|
||||
| `bytes` | size |
|
||||
| `last commit` | `git log -1 --format=%ad --date=short -- <path>` |
|
||||
| `kind` | `rule` · `reference` · `contract` · `plan` · `report` · `history` · `business` · `ops` · `feedback` |
|
||||
| `disposition` | `keep-as-is` · `move` · `distill` · `merge-into` · `archive` · `delete` |
|
||||
| `target` | where its content ends up (a `docs/…` path, or `archive/…`) |
|
||||
| `owner phase` | which phase (1–7) handles it |
|
||||
| `live facts?` | `yes` / `no` — does it contain anything not yet captured elsewhere? |
|
||||
|
||||
Rules for assigning disposition:
|
||||
|
||||
- **`dev/phases/backend/*` and `dev/phases/frontend/*`** (32 files, ~1 MB): these are *prompts that
|
||||
were already executed*. Disposition `archive`. But scan each for **decisions and constraints stated
|
||||
in the prompt that are not visible in the code** — those are `live facts: yes` and go to Phase 1
|
||||
(if a rule) or Phase 4 (`decisions.md`).
|
||||
- **`dev/shared-working-context/reports/*` (50 files)**: `archive`, but every "Follow-ups for later
|
||||
phases" / "Deferred" / "Known gap" section is a live fact for **Phase 4**. Extract the section
|
||||
headings now; Phase 4 reads them in detail.
|
||||
- **`dev/shared-working-context/*/STATUS.md`** (86 KB combined): `distill` → Phase 4 (`decisions.md`
|
||||
+ `implemented.md`), then `archive`.
|
||||
- **`dev/shared-working-context/frontend/requests/for-backend.md`** (67 REQs): `distill` → Phase 4.
|
||||
- **`dev/post-phase/hardening/issues.md`** (18 open items): `distill` → Phase 4, **with
|
||||
re-verification** — the UI and refinement chains ran after this file was written and some items are
|
||||
probably already fixed.
|
||||
- **`dev/contracts/**`**: `move` → `docs/integration/` — Phase 2 owns it, and refreshes it against code.
|
||||
- **`dev/post-phase/manual-testing-plan.md`** + **`refinement/RUNBOOK.md`**: `distill` → Phase 3
|
||||
(`docs/flows/testing-setup.md` + the per-flow files). Both are stale on secrets handling.
|
||||
- **`dev/manual-testing/iteration-*/`**: `distill` → Phase 4 (unfinished items) then `archive`
|
||||
(**keep the PNG screenshots** — they are the only visual record of the pre-overhaul UI).
|
||||
- **`product/**`**: `keep-as-is`, every one. Not this chain's business.
|
||||
- **`client/CLAUDE.md`, `server/CLAUDE.md`, `server/CONVENTIONS.md`, `client/messages/STYLE.md`,
|
||||
`dev/phases/_shared/*`, `dev/contracts/conventions/*`, `.claude/skills/*/SKILL.md`**: `distill` →
|
||||
Phase 1.
|
||||
- **`DEPLOY.md`**: `keep-as-is` at root (it is the deploy *procedure* and it is current) — but Phase 2
|
||||
fixes its stale `user-secrets` reference and Phase 2's `topology.md` links to it.
|
||||
- **`Prompt.md`** (0 bytes): `delete`.
|
||||
- **`temp/swagger.json`** (stale duplicate): `delete` — Phase 2 replaces it.
|
||||
- **`client/graphify-out/GRAPH_REPORT.md`, `server/graphify-out/GRAPH_REPORT.md`**: generated tool
|
||||
output. Decide `keep-as-is` if the tool is still used, else `delete`; check `.gitignore` first.
|
||||
|
||||
### 2. Log contradictions as you go
|
||||
|
||||
Write `docs/_plan/open-contradictions.md` with one row per conflict: *claim A (file:line) vs claim B
|
||||
(file:line or code:line) — unresolved*. Seed it with the ones already known:
|
||||
|
||||
- **`user-secrets` is required** (18 files) vs **`user-secrets` was removed and the store isn't read**
|
||||
(root [CLAUDE.md](../../CLAUDE.md) §6, commit `5885280`).
|
||||
- **`dev/contracts/` describes the API** (frozen 2026-07-13) vs **`server/src`** (through 2026-07-28).
|
||||
- **Design language in [.claude/skills/frontend-designer/SKILL.md](../../.claude/skills/frontend-designer/SKILL.md) §§1–7**
|
||||
vs **[client/CLAUDE.md](../../client/CLAUDE.md) "Theme System" / "Anti-patterns"** — overlapping, possibly divergent.
|
||||
- **Both** vs **the reality after iterations 1–2** (mobile-scoped shell, bottom nav, react-hook-form,
|
||||
new icon set) — the skill predates that overhaul.
|
||||
- **18 hardening items open** (2026-07-16) vs **UI phases 0–13 and the deploy commits that ran after**.
|
||||
|
||||
Do **not** resolve these here. Phase 0 only finds them.
|
||||
|
||||
### 3. Regenerate the OpenAPI snapshot
|
||||
|
||||
Boot the server and capture the live swagger document:
|
||||
|
||||
```bash
|
||||
cd server && dotnet run --project src/API/Baya.Web.Api/Baya.Web.Api.csproj
|
||||
# then, from another shell:
|
||||
curl -sk https://localhost:5002/swagger/v1/swagger.json -o docs/integration/openapi/swagger.v1.json
|
||||
```
|
||||
|
||||
Record in the file's sibling `README.md`: the date, the commit, and the endpoint count. Diff the
|
||||
endpoint *paths* against the old `dev/contracts/openapi/swagger.v1.json` and write the added/removed
|
||||
list into `docs/_plan/open-contradictions.md` — Phase 2 uses it as its worklist.
|
||||
|
||||
If the server will not boot (config, DB reachability), **stop and report** rather than guessing. A
|
||||
stale snapshot is what caused half of this mess.
|
||||
|
||||
### 4. Scaffold `docs/`
|
||||
|
||||
Create the directories and stub index files from the target tree in [`README.md`](README.md). Each
|
||||
stub is ~10 lines: what lives here, which phase fills it, and a `> Populated by phase N — not yet
|
||||
written` banner. `docs/README.md` is the only one with real content: the map, and the
|
||||
`product/` vs `docs/` vs `archive/` rule.
|
||||
|
||||
Do **not** create `archive/` yet — Phase 6 does that, once there is something safe to put in it.
|
||||
|
||||
---
|
||||
|
||||
## Verification
|
||||
|
||||
- [ ] `docs/_plan/inventory.md` has a row for every `.md` file the survey walked; the count matches
|
||||
`find . -name "*.md" -not -path "./node_modules/*" … | wc -l` (~260 at baseline).
|
||||
- [ ] No row has an empty `disposition` or `owner phase`.
|
||||
- [ ] Every row with `live facts: yes` names the phase that will extract them.
|
||||
- [ ] `docs/integration/openapi/swagger.v1.json` exists and its endpoint count is recorded.
|
||||
- [ ] Every stub index exists and says which phase fills it.
|
||||
- [ ] Nothing outside `docs/` was modified, except deleting `Prompt.md` and `temp/swagger.json`.
|
||||
|
||||
## Definition of done
|
||||
|
||||
You can answer, for any markdown file in the repo, "where does this end up and who handles it?"
|
||||
without re-reading the file.
|
||||
|
||||
## Handoff
|
||||
|
||||
_(filled in by the agent that runs this phase — file counts, surprises, anything that changes a later
|
||||
phase's scope)_
|
||||
Reference in New Issue
Block a user