making the mess clean plans added
This commit is contained in:
hamid
@@ -0,0 +1,121 @@
|
||||
# Phase 5 — Roadmap & technical requirements
|
||||
|
||||
**Depends on:** Phase 4 · **Size:** one session
|
||||
|
||||
## Goal
|
||||
|
||||
Answer "what next?" — recording every already-decided future item **and** proposing a sequenced
|
||||
order, with the technical prerequisites each step needs. The ordering is a proposal you can overrule;
|
||||
the recording is not negotiable.
|
||||
|
||||
---
|
||||
|
||||
## Inputs
|
||||
|
||||
- `docs/status/backlog.md` and `implemented.md` — Phase 4's output, the ground truth
|
||||
- `docs/flows/index.md` — what's mocked vs built
|
||||
- The **deferrals with pull-triggers** from the STATUS logs: Elasticsearch `INurseSearch`, real
|
||||
SMS/push `INotificationDispatcher`, the analytics pipeline, the holiday feed, **8 unbuilt product
|
||||
tables**, and the refinement-phase-9 items 9.7–9.11
|
||||
- [product/notes/future-ideas.md](../../product/notes/future-ideas.md) and
|
||||
[open-questions.md](../../product/notes/open-questions.md) — including PWA/Workbox caching
|
||||
- ui-phase-13's follow-ups: **tier (c)** — guest search + public nurse profiles (REQ-066/067), blocked
|
||||
on a backend phase **and an explicit privacy sign-off on the nurse-profile field list**; the OG
|
||||
image Persian variant
|
||||
- Root [CLAUDE.md](../../CLAUDE.md) §6 + [DEPLOY.md](../../DEPLOY.md) "Going to Production" — the
|
||||
credential-rotation obligation
|
||||
- `product/business/*` — anything specified but never built
|
||||
- `product/research/*` — go-to-market, legal landscape (informs sequencing, not scope)
|
||||
|
||||
## Outputs
|
||||
|
||||
```
|
||||
docs/roadmap/
|
||||
index.md the proposed sequence + the reasoning, in one page
|
||||
next-up.md the next 3-5 units of work, each spec'd enough to start
|
||||
deferred.md recorded, with the trigger that pulls each one forward
|
||||
tech-debt.md what must be paid before scale, and what it costs to defer
|
||||
pre-launch.md the hard gate before real users touch this
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. `pre-launch.md` first — it's the one with a deadline
|
||||
|
||||
Everything that must be true before a real user with real money uses the platform. Known already:
|
||||
|
||||
- **Rotate the committed credentials** and move the secret half out of git. The repo currently
|
||||
contains live credentials by deliberate pre-launch decision. Note the exception: `Seams:FieldEncryption:Key`
|
||||
/ `:HashKey` decrypt existing PII and derive the phone-lookup hash — rotating those requires a data
|
||||
migration, not a config edit. Spell out that migration as its own item.
|
||||
- **Real external rails** — which seams are still mocked in production config (payment gateway, SMS,
|
||||
BNPL provider, object storage). Phase 3's mock-vs-real map is the input; this is the list of seams
|
||||
that must flip.
|
||||
- **Running as Development in production** — `DEPLOY.md` documents this as a deliberate trade.
|
||||
State what it implies (gRPC reflection, dev endpoints such as `/dev/last_otp`, seeding behaviour,
|
||||
log verbosity) and what must change.
|
||||
- Anything Phase 4 marked `blocker`.
|
||||
- Legal/tax items from `product/business/13-tax-invoicing-and-legal.md` that are code-side.
|
||||
|
||||
Each item: what, why it blocks launch, roughly what it takes.
|
||||
|
||||
### 2. `deferred.md` — record faithfully, don't re-decide
|
||||
|
||||
One row per deferral: **item · why deferred · the pull-trigger (the condition that makes it
|
||||
necessary) · rough size · where it was decided**. The pull-triggers already exist in the STATUS logs
|
||||
— preserve them verbatim in substance. A deferral with a trigger is a decision; a deferral without
|
||||
one is just a forgotten task, so any you find without a trigger, give one.
|
||||
|
||||
Include the 8 unbuilt product tables, named individually.
|
||||
|
||||
### 3. `tech-debt.md`
|
||||
|
||||
Debt is different from backlog: it doesn't block a flow, it raises the cost of everything after it.
|
||||
Candidates to assess: the single-instance in-process scheduler; search without Elasticsearch; the
|
||||
absence of E2E tests over the money paths; the remaining raw-state forms; the Windows-generated
|
||||
client lockfile wrinkle in `DEPLOY.md`; test coverage asymmetry between the two projects.
|
||||
|
||||
For each: what it costs now, what it costs at 10× usage, and the trigger to pay it.
|
||||
|
||||
### 4. `next-up.md` — the opinionated part
|
||||
|
||||
Three to five units of work, each with: goal, why now, what it unblocks, technical prerequisites,
|
||||
affected flows, rough size, and the backlog ids it closes. Enough that a fresh agent session could
|
||||
start one without re-deriving the context.
|
||||
|
||||
**Sequencing principle to apply, and state explicitly in `index.md`:** the product's own promise is
|
||||
trust-first and money-holding. So the order is (1) anything that makes a *money or trust* flow lie to
|
||||
a user, (2) anything that makes a built flow unusable, (3) anything that makes a mocked flow real,
|
||||
(4) new surface area. Tier (c) guest search is new surface — it ranks below making the authenticated
|
||||
flows honest, regardless of how visible it is.
|
||||
|
||||
Where a proposed item conflicts with something in `product/`, say so and defer to `product/`.
|
||||
|
||||
### 5. `index.md`
|
||||
|
||||
The one-page sequence: a table of the proposed order with rationale per step, plus the standing
|
||||
answer to "what are we not doing, and why" (a pointer to `deferred.md`). Mark clearly which parts are
|
||||
**recorded decisions** and which are **this document's proposal** — the reader must be able to tell
|
||||
your judgement from the project's.
|
||||
|
||||
---
|
||||
|
||||
## Verification
|
||||
|
||||
- [ ] Every `deferred` item in `docs/status/backlog.md` appears in `deferred.md` with a trigger.
|
||||
- [ ] Every recorded deferral from the STATUS logs is present, including the 8 unbuilt tables.
|
||||
- [ ] `pre-launch.md` covers credential rotation, every still-mocked production seam, and the
|
||||
Development-in-production trade.
|
||||
- [ ] Every `next-up.md` item names the backlog ids it closes and the flows it affects.
|
||||
- [ ] Proposal is visibly distinguished from record.
|
||||
|
||||
## Definition of done
|
||||
|
||||
You can pick the next piece of work in five minutes, and you can explain to someone else why it's
|
||||
that piece and not another.
|
||||
|
||||
## Handoff
|
||||
|
||||
_(filled in by the agent that runs this phase)_
|
||||
Reference in New Issue
Block a user