Files
Bike-Tinder/docs/PLAN.md

76 lines
6.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# PLAN — Bike-Tinder
**Status:** Build phase — Phase 1 complete (2026-11-10); Phase 2 not yet started. Phases are gated: each lands, is verified, then the next begins. Glenn's standing rule applies — "pause" stops all spend immediately.
## v1 goal
A single-source, single-user, tailnet-only Tinder-style PWA on the Rotarran: nightly-updated catalog, swipe deck (Like / Nope / Maybe), full editable list, taste-ranked ordering.
## Phase 0 — Planning
- [x] Engineering consultation (Torres) → memo
- [x] Design docs in this repo: SOURCES, DESIGN, DATA-MODEL, RANKING, UI-SPEC
- [x] Glenn's calls (2026-11-10): v1 source = **Kijiji** · deck = show all, taste-ranked · new-bike feed = in-app badge only
- [x] Repo housekeeping (2026-11-10): branches `dev`/`main`/`release` · dedicated `bike-tinder-import` cron (parked for deploy) · stack-owned Tailscale sidecar in the deploy plan
- [x] Build gate opened — Glenn green-lit (2026-11-10)
- **Exit criteria:** docs merged to `main` (done 2026-11-10); source decision recorded in `SOURCES.md`.
## Phase 1 — Data spine
**Status: complete (2026-11-10).** Built by Torres on `dev` (`5bf180c..19e46cd`), independently re-verified by Alex (fresh-DB import x2, deck CLI, 8/8 selfcheck), merged to `main` (`d890dcd`). Live result: 640 rows → 560 active + 80 dup; deck top = Indian Scout family (91) then Vulcan 900 Classic (73).
*(Build work lands on `dev`; verified milestones merge to `main`; deploys track `release`.)*
- [x] DB schema + migrations (SQLite)
- [x] Importer: source catalog → upsert into DB (new / changed / gone states)
- [x] Cold-start scoring wired (existing rubric logic)
- [x] Proof: CLI query shows a ranked, deduped queue from the real live catalog
- **Exit criteria:** importer runs clean twice in a row (done — idempotent); counts reconcile against the source (done — 560+0+80=640); no schema surprises (done).
**Carried into Phase 2 from P1 findings:**
- Dedupe pairing refinement — **DONE (P2, 2026-11-10):** `min(ns,nb)` completeness pairing landed; 640 rows = 563 active + 77 dup, sibling rows stay visible.
- Image backfill — **DONE (P2, 2026-11-10):** hunt backfill filled 619/620 Kijiji listings; app mirror `app/imgfetch.py` → 559 local webp (3 CDN 404s fall back to placeholder).
- Dealer-blast mitigation + Stage 1.5 swipe boost matter immediately — only ~67/560 active rows are family-scored; the rest sort below.
## Phase 2 — The swipe app (core)
**Status: built by Torres + verified by Alex (2026-11-10) on `dev`; phone pass LIVE (swiping over the tailnet).** Contract frozen: `UI-SPEC.md` v2 + `reference/mockup-001-fidelity.html` (Variant A "Pure", approved by Glenn; 5-deep live stack, no-lock commit, dossier sheet). Image backfill + app-side mirror (`app/imgfetch.py`) done: 619/620 listings enriched, 559 local webp.
- [x] 2–3 UI mock variants → Glenn picked **Variant A "Pure"** (approved 2026-11-10 after two fix rounds)
- [x] API (deck cursor, swipe upsert/clear, list + filters, stats, media, import) + PWA frontend (faithful mockup port: stack engine, drag, Like / Nope / Maybe, dossier, empty/undo) — no match overlay (removed by Glenn's call)
- [x] Full list view with inline edit; basic filters (decision + sort + search)
- [x] Proof: runs locally on :9453 (systemd dev unit) + tailnet `http://rotarran.tailf35a34.ts.net:9453`; phone-viewport browser pass green; **phone pass live 2026-11-10** — Glenn swiping the real deck over the tailnet (24 swipes recorded + verified from the DB; list-edit tap still unexercised by Glenn — automation-covered)
- **Exit criteria:** Glenn can swipe a real deck on his phone and edit results in the list — swiping proven; edit-tap pending.
## Phase 3 — Personalization ("Trends")
**Status: contract frozen 2026-11-10 (docs + brief); build started (Torres).** Glenn's approved design (2026-11-10):
- **Sections of 25:** the deck is a finite batch; the agent always runs between sections (learning segmentation + anti-doom-scroll). Modes: forge-on-demand (default) / strict (nightly read only). Fallback to the last profile if the agent fails.
- **Section lead:** on open/refresh the best suggestions lead; the 5-card live stack is unchanged.
- **Wildcards (~1-in-10):** labeled "maybe you'll like this one instead"; plausible stretches; never hard-noped families; their answers teach the model.
- **Second looks:** likes + maybes + nopes return (chosen; ≤5/section, ≤2 nopes); Round 2 weighs ×2; flips are the loudest signal; a re-nope rests the item; rounds cap at 2. Returning maybes can bring their variants.
- **Match points:** taste + agent adjustments; drive ordering, the section recipe (family caps, price mix), and returns. Explainable in the dossier; tank gauge (non-numeric) in the List.
- **Hits objective:** order = expected-like; Trends reports the hit rate (likes; likes+maybes).
- **Agent pass:** nightly/on-demand read (mock + live + fallback); **no LLM in the swipe path — ever.**
- **Exit criteria:** after ≥30 swipes the deck order visibly reflects taste; explainability visible (dossier breakdown + Trends); the section loop works end-to-end; the agent kill-switch test passes (app fully functional on the last profile with the pass disabled).
## Phase 4 — Deploy + automate
- Podman compose stack at `/var/mnt/DATA/podman-stacks/bike-tinder/` + systemd unit (`Delegate=yes`) + in-stack Tailscale sidecar serving `https://biketinder.tailf35a34.ts.net`; PWA install on Glenn's phone
- Enable the new `bike-tinder-import` Hermes cron (08:30 daily, post-hunt; script-only, zero LLM; parked until deploy); DB backup routine
- Runbook in DESIGN.md; announce + handover note
- **Exit criteria:** survives a reboot; refreshes overnight unattended; installable and used from the phone.
## Non-goals (v1)
- Multi-user accounts, social features, comments
- Additional sources (v2+); Facebook (never — manual by Glenn)
- Notifications beyond what already exists (Conduit is the house channel)
- Buying workflow (contact/inspection tracking) — possible v2
## Open decisions
- v1 source — **resolved 2026-11-10: Kijiji** (see `docs/SOURCES.md`)
- Mockup direction — Glenn picks at Phase 2 start