update session_memory - for refer to the passwork
This commit is contained in:
DatTT127
554
session_memory/7_Jun_26/ONBOARDING_INDEX.md
Normal file
554
session_memory/7_Jun_26/ONBOARDING_INDEX.md
Normal file
@@ -0,0 +1,554 @@
|
||||
# VKIST MSK Pilot — Intern Onboarding Index
|
||||
|
||||
**Date:** 7 Jul 2026
|
||||
**Audience:** Phuc (ML / agentic), Quan (frontend / PWA), Dave Tran - Dat (lead)
|
||||
**Repo:** `pilot_msk_ultrasound_stack` — clone already shared via GitHub
|
||||
|
||||
Read this file first, then open your role-specific guide:
|
||||
|
||||
|
||||
| Track | Document |
|
||||
| ---------------------------------------------- | ------------------------------------------------------------------ |
|
||||
| **Phuc** — generative logic, agent, guardrails | [ONBOARDING_PHUC_ML_ENGINEER.md](./ONBOARDING_PHUC_ML_ENGINEER.md) |
|
||||
| **Quan** — mobile UI, Figma, Stitch, PWA | [ONBOARDING_QUAN_FRONTEND.md](./ONBOARDING_QUAN_FRONTEND.md) |
|
||||
|
||||
|
||||
> **Abbreviations:** See [§12 Glossary](./ONBOARDING_INDEX.md#12-glossary-of-abbreviations) — FR, NFR, RAG, CoT, PHI, PWA, etc.
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
## 1. What this project is
|
||||
|
||||
**VKIST MSK Pilot** moves academic musculoskeletal ultrasound ML (angle → inflammation → segmentation → synovitis grade 0–3) into a clinical web platform for Vietnamese public hospitals (Bach Mai, Viet Duc class facilities).
|
||||
|
||||
|
||||
| Dimension | Summary |
|
||||
| ---------- | ------------------------------------------------------------------------------------------------------- |
|
||||
| **Cycle** | Jun 2 – Sep 2, 2026 (strict 3-month window) |
|
||||
| **Method** | Hybrid: waterfall phases + agile sprints |
|
||||
| **Stack** | React PWA + FastAPI + Triton CV + 3-tier LLM (Edge Gemma → Gemini → MedGemma) + RAG over MOH guidelines |
|
||||
| **Users** | Radiologists, surgeons, physiotherapists, patients/caregivers — each with different UI needs |
|
||||
|
||||
|
||||
**Hard constraints (non-negotiable):**
|
||||
|
||||
- **Decree 13/2023** — no raw PHI leaves device without scrubbing
|
||||
- **No open-ended patient chat** — structured, gated summaries only
|
||||
- **Air-gapped hospital LAN** — cloud LLM only under NFR-16a (consent + audit + redaction)
|
||||
- **Legacy smartphones** — zero-GPU fallback rendering for patient fleet
|
||||
|
||||
Full vision: `[PILOT_PROJECT/PROJ_LEVEL_READING/PLAN/CONTEXT_VISION_SCOPE.md](../../PILOT_PROJECT/PROJ_LEVEL_READING/PLAN/CONTEXT_VISION_SCOPE.md)`
|
||||
|
||||
**Tóm tắt (VI):** Dự án AI siêu âm khớp gối cho bệnh viện VN; 3 tháng; bảo mật Decree 13; các tinh năng hiện giờ đang optimize cho người dùng chính là bác sĩ cơ xương khớp - trong tương lai có thể cân nhắc `bệnh nhân` là đối tượng phát triển; làm tiếp phần Dave đã xây, không làm lại từ đầu.
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
## 2. How we work — continuation engineering
|
||||
|
||||
You are **not** here to read docs for three weeks. You inherit Dave's foundation and ship **incremental PRs** that close spec gaps toward sprint checkpoints.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
foundation[Dave_Foundation]
|
||||
specs[Specs_and_UCs]
|
||||
backlog[Open_Backlog]
|
||||
checkpoint[Sprint_Checkpoint]
|
||||
internPR[Intern_Incremental_PR]
|
||||
foundation --> internPR
|
||||
specs --> backlog
|
||||
backlog --> internPR
|
||||
internPR --> checkpoint
|
||||
```
|
||||
|
||||
|
||||
|
||||
1. Dave assigns **one backlog ID** (P-n or Q-n).
|
||||
2. You read **only** the spec + code files for that ticket.
|
||||
3. Ship a small PR (≤300 lines preferred); demo something runnable weekly.
|
||||
4. Dave assigns the next ticket.
|
||||
|
||||
**Tóm tắt (VI):** Dave giao ticket → đọc đúng spec → PR nhỏ → demo hàng tuần → ticket tiếp theo.
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
## 3. Foundation already built (do not rebuild)
|
||||
|
||||
Dave's latest handoff: `[session_memory/6_Jul_26.md](../6_Jul_26.md)`
|
||||
|
||||
|
||||
| Area | Status | Key locations |
|
||||
| --------------------- | ------------------------ | ------------------------------------------------------------------------- |
|
||||
| FR-25 workspace shell | **Working PoC** | `ClinicalWorkspacePage.tsx`, `WorkspaceShell.tsx`, `DiagnosticCanvas.tsx` |
|
||||
| CV inference | **Live** (FastAPI proxy) | `POST /api/test/analyze/batch`, `mlInferenceCacheStore.ts` |
|
||||
| Clinical chat UI | **Working** | `ClinicalChatPanel.tsx`, `useClinicalChat.ts` |
|
||||
| Edge Gemma 4 E2B | **Working** | `llm.worker.ts`, `clinicalLlmRuntime.ts`, OPFS |
|
||||
| CoT streaming | **Working** (plain text) | `clinicalChatStreamRegistry.ts`, `StreamingPlainText.tsx` |
|
||||
| Agent runtime | **Working** (mock tools) | `agent_runtime/`, `agentLoop.ts` |
|
||||
| Cloud BFF | **Wired** | `cloud_orchestrate.py`, `cloud_consult.py`, `agent_tools.py` |
|
||||
| 35 Figma routes | **Stub pages** | `figma-component-specs.md` |
|
||||
| Safety / guardrails | **Spec + stubs** | `bert_adapter.py`; `guardrail.worker.ts` missing |
|
||||
| Patient PWA | **Not started** | Sprint 4 |
|
||||
|
||||
|
||||
**Tóm tắt (VI):** Workspace, chat, agent, inference đã chạy; guardrail và UI mobile/patient còn thiếu — đó là việc của bạn.
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
## 4. Sprint checkpoints (what your PRs advance)
|
||||
|
||||
|
||||
| ID | Checkpoint | Sprint | Window | Owner |
|
||||
| ---- | ----------------------------------------------- | ------ | -------------- | --------------------- |
|
||||
| CP-1 | Beta clinical modes (Planning + high reasoning) | 2 | Jul 10 | Dave → Phuc polish |
|
||||
| CP-2 | Live agent tools (mock → BFF) | 2–3 | Jul 14–24 | **Phuc** |
|
||||
| CP-3 | Guardrail slice v1 | 2–3 | Jul 21 – Aug 7 | **Phuc** + Dave |
|
||||
| CP-4 | Collaborative annotation UX | 3 | Jul 13–24 | Dave; Quan UI support |
|
||||
| CP-5 | Patient list/cards → Figma mobile | 3–4 | Jul 28 – Aug 7 | **Quan** |
|
||||
| CP-6 | Patient PWA (large text, 375px) | 4 | Jul 27 – Aug 7 | **Quan** |
|
||||
| CP-7 | Accessibility on 2 screens | 4–5 | Aug 4–21 | **Quan** |
|
||||
| CP-8 | RAG retrieval gate / referee stub | 3–5 | Aug 1–21 | **Phuc** |
|
||||
|
||||
|
||||
**Timeboxes:** Phuc until ~Aug 31; Quan ~2 months (ends ~early Aug).
|
||||
|
||||
**Tóm tắt (VI):** Mỗi PR phải đẩy một checkpoint CP-n, không chỉ viết tài liệu.
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
## 5. Open backlog
|
||||
|
||||
Dave maintains priority. Do not self-assign large items.
|
||||
|
||||
### Phuc — generative / agentic
|
||||
|
||||
|
||||
| ID | Gap | Starting code | Done when |
|
||||
| --- | -------------------------------- | ----------------------------------------------- | ----------------------------------------------------- |
|
||||
| P-1 | Agent tools mock | `tools/registry.ts`, `agent_tools.py` | Live BFF; `VITE_CLINICAL_CHAT_MOCK_TOOLS=false` works |
|
||||
| P-2 | `bert_adapter.py` stubs | `bert_adapter.py`, `safety/service.py` | One real PASS/FAIL check on outbound text |
|
||||
| P-3 | `guardrail.worker.ts` missing | Create near `llm.worker.ts` | Worker hooks into chat before display |
|
||||
| P-4 | RAG not enforced in chat mode | `runClinicalChatTurn.ts` | Clinical answers require retrieval context |
|
||||
| P-5 | Planning + high reasoning `beta` | `clinicalChatModes.ts`, `chatReasoningLevel.ts` | Stable runs; beta flags removed |
|
||||
| P-6 | `escalate_medgemma` E2E | `cloud_llm_gateway.py`, `tools/registry.ts` | Demo with audit log entry |
|
||||
| P-7 | Conformal decoding eval | `ml/spec/conformal_decoding_*.md` | 3 VI clinical test cases (research) |
|
||||
|
||||
|
||||
|
||||
|
||||
### Quan — frontend / PWA
|
||||
|
||||
|
||||
| ID | Gap | Starting code | Done when |
|
||||
| --- | ----------------------------- | ----------------------------- | ----------------------------------------------------------------- |
|
||||
| Q-1 | 35 stub routes | `src/pages/*.tsx` | 2 priority screens match Figma |
|
||||
| Q-2 | Safety overlay not routed | `SafetyEscalationOverlay.tsx` | Reachable from workspace |
|
||||
| Q-3 | No mobile breakpoint | Patient pages | 375px pass, touch ≥44px |
|
||||
| Q-4 | Accessibility open | Patient components | 1 view WCAG-oriented pass |
|
||||
| Q-5 | No error boundaries | `App.tsx` | Friendly fallback on workspace route |
|
||||
| Q-6 | Patient dashboard | `patient-card-*.tsx` | Jargon-free, large type, VI copy |
|
||||
| Q-7 | Zero-GPU fallback UI | TBD banner | UI state when WebGL weak (Dave provides hook) |
|
||||
| Q-8 | Stitch sync after ship (lite) | Stitch board | Optional: update frame when PR merges; no standalone proposal doc |
|
||||
|
||||
|
||||
**Tóm tắt (VI):** Bảng backlog trên — chờ Dave giao ID cụ thể trước khi code.
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
## 6. Codebase map
|
||||
|
||||
**Active code:** `PILOT_PROJECT/workspace/sprint_1_2/CODEBASE/`
|
||||
**Do not develop in:** `PILOT_PROJECT/workspace/LEGACY/` (read-only reference)
|
||||
|
||||
> **Note:** Root `PILOT_PROJECT/README.md` references stale paths (`Reading_docs/`, `CONTEXT.md`). Use paths in this doc instead.
|
||||
|
||||
|
||||
| Module | Path | Phuc | Quan |
|
||||
| -------------- | --------------------- | ----------------------------------------- | ------------------------------------------------ |
|
||||
| Frontend | `CODEBASE/frontend/` | `lib/llm/`, `workers/`, `useClinicalChat` | **Primary** — `pages/`, `components/`, `styles/` |
|
||||
| Backend | `CODEBASE/backend/` | **Primary** — routers, safety, adapters | Read-only |
|
||||
| ML / NLP | `CODEBASE/ml/` | **Primary** — `agent_runtime/`, tests | Do not touch |
|
||||
| Knowledge | `CODEBASE/knowledge/` | When P-4/P-8 | Do not touch |
|
||||
| Design | `Design_Material/` | Safety, API | UCs, screen specs |
|
||||
| Session memory | `session_memory/` | `6_Jul_26.md` | `26_Jun_26/Proj_context` for layout |
|
||||
|
||||
|
||||
|
||||
|
||||
### Frontend tree (Quan primary)
|
||||
|
||||
```
|
||||
frontend/
|
||||
├── spec/ ← uix_prototype_coverage, figma-component-specs, DESIGN
|
||||
└── implementation/src/
|
||||
├── pages/ ← Quan: screens
|
||||
├── components/atoms|molecules|shells/
|
||||
├── styles/design-tokens.ts
|
||||
├── hooks/ ← Phuc: useClinicalChat only
|
||||
├── lib/llm/ ← Phuc ONLY
|
||||
└── workers/ ← Phuc ONLY
|
||||
```
|
||||
|
||||
|
||||
|
||||
### ML + backend tree (Phuc primary)
|
||||
|
||||
```
|
||||
ml/implementation/nlp/agent_runtime/src/
|
||||
orchestrator/agentLoop.ts
|
||||
tools/registry.ts
|
||||
prompt/toolSystemPrompt.ts, toolOutputParser.ts
|
||||
|
||||
frontend/.../src/lib/llm/ ← edge inference, chat routing
|
||||
backend/routers/ ← cloud_*, agent_tools
|
||||
backend/services/ ← cloud_llm_gateway, agent_tools_service
|
||||
backend/implementation/safety/, adapters/bert_adapter.py
|
||||
knowledge/spec/ ← RAG when P-4/P-8
|
||||
```
|
||||
|
||||
**Tóm tắt (VI):** Phuc = ml + backend + lib/llm; Quan = frontend pages/components; LEGACY không đụng.
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
## 7. Reading guide (summary)
|
||||
|
||||
Each role doc has three tiers. Quick reference:
|
||||
|
||||
|
||||
| Tier | When |
|
||||
| ---------------- | ---------------------------------- |
|
||||
| **Must read** | Day 1–3, before first PR |
|
||||
| **Should read** | When your ticket touches that area |
|
||||
| **Learn deeper** | Keywords — grow over internship |
|
||||
|
||||
|
||||
See [Phuc doc](./ONBOARDING_PHUC_ML_ENGINEER.md#3-what-to-read-what-to-learn) and [Quan doc](./ONBOARDING_QUAN_FRONTEND.md#3-what-to-read-what-to-learn) for full lists.
|
||||
|
||||
**Tóm tắt (VI):** Đọc bắt buộc trước PR đầu; đọc thêm theo ticket; học sâu theo từ khóa khi cần.
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
## 8. Dev toolkit
|
||||
|
||||
|
||||
|
||||
### Shared (both)
|
||||
|
||||
|
||||
| Tool | Purpose |
|
||||
| ----------------- | ----------------------------------------------------------- |
|
||||
| **Cursor / Kilo** | Agentic coding — load `PILOT_PROJECT/AGENT_SKILL/` first |
|
||||
| **Git + GitHub** | Branch per ticket; PR ≤300 lines |
|
||||
| `secrets/` | Local only — see `PILOT_PROJECT/secrets_template/README.md` |
|
||||
| `session_memory/` | Dave handoff — start with `6_Jul_26.md` |
|
||||
|
||||
|
||||
|
||||
|
||||
### Phuc additions
|
||||
|
||||
```bash
|
||||
# Frontend + clinical chat
|
||||
cd PILOT_PROJECT/workspace/sprint_1_2/CODEBASE/frontend/implementation
|
||||
npm install && npm run dev # :5173
|
||||
|
||||
# Gemma lab
|
||||
cd ../../ml/tests/gemma4_e2b && npm install && npm run dev # :5174
|
||||
|
||||
# Agent smoke
|
||||
cd ../agent_tools && npm install && npm run smoke
|
||||
|
||||
# Backend
|
||||
cd ../../.. && conda activate vkist_ultra
|
||||
PYTHONPATH=. python backend/tests/smoke_agent_tools_server.py
|
||||
```
|
||||
|
||||
Key env: `VITE_CLINICAL_CHAT_USE_LLM`, `VITE_CLINICAL_CHAT_MOCK_TOOLS`, `VITE_API_BASE_URL`
|
||||
|
||||
### Quan additions
|
||||
|
||||
```bash
|
||||
cd PILOT_PROJECT/workspace/sprint_1_2/CODEBASE/frontend/implementation
|
||||
npm install && npm run dev # :5173
|
||||
```
|
||||
|
||||
|
||||
| Tool | Link |
|
||||
| ------------------------- | -------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Figma** (authority) | [MSK_Workspace_UIX-Design](https://www.figma.com/design/uakk3T4efS1AIckfTEFSZO/MSK_Workspace_UIX-Design?node-id=0-1) |
|
||||
| **Stitch** (acceleration) | [Whiteboard 8188910238055386921](https://stitch.withgoogle.com/projects/8188910238055386921) |
|
||||
| **Responsive test** | Chrome DevTools → iPhone SE 375px |
|
||||
|
||||
|
||||
Stitch board has **web mocks** today — Quan creates **mobile variants** and exports references for the coding agent (see Quan doc).
|
||||
|
||||
**Tóm tắt (VI):** Cursor/Kilo + Git; Phuc thêm conda/smoke tests; Quan thêm Figma + Stitch + DevTools mobile.
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
## 9. Bonus — Feynman Technique with agents
|
||||
|
||||
When a concept or code path feels **hard**, don't just ask the agent to fix it — ask it to **teach it back to you** using the [Feynman Technique](https://en.wikipedia.org/wiki/Feynman_technique): explain simply, use an analogy, expose gaps, then verify your understanding.
|
||||
|
||||
### When to use
|
||||
|
||||
|
||||
| Situation | Use Feynman prompt |
|
||||
| ---------------------------------------------------- | -------------------------------- |
|
||||
| You read code but can't explain it in your own words | ✅ |
|
||||
| Agent generated a diff you don't fully understand | ✅ Before commit |
|
||||
| Spec uses jargon (RAG, CoT, BFF, …) | ✅ |
|
||||
| You're stuck >30 min on the same concept | ✅ Then ask Dave if still blocked |
|
||||
|
||||
|
||||
|
||||
|
||||
### Universal template (copy into Cursor / Kilo)
|
||||
|
||||
```
|
||||
Feynman explain — [TOPIC or FILE PATH]:
|
||||
|
||||
1. Explain like I'm a new intern with CS basics but new to this codebase.
|
||||
2. Use one everyday analogy (non-medical if possible).
|
||||
3. Walk the data/control flow in ≤8 numbered steps.
|
||||
4. Define every abbreviation you use (or link to our glossary).
|
||||
5. List 3 "common mistakes" a beginner would make here.
|
||||
6. Ask me 2 short quiz questions — wait for my answers before continuing.
|
||||
7. If I get them wrong, correct me simply.
|
||||
|
||||
Context: VKIST MSK Pilot, ticket [P-n or Q-n].
|
||||
Do NOT write code yet — teach only.
|
||||
```
|
||||
|
||||
|
||||
|
||||
### After the agent teaches you
|
||||
|
||||
1. **Rewrite** the idea in 3–5 bullets in your own words (PR description, standup note, or personal log).
|
||||
2. If you still can't rewrite without copying — **you're not ready to commit** that code; ask one follow-up or ping Dave.
|
||||
3. Optional: paste your summary to Dave at weekly demo — proves understanding, not just output.
|
||||
|
||||
Role-specific Feynman prompts: [Phuc §12](./ONBOARDING_PHUC_ML_ENGINEER.md#12-bonus--feynman-technique-prompts) · [Quan §14](./ONBOARDING_QUAN_FRONTEND.md#14-bonus--feynman-technique-prompts)
|
||||
|
||||
**Tóm tắt (VI):** Khi khó hiểu — bảo agent giải thích đơn giản (Feynman), trả lời quiz, tự viết lại bằng lời mình; chưa hiểu thì chưa commit.
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
## 10. Collaboration contract
|
||||
|
||||
|
||||
| Rule | Detail |
|
||||
| ------------- | ----------------------------------------------------------- |
|
||||
| Assignment | Dave picks backlog ID — you don't self-select large scope |
|
||||
| PR size | ≤300 lines; one backlog ID per PR |
|
||||
| Weekly demo | Runnable change required |
|
||||
| Agentic tools | OK after reading ticket spec; pass `AGENT_SKILL` checklists |
|
||||
| Research | ≤40% time; only when tied to P-7 or approved milestone |
|
||||
| Blocked >4h | Ping Dave with exact error + file path |
|
||||
|
||||
|
||||
**Tóm tắt (VI):** PR nhỏ, demo mỗi tuần, hỏi Dave khi kẹt quá 4 giờ.
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
## 11. Current assignments (Dave fills in)
|
||||
|
||||
|
||||
| Intern | Active ticket | Checkpoint | PR link | Status |
|
||||
| ------ | ------------------------- | ---------- | ------- | ------ |
|
||||
| Phuc | P-___ | CP-___ | | |
|
||||
| Quan | Q-1 (`/` worklist mobile) | CP-5 | | |
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
## 12. Glossary of abbreviations
|
||||
|
||||
Terms you will see daily in specs, code comments, and standups. Bookmark this section.
|
||||
|
||||
### Project & process
|
||||
|
||||
|
||||
| Abbr. | Full form | Meaning in this project |
|
||||
| --------------- | --------------------------------- | -------------------------------------------------------------- |
|
||||
| **VKIST** | Viện Khoa học Công nghệ (context) | Research institute partner; MSK ultrasound AI origin |
|
||||
| **MSK** | Musculoskeletal | Joint/tendon/ligament domain — knee ultrasound focus |
|
||||
| **PoC** | Proof of Concept | Current sprint build — not production-certified yet |
|
||||
| **CP-n** | Checkpoint n | Sprint deliverable milestone (see §4) |
|
||||
| **P-n / Q-n** | Phuc-ticket / Quan-ticket | Backlog IDs in §5 |
|
||||
| **UC-n** | Use Case n | Clinical workflow spec (e.g. `UC-48376` load scan session) |
|
||||
| **FR-n** | Functional Requirement n | Feature requirement (e.g. **FR-25** synovitis grading) |
|
||||
| **NFR-n** | Non-Functional Requirement n | Quality constraint (latency, safety, privacy) |
|
||||
| **WS-25** | Workspace 25 | Clinician diagnostic workspace UI (65/35 layout) |
|
||||
| **HITL** | Human-in-the-Loop | Clinician must review/confirm before AI output is final |
|
||||
| **UP5, UP1, …** | User Persona n | Stakeholder archetype (UP5 = radiologist, UP1 = senior expert) |
|
||||
|
||||
|
||||
|
||||
|
||||
### Clinical & domain (Vietnamese context)
|
||||
|
||||
|
||||
| Abbr. | Full form | Meaning |
|
||||
| --------------- | ----------------------------------------------------------- | --------------------------------------------------------- |
|
||||
| **MOH** | Ministry of Health (Vietnam) | Source of clinical guidelines for RAG corpus |
|
||||
| **DICOM** | Digital Imaging and Communications in Medicine | Standard medical image format (ultrasound slices) |
|
||||
| **PACS** | Picture Archiving and Communication System | Hospital image archive — DICOM source |
|
||||
| **EMR / HIS** | Electronic Medical Record / Hospital Information System | Hospital patient record system |
|
||||
| **HL7 / FHIR** | Health Level 7 / Fast Healthcare Interoperability Resources | Standards for EMR data exchange |
|
||||
| **Synovitis** | — | Joint lining inflammation — graded **0–3** by this system |
|
||||
| **GradCAM** | Gradient-weighted Class Activation Mapping | Heatmap showing which image regions drove AI grade |
|
||||
| **ULTS** | Ultrasound | Modality used in FR-25 |
|
||||
| **Circular 46** | Thông tư 46/2018/TT-BYT | Vietnam clinical report format regulation |
|
||||
| **Decree 13** | Nghị định 13/2023/NĐ-CP | Vietnam personal data protection law (PHI rules) |
|
||||
|
||||
|
||||
|
||||
|
||||
### Security & privacy
|
||||
|
||||
|
||||
| Abbr. | Full form | Meaning |
|
||||
| --------------- | ----------------------------------- | ----------------------------------------------------------------- |
|
||||
| **PHI** | Protected Health Information | Patient-identifiable health data — never commit to git |
|
||||
| **PII** | Personally Identifiable Information | Names, IDs, phone — scrubbed before cloud egress |
|
||||
| **RBAC** | Role-Based Access Control | Permissions by clinician role (radiologist, therapist, …) |
|
||||
| **JWT** | JSON Web Token | Session auth token (stored in Redis server-side) |
|
||||
| **NFR-16a** | NFR exception 16a | PoC-only rule allowing cloud LLM with redaction + consent + audit |
|
||||
| **AES-256-GCM** | Advanced Encryption Standard | Client-side encryption for local storage (target arch) |
|
||||
|
||||
|
||||
|
||||
|
||||
### Architecture & infrastructure
|
||||
|
||||
|
||||
| Abbr. | Full form | Meaning |
|
||||
| ------------ | ----------------------------------- | -------------------------------------------------------------- |
|
||||
| **PWA** | Progressive Web App | Installable web app — Sprint 4 patient target |
|
||||
| **BFF** | Backend-for-Frontend | FastAPI layer that proxies agent tools + cloud LLM for browser |
|
||||
| **API** | Application Programming Interface | HTTP endpoints (`/api/v1/...`) |
|
||||
| **K3s** | Lightweight Kubernetes | On-prem hospital cluster (target deployment) |
|
||||
| **Triton** | NVIDIA Triton Inference Server | GPU server for CV models + embeddings (`:8001` gRPC) |
|
||||
| **FastAPI** | — | Python web framework for backend (`:8000`) |
|
||||
| **NGINX** | — | Reverse proxy / SSL termination in front of FastAPI |
|
||||
| **MinIO** | — | S3-compatible object store for DICOM blobs, reports |
|
||||
| **pgvector** | PostgreSQL vector extension | Vector DB for MOH guideline semantic search (HNSW index) |
|
||||
| **HNSW** | Hierarchical Navigable Small World | Approximate nearest-neighbor index for RAG retrieval |
|
||||
| **GCP** | Google Cloud Platform | Hosts Gemini (Vertex AI) |
|
||||
| **Modal** | Modal.com | Serverless GPU platform hosting MedGemma |
|
||||
| **LAN** | Local Area Network | Hospital internal network — air-gapped primary mode |
|
||||
| **CI/CD** | Continuous Integration / Deployment | Jenkins + GitLab pipeline |
|
||||
| **SSE** | Server-Sent Events | One-way streaming from server to browser |
|
||||
|
||||
|
||||
|
||||
|
||||
### ML, NLP & generative AI
|
||||
|
||||
|
||||
| Abbr. | Full form | Meaning |
|
||||
| --------------------- | ------------------------------------------------------- | ------------------------------------------------------------------- |
|
||||
| **CV** | Computer Vision | Image ML pipeline (angle → inflammation → segmentation) |
|
||||
| **NLP** | Natural Language Processing | Clinical text cleanup, explanations, chat |
|
||||
| **LLM** | Large Language Model | Generative text models (Gemma, Gemini, MedGemma) |
|
||||
| **RAG** | Retrieval-Augmented Generation | Fetch MOH guideline chunks before generating answer |
|
||||
| **CoT** | Chain-of-Thought | Model "thinking" trace before final answer (thought channel) |
|
||||
| **TTFT** | Time to First Token | Latency until first streamed word appears (NFR-7: ≤200 ms target) |
|
||||
| **E2B / E4B** | Gemma 4 2B / 4B params | Edge (browser) vs server Ollama model sizes |
|
||||
| **WebLLM** | Web Large Language Model | In-browser inference via WebGPU + WASM |
|
||||
| **OPFS** | Origin Private File System | Browser storage for ~1.9 GB Gemma checkpoint |
|
||||
| **WASM** | WebAssembly | Binary format for in-browser ML (MediaPipe, LiteRT) |
|
||||
| **WebGPU** | — | Browser GPU API — required for edge Gemma |
|
||||
| **WebGL** | — | Older browser 3D API — fallback path for weak devices |
|
||||
| **BERT** | Bidirectional Encoder Representations from Transformers | Classifier for drift/guardrail/referee (partially stubbed) |
|
||||
| **EmbeddingGemma** | — | 768-dim embedding model for RAG vector search |
|
||||
| **MedGemma** | — | Tier-3 clinical deep-reasoning LLM (Modal, NFR-16a) |
|
||||
| **Gemini** | — | Tier-2 orchestration/translation LLM (GCP Vertex AI) |
|
||||
| **Gemma** | — | Tier-1 edge conversation LLM (browser MediaPipe) |
|
||||
| **Agent** | — | Multi-step tool-calling loop (`<tool_call>` / `<final>` protocol) |
|
||||
| **Guardrail** | — | Safety filter on generated text (hallucination, scope breach) |
|
||||
| **RAG-Referee** | — | 3-axis citation validator for MedGemma output |
|
||||
| **Circuit breaker** | — | Clinician challenges AI grade via Socratic dialogue before sign-off |
|
||||
| **Socratic dialogue** | — | Structured Q&A between clinician and AI about a grade |
|
||||
| **DeepLab / UNet** | — | Segmentation model architectures in CV pipeline |
|
||||
| **ConvNeXt / MedViT** | — | Angle classification model families (legacy stack) |
|
||||
| **LiteRT** | — | On-device inference runtime (TensorFlow Lite successor) |
|
||||
| **TFLite / TFJS** | TensorFlow Lite / TensorFlow.js | Client-side ML runtimes |
|
||||
| **ONNX** | Open Neural Network Exchange | Model interchange format for Triton deployment |
|
||||
| **VRAM** | Video RAM | GPU memory — relevant for Triton/Modal sizing |
|
||||
|
||||
|
||||
|
||||
|
||||
### Frontend & UI
|
||||
|
||||
|
||||
| Abbr. | Full form | Meaning |
|
||||
| ------------- | ------------------------------------------ | ------------------------------------------------------------- |
|
||||
| **UI / UIX** | User Interface / User Interface eXperience | Screens, layout, interaction design |
|
||||
| **SPA** | Single Page Application | React app — one HTML shell, client-side routing |
|
||||
| **TS / TSX** | TypeScript / TypeScript + JSX | Frontend language + React syntax |
|
||||
| **Zustand** | — | Lightweight React state store (target arch; PoC uses context) |
|
||||
| **Dexie.js** | — | IndexedDB wrapper for offline cache |
|
||||
| **IndexedDB** | — | Browser local database for inference cache, session replay |
|
||||
| **MRN** | Medical Record Number | Patient hospital ID shown in TopBar |
|
||||
| **FR-26** | Functional Requirement 26 | Future patient-facing dashboard scope |
|
||||
| **a11y** | Accessibility | WCAG-oriented design (contrast, font scale, touch targets) |
|
||||
|
||||
|
||||
|
||||
|
||||
### Tools & workflow
|
||||
|
||||
|
||||
| Abbr. | Full form | Meaning |
|
||||
| ------------ | ---------------------------------- | ----------------------------------------- |
|
||||
| **PR** | Pull Request | Code review unit — keep ≤300 lines |
|
||||
| **IDE** | Integrated Development Environment | VS Code / Cursor |
|
||||
| **Dev Mode** | Figma Dev Mode | Inspect panel for spacing, tokens, CSS |
|
||||
| **SDK** | Software Development Kit | e.g. `@google/stitch-sdk` for asset fetch |
|
||||
|
||||
|
||||
**Tóm tắt (VI):** Bảng viết tắt trên dùng hàng ngày — FR/NFR = yêu cầu; RAG/LLM/CoT = AI sinh ngôn ngữ; PHI/Decree 13 = bảo mật; PWA/DICOM/PACS = lâm sàng & UI; hỏi Dave nếu gặp từ mới.
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
## 13. Quick links
|
||||
|
||||
|
||||
| Resource | Path |
|
||||
| -------------------- | ------------------------------------------------------------------------------------- |
|
||||
| Project vision | `PILOT_PROJECT/PROJ_LEVEL_READING/PLAN/CONTEXT_VISION_SCOPE.md` |
|
||||
| Sprint architecture | `PILOT_PROJECT/workspace/sprint_1_2/Design_Material/SPRINT_1_2_ARCHITECTURE_SPEC.md` |
|
||||
| UI truth doc | `PILOT_PROJECT/workspace/sprint_1_2/CODEBASE/frontend/spec/uix_prototype_coverage.md` |
|
||||
| Agent skills | `PILOT_PROJECT/AGENT_SKILL/INTRODUCTION.md` |
|
||||
| Dave's Jul 6 handoff | `session_memory/6_Jul_26.md` |
|
||||
| Layout reference | `session_memory/26_Jun_26/Proj_context_26_Jun_26.md` |
|
||||
|
||||
|
||||
396
session_memory/7_Jun_26/ONBOARDING_PHUC_ML_ENGINEER.md
Normal file
396
session_memory/7_Jun_26/ONBOARDING_PHUC_ML_ENGINEER.md
Normal file
@@ -0,0 +1,396 @@
|
||||
# Onboarding — Phuc (ML Engineer / Agentic & Generative Logic)
|
||||
|
||||
**Start here:** [ONBOARDING_INDEX.md](./ONBOARDING_INDEX.md) — [glossary](./ONBOARDING_INDEX.md#12-glossary-of-abbreviations) · [Feynman prompts (INDEX §9)](./ONBOARDING_INDEX.md#9-bonus--feynman-technique-with-agents)
|
||||
**Date:** 7 Jul 2026
|
||||
**Timebox:** ~Jul 7 – Aug 31, 2026
|
||||
**Lane:** Generative LLM, agent runtime, guardrails, RAG gates — co-designed with Dave
|
||||
|
||||
---
|
||||
|
||||
## 1. Your mission
|
||||
|
||||
You continue the **generative & agentic layer** Dave built. Your deliverable is **merged code** that advances checkpoints **CP-2, CP-3, CP-8** — not architecture slides.
|
||||
|
||||
You co-own agentic design and guardrail logic with Dave: you propose, Dave approves scope, you ship one vertical slice per PR.
|
||||
|
||||
**You are not expected to:** rewrite the CV/Triton pipeline, own full compliance sign-off, or refactor UI components.
|
||||
|
||||
**Tóm tắt (VI):** Tiếp tục xây LLM/agent/guardrail; mỗi tuần có PR chạy được; thiết kế guardrail cùng Dave; không làm lại pipeline những kết quả đã có - nếu có thì phải optimize & hạn chế redundancies overhead trong thiết kế.
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
## 2. Your codebase scope
|
||||
|
||||
|
||||
|
||||
### In scope — touch freely
|
||||
|
||||
|
||||
| Path | What |
|
||||
| --------------------------------------------------------------------------- | --------------------------------------- |
|
||||
| `CODEBASE/ml/implementation/nlp/agent_runtime/` | Agent loop, tools, prompts |
|
||||
| `CODEBASE/ml/tests/gemma4_e2b/` | Isolated Gemma + agent lab (`:5174`) |
|
||||
| `CODEBASE/ml/tests/agent_tools/` | BFF / Modal / Exa smoke tests |
|
||||
| `CODEBASE/ml/spec/conformal_decoding_llm_with_domain_stritcly_constrain.md` | Research spec |
|
||||
| `CODEBASE/frontend/implementation/src/lib/llm/` | Edge inference, chat routing, prompts |
|
||||
| `CODEBASE/frontend/implementation/src/hooks/useClinicalChat.ts` | Chat bootstrap + streaming |
|
||||
| `CODEBASE/frontend/implementation/src/workers/llm.worker.ts` | MediaPipe Gemma worker |
|
||||
| `CODEBASE/frontend/implementation/src/workers/` | Create `guardrail.worker.ts` here (P-3) |
|
||||
| `CODEBASE/backend/routers/cloud_*.py`, `agent_tools.py` | Cloud + tool BFF |
|
||||
| `CODEBASE/backend/services/cloud_llm_gateway.py`, `agent_tools_service.py` | Gateway + tools |
|
||||
| `CODEBASE/backend/implementation/safety/` | Safety service |
|
||||
| `CODEBASE/backend/implementation/adapters/bert_adapter.py` | Guardrail stubs |
|
||||
| `CODEBASE/knowledge/spec/` | When working P-4 / P-8 |
|
||||
|
||||
|
||||
|
||||
|
||||
### Read-only — understand, don't refactor
|
||||
|
||||
- `CODEBASE/backend/implementation/pipeline/` — CV inference (Dave)
|
||||
- `CODEBASE/infra/` — unless P-6 Modal debugging
|
||||
- `CODEBASE/frontend/implementation/src/components/` — Quan's lane
|
||||
- `workspace/LEGACY/` — reference only
|
||||
|
||||
|
||||
|
||||
### Architecture mental model
|
||||
|
||||
```
|
||||
User message
|
||||
→ useClinicalChat / runClinicalChatTurn
|
||||
→ [chat|planning] → Edge Gemma (llm.worker) OR Ollama E4B
|
||||
→ [agent] → agentLoop → tools (exa, supabase, medgemma)
|
||||
→ [YOUR GAPS] guardrail check, RAG gate, cloud escalation audit
|
||||
→ display (StreamingPlainText)
|
||||
```
|
||||
|
||||
Tier 1 = browser Gemma · Tier 2 = Gemini · Tier 3 = MedGemma (NFR-16a governed)
|
||||
|
||||
**Tóm tắt (VI):** Phạm vi = ml/agent_runtime, lib/llm, backend safety/routers; không sửa UI hay LEGACY.
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
## 3. What to read, what to learn
|
||||
|
||||
|
||||
|
||||
### Must read (Day 1 — before first PR)
|
||||
|
||||
|
||||
| # | Document | Path |
|
||||
| --- | ---------------------- | ---------------------------------------------------------------------------- |
|
||||
| 1 | Dave's latest handoff | `session_memory/6_Jul_26.md` |
|
||||
| 2 | Regulatory constraints | `PILOT_PROJECT/PROJ_LEVEL_READING/PLAN/CONTEXT_VISION_SCOPE.md` §4 |
|
||||
| 3 | Agent protocol | `CODEBASE/ml/implementation/nlp/README.md` |
|
||||
| 4 | PHI safety | `PILOT_PROJECT/AGENT_SKILL/secrets_and_phi_safety/SKILL.md` |
|
||||
| 5 | Agent tools rules | `PILOT_PROJECT/AGENT_SKILL/agent_tool_execution/SKILL.md` |
|
||||
| 6 | LLM + safety NFRs | `Design_Material/SPRINT_1_2_ARCHITECTURE_SPEC.md` — LLM tiers, NFR-10/16a/18 |
|
||||
|
||||
|
||||
|
||||
|
||||
### Should read (when ticket assigned)
|
||||
|
||||
|
||||
| Ticket | Read |
|
||||
| -------- | --------------------------------------------------------------------------------------------------------------- |
|
||||
| P-1, P-6 | `backend/spec/agent_tools_contract.md`, `agent_runtime/.../tools/registry.ts`, `backend/routers/agent_tools.py` |
|
||||
| P-2, P-3 | `bert_adapter.py`, `safety/service.py`, `FR_25_UC_DESIGN/Q1_*.md` … `Q4_*.md` |
|
||||
| P-4, P-8 | `knowledge/spec/knowledge_spec.md`, `agentLoop.ts`, `runClinicalChatTurn.ts` |
|
||||
| P-5 | `clinicalChatModes.ts`, `chatReasoningLevel.ts`, `6_Jul_26.md` §beta |
|
||||
| P-7 | `ml/spec/conformal_decoding_llm_with_domain_stritcly_constrain.md` |
|
||||
| Any | Relevant `UC-*.md` in `Design_Material/FR_25_UC_DESIGN/Use_Case/` |
|
||||
|
||||
|
||||
**Week 1 code trace (do once):**
|
||||
`useClinicalChat.ts` → `runClinicalChatTurn.ts` → `agentLoop.ts` OR `llm.worker.ts` → `cloud_llm_gateway.py`
|
||||
|
||||
### Learn deeper (keywords)
|
||||
|
||||
> Abbreviations: [Glossary INDEX §12](./ONBOARDING_INDEX.md#12-glossary-of-abbreviations)
|
||||
|
||||
Study as tickets require — use papers, specs, and agent exploration:
|
||||
|
||||
|
||||
| Keywords | Tickets |
|
||||
| ------------------------------------------------------------------- | -------- |
|
||||
| `prompt-constrained tool calling`, `agent orchestration loop` | P-1 |
|
||||
| `RAG pre-retrieval`, `pgvector`, `semantic chunk`, `MOH corpus` | P-4, P-8 |
|
||||
| `BERT guardrail`, `hallucination detection`, `scope-breach scoring` | P-2, P-3 |
|
||||
| `conformal decoding`, `domain-constrained generation` | P-7 |
|
||||
| `CoT streaming`, `thought/answer channel`, `WebLLM MediaPipe` | P-5 |
|
||||
| `NFR-16a`, `consent audit`, `cloud egress redaction` | P-6 |
|
||||
| `RAG-Referee`, `citation validation`, `3-axis contestant` | P-8 |
|
||||
| `Transformers.js`, `Web Worker`, `OPFS model cache` | P-3 |
|
||||
|
||||
|
||||
**Tóm tắt (VI):** Đọc 6 tài liệu bắt buộc ngày 1; đọc thêm theo ticket P-n; học sâu theo từ khóa khi làm.
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
## 4. Dev toolkit
|
||||
|
||||
|
||||
| Tool | Command |
|
||||
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
|
||||
| Clinical chat UI | `cd CODEBASE/frontend/implementation && npm run dev` → `:5173` |
|
||||
| Gemma lab | `cd CODEBASE/ml/tests/gemma4_e2b && npm run dev` → `:5174` |
|
||||
| Agent smoke (test-the-agentic-functionality) | `cd CODEBASE/ml/tests/agent_tools && npm run smoke` |
|
||||
| Backend smoke (test-the-agentic-functionality) | `conda activate vkist_ultra`; `cd CODEBASE`; `PYTHONPATH=. python backend/tests/smoke_agent_tools_server.py` |
|
||||
| Agentic IDE | Cursor / Kilo — load `AGENT_SKILL/agent_tool_execution` |
|
||||
|
||||
|
||||
**Environment variables (frontend** `.env.development`**):**
|
||||
|
||||
```env
|
||||
VITE_CLINICAL_CHAT_USE_LLM=true
|
||||
VITE_CLINICAL_CHAT_MOCK_TOOLS=true # flip false for P-1 done
|
||||
VITE_OLLAMA_CHAT_URL=/api/ollama-chat/api/chat
|
||||
VITE_API_BASE_URL=http://localhost:8001
|
||||
```
|
||||
|
||||
Secrets: ask Dave — `PILOT_PROJECT/secrets_template/README.md`
|
||||
|
||||
**Tóm tắt (VI):** Chạy :5173 chat, :5174 lab, smoke tests; đổi MOCK_TOOLS=false khi P-1 xong.
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
## 5. Day 1 playbook (then ship)
|
||||
|
||||
**Morning**
|
||||
|
||||
1. Run `:5173` → open `/workspace/:patientId` → test chat + agent modes.
|
||||
2. Run `:5174` gemma4_e2b → complete one tool smoke call.
|
||||
3. Trace one chat turn and one agent turn (Section 3 code trace).
|
||||
|
||||
**Afternoon**
|
||||
4. Hands-on verify backlog P-1–P-7 (✅/❌ in your notes).
|
||||
5. Sync with Dave → receive first ticket (likely **P-1** or **P-5**).
|
||||
|
||||
Do **not** spend Week 1 writing standalone architecture docs.
|
||||
|
||||
**Tóm tắt (VI):** Ngày 1: chạy app, trace code, sync Dave lấy ticket — không viết doc dài.
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
## 6. Spec vs implementation (your work surface)
|
||||
|
||||
|
||||
| Component | Built today | Your tickets |
|
||||
| ----------------------------------- | -------------- | ------------------ |
|
||||
| Edge Gemma inference | ✅ | P-5 polish |
|
||||
| Agent loop + `<tool_call>` protocol | ✅ (mock tools) | P-1 |
|
||||
| Cloud gateway + audit hooks | ⚠️ partial | P-6 |
|
||||
| Auto-retrieval in agent mode | ✅ | P-4 extend to chat |
|
||||
| `bert_adapter.py` / safety service | ❌ stub | P-2 |
|
||||
| `guardrail.worker.ts` | ❌ missing | P-3 |
|
||||
| RAG-Referee 3-axis | ❌ spec only | P-8 |
|
||||
| Planning + high reasoning beta | ⚠️ disabled | P-5 |
|
||||
|
||||
|
||||
**Key facts:**
|
||||
|
||||
- Production chat = **browser Gemma 4 E2B** (MediaPipe), not server-side generation.
|
||||
- Agent mode uses **prompt tags** (`<tool_call>`, `<final>`), not native function calling.
|
||||
- Do **not** re-enable `ChatMarkdown` in reasoning mode — see `6_Jul_26.md` crash policy.
|
||||
|
||||
**Tóm tắt (VI):** Guardrail và RAG chat còn stub — đó là trọng tâm của bạn.
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
## 7. Your backlog (detail)
|
||||
|
||||
|
||||
| ID | Gap | Spec | Starting files |
|
||||
| ------- | ------------------------------ | --------------------------------- | ----------------------------------------------- |
|
||||
| **P-1** | Mock agent tools | `agent_tools_contract.md` | `tools/registry.ts`, `agent_tools.py` |
|
||||
| **P-2** | BERT adapter stubs | NFR-10, Q1–Q4 | `bert_adapter.py`, `safety/service.py` |
|
||||
| **P-3** | No edge guardrail worker | Web Workers spec | Create `guardrail.worker.ts` |
|
||||
| **P-4** | No RAG gate in chat mode | NFR-18, `knowledge_spec.md` | `runClinicalChatTurn.ts` |
|
||||
| **P-5** | Beta modes disabled | `6_Jul_26.md` | `clinicalChatModes.ts`, `chatReasoningLevel.ts` |
|
||||
| **P-6** | MedGemma escalation incomplete | NFR-16a | `cloud_llm_gateway.py`, `tools/registry.ts` |
|
||||
| **P-7** | Conformal decoding research | `ml/spec/conformal_decoding_*.md` | `gemma4_e2b/` lab |
|
||||
|
||||
|
||||
**Tóm tắt (VI):** P-1 đến P-7 — chờ Dave giao ID / chủ động đề xuất giải pháp kỹ thuật & thiết kế; mỗi PR một ticket.
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
## 8. SMART milestones
|
||||
|
||||
|
||||
|
||||
### M1 — First merge (Jul 7 – Jul 18)
|
||||
|
||||
|
||||
| | |
|
||||
| -------------- | --------------------------------------------- |
|
||||
| **Ticket** | P-1 or P-5 (Dave assigns) |
|
||||
| **Specific** | Live agent tools OR remove beta from one mode |
|
||||
| **Measurable** | PR merged; live demo on `:5173` |
|
||||
| **Achievable** | One backlog ID only |
|
||||
| **Relevant** | CP-1 / CP-2 |
|
||||
| **Time-bound** | Sprint 3 week 1 |
|
||||
|
||||
|
||||
|
||||
|
||||
### M2 — Guardrail v1 (Jul 14 – Aug 1)
|
||||
|
||||
|
||||
| | |
|
||||
| -------------- | ------------------------------------------------------- |
|
||||
| **Ticket** | P-2 or P-3 (co-scoped with Dave) |
|
||||
| **Specific** | RFC ≤1 page + one real PASS/FAIL check on outbound text |
|
||||
| **Measurable** | Test/smoke on 3 fixtures from Q1–Q4 scenarios |
|
||||
| **Achievable** | Keyword gate OK for v1; full BERT optional |
|
||||
| **Relevant** | CP-3, NFR-10 |
|
||||
| **Time-bound** | Sprint 3 end |
|
||||
|
||||
|
||||
|
||||
|
||||
### M3 — Retrieval or escalation (Jul 28 – Aug 15)
|
||||
|
||||
|
||||
| | |
|
||||
| -------------- | -------------------------------------------------- |
|
||||
| **Ticket** | P-4 or P-6 |
|
||||
| **Specific** | RAG gate in chat OR MedGemma escalation with audit |
|
||||
| **Measurable** | Screen recording + log snippet in PR |
|
||||
| **Relevant** | CP-2 / CP-8, NFR-18 |
|
||||
| **Time-bound** | Sprint 4 |
|
||||
|
||||
|
||||
|
||||
|
||||
### M4 — Research or hardening (Aug 1 – Aug 31)
|
||||
|
||||
|
||||
| | |
|
||||
| -------------- | ---------------------------------------------------- |
|
||||
| **Ticket** | P-7 or extend P-2/P-3 |
|
||||
| **Specific** | Conformal eval (3 VI cases) OR second guardrail axis |
|
||||
| **Optional** | If M2–M3 complete |
|
||||
| **Time-bound** | Internship end |
|
||||
|
||||
|
||||
**Tóm tắt (VI):** 4 mốc — PR đầu tiên tuần 1; guardrail tuần 3–4; RAG/escalation tháng 8.
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
## 9. Anti-patterns
|
||||
|
||||
- ❌ Refactor `agent_runtime` package structure without inform to members on update logic (no change-Log)
|
||||
- ❌ Swap model families (Qwen experiment is closed)
|
||||
- ❌ Touch `LEGACY/` or Quan's UI components
|
||||
- ❌ Enable `ChatMarkdown` during reasoning streams (markdown rendering on LLM's outcome is problem - we shall put it under the rug)
|
||||
- ❌ Commit secrets or PHI — ever
|
||||
|
||||
**Tóm tắt (VI):** Không refactor lớn, không đổi model, không markdown khi reasoning.
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
## 10. Definition of done
|
||||
|
||||
- [ ] ≥3 merged PRs across P-1–P-6
|
||||
- [ ] Can demo live agent tool call or guardrail check without Dave driving
|
||||
- [ ] CP-2 or CP-3 marked advanced in team backlog
|
||||
- [ ] Read `secrets_and_phi_safety` + `agent_tool_execution` skills
|
||||
|
||||
**Tóm tắt (VI):** 3 PR, demo được guardrail/agent, checkpoint CP-2 hoặc CP-3 tiến triển.
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
## 11. Agent prompt examples (optimize / change based on usecase)
|
||||
|
||||
**Explore generative flow:**
|
||||
|
||||
```
|
||||
Trace runClinicalChatTurn.ts for agent mode: list each file called,
|
||||
what tool protocol is used, and where mock tools are injected.
|
||||
```
|
||||
|
||||
**Start P-1:**
|
||||
|
||||
```
|
||||
Help me flip VITE_CLINICAL_CHAT_MOCK_TOOLS to false and fix any
|
||||
BFF errors. Start from tools/registry.ts and agent_tools.py.
|
||||
Follow AGENT_SKILL/agent_tool_execution/SKILL.md.
|
||||
```
|
||||
|
||||
**Start P-2:**
|
||||
|
||||
```
|
||||
Implement a minimal scope-breach keyword gate in bert_adapter.py
|
||||
returning PASS/FAIL. Use Q1_True_Agreement.md as fixture context.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12. Bonus — Feynman Technique prompts
|
||||
|
||||
Use when a generative/agent concept feels opaque **before** you commit agent-generated code.
|
||||
Master template: [INDEX §9](./ONBOARDING_INDEX.md#9-bonus--feynman-technique-with-agents).
|
||||
|
||||
### Hard concepts → ready-made prompts
|
||||
|
||||
**Agent loop & `<tool_call>` protocol (P-1):**
|
||||
```
|
||||
Feynman explain agentLoop.ts and the <tool_call> / <final> protocol in
|
||||
@vkist/agent-runtime. Why prompt tags instead of OpenAI function calling?
|
||||
Trace one turn with exa_search mocked. Quiz me after.
|
||||
```
|
||||
|
||||
**Edge vs cloud 3-tier LLM (general):**
|
||||
```
|
||||
Feynman explain our 3-tier LLM: Edge Gemma → Gemini → MedGemma.
|
||||
When does each tier run? What is NFR-16a in one sentence?
|
||||
Use a "triage desk at a hospital" analogy. Quiz me.
|
||||
```
|
||||
|
||||
**clinicalChatStreamRegistry + streaming (P-5 area):**
|
||||
```
|
||||
Feynman explain why clinicalChatStreamRegistry.ts paints tokens to the DOM
|
||||
directly instead of React setState on every token. What breaks if we use
|
||||
ChatMarkdown during CoT? ≤8 steps. Quiz me.
|
||||
```
|
||||
|
||||
**RAG pre-retrieval (P-4 / P-8):**
|
||||
```
|
||||
Feynman explain mandatory RAG pre-generation in our system: what pgvector
|
||||
retrieves, when agentLoop auto-calls supabase_query, and why chat mode
|
||||
doesn't do this yet. MOH corpus in plain language. Quiz me.
|
||||
```
|
||||
|
||||
**Guardrail vs RAG-Referee (P-2 / P-3):**
|
||||
```
|
||||
Feynman explain the difference between edge guardrail, bert_adapter
|
||||
drift check, and RAG-Referee. Which are implemented vs stub today?
|
||||
Use a "editor vs fact-checker" analogy. Quiz me.
|
||||
```
|
||||
|
||||
**After each Feynman session:** write 3 bullets in your own words in the PR or ticket comment.
|
||||
|
||||
**Tóm tắt (VI):** Dùng prompt Feynman khi không hiểu agent/LLM; có sẵn prompt cho từng chủ đề khó; tự tóm tắt lại trước khi commit.
|
||||
499
session_memory/7_Jun_26/ONBOARDING_QUAN_FRONTEND.md
Normal file
499
session_memory/7_Jun_26/ONBOARDING_QUAN_FRONTEND.md
Normal file
@@ -0,0 +1,499 @@
|
||||
# Onboarding — Quan (Frontend / Mobile PWA)
|
||||
|
||||
**Start here:** [ONBOARDING_INDEX.md](./ONBOARDING_INDEX.md) — [glossary](./ONBOARDING_INDEX.md#12-glossary-of-abbreviations) · [Feynman prompts (INDEX §9)](./ONBOARDING_INDEX.md#9-bonus--feynman-technique-with-agents)
|
||||
**Date:** 7 Jul 2026
|
||||
**Timebox:** ~2 months (ends ~early Aug 2026)
|
||||
**Lane:** Mobile UI, Figma + Stitch design acceleration, patient PWA
|
||||
|
||||
---
|
||||
|
||||
## 1. Your mission
|
||||
|
||||
You continue the **UI layer** from stub routes toward Sprint 4 patient PWA checkpoints. You ship **visible screens in the browser** — not backend, not LLM internals.
|
||||
|
||||
Dave provides two design accelerators:
|
||||
|
||||
|
||||
| Tool | Link | Role |
|
||||
| ----------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
|
||||
| **Figma** | [MSK_Workspace_UIX-Design](https://www.figma.com/design/uakk3T4efS1AIckfTEFSZO/MSK_Workspace_UIX-Design?node-id=0-1) | Design authority — 35 screens, tokens, Vietnamese copy |
|
||||
| **Google Stitch** | [Whiteboard](https://stitch.withgoogle.com/projects/8188910238055386921) | Acceleration — board has **web mocks**; you design **mobile variants** |
|
||||
|
||||
|
||||
**Your agency:** Pick Figma-first, Stitch-first, or hybrid **per screen** — one line in the PR is enough. Dave assigns tickets; **Week 1 default ticket is Q-1 on the live `/` worklist** (highest yield).
|
||||
|
||||
**Week 1 principle — ship fast, correct, get feedback:**
|
||||
|
||||
|
||||
| Priority | Rule |
|
||||
| --------------- | ----------------------------------------------------------------------------------------------------- |
|
||||
| **Speed** | Tools (Figma + Stitch) = **1 day max**, then code same day |
|
||||
| **Yield** | Week 1 targets the **live route** `/` (`PatientWorklistPage`) mobile at 375px — not orphan stub pages |
|
||||
| **Correctness** | `design-tokens.ts`, live navigation, no hardcoded colors, no pasted Stitch HTML |
|
||||
| **Feedback** | Draft PR or screenshots to Dave **end of Day 1**; iterate Day 2–3 from review |
|
||||
|
||||
|
||||
**Stitch (quick rules):**
|
||||
|
||||
1. Board has web mocks — use Stitch to sketch **mobile layout**, export screenshot for Cursor/Kilo
|
||||
2. Agent writes React; you review every line
|
||||
3. Figma wins on tokens and Vietnamese copy
|
||||
|
||||
**Tóm tắt (VI):** Tuần 1 = 1 ngày học tool, cùng ngày code mobile cho `/` worklist; PR/screenshot cuối ngày 1; sửa theo feedback Dave — không khảo sát tự do nhiều ngày.
|
||||
|
||||
---
|
||||
|
||||
## 2. Your codebase scope
|
||||
|
||||
### In scope — touch freely
|
||||
|
||||
```
|
||||
CODEBASE/frontend/
|
||||
├── spec/ ← read: uix_prototype_coverage, figma-component-specs, DESIGN
|
||||
└── implementation/src/
|
||||
├── pages/ ← your primary workspace
|
||||
├── components/atoms/
|
||||
├── components/molecules/
|
||||
├── components/layout/
|
||||
├── styles/design-tokens.ts ← token source of truth
|
||||
├── App.tsx ← routes
|
||||
└── public/assets/stitch/ ← exported Stitch references
|
||||
```
|
||||
|
||||
### Read-only — understand, don't refactor
|
||||
|
||||
|
||||
| File / folder | Why |
|
||||
| ------------------------------------------ | -------------------------------- |
|
||||
| `organisms/DiagnosticCanvas.tsx` | Dave owns DICOM canvas |
|
||||
| `molecules/ClinicalChatPanel.tsx` | Read layout only — Phuc owns LLM |
|
||||
| `lib/llm/`, `workers/` | Phuc's lane |
|
||||
| `hooks/useClinicalChat.ts` | Know it exists |
|
||||
| `data/mockData.ts`, `lib/patientStore.tsx` | How worklist gets data |
|
||||
|
||||
|
||||
### Out of scope
|
||||
|
||||
`CODEBASE/backend/`, `CODEBASE/ml/`, `CODEBASE/knowledge/`, `CODEBASE/infra/`, `LEGACY/`
|
||||
|
||||
### Live routes today
|
||||
|
||||
```
|
||||
/ → PatientWorklistPage.tsx ← Q-1, Q-6 priority
|
||||
/workspace/:patientId → ClinicalWorkspacePage.tsx ← polish only; Q-2 overlay
|
||||
+ 35 stub routes in src/pages/ ← Figma parity over time
|
||||
```
|
||||
|
||||
**Tóm tắt (VI):** Sửa pages, atoms, molecules, tokens; không đụng canvas, chat LLM, backend.
|
||||
|
||||
---
|
||||
|
||||
## 3. What to read, what to learn
|
||||
|
||||
### Must read (Day 1 morning only — then code)
|
||||
|
||||
|
||||
| # | Document | Time |
|
||||
| --- | ----------------------------------------------------------------- | ---------------------------------- |
|
||||
| 1 | `uix_prototype_coverage.md` | 20 min — **which routes are live** |
|
||||
| 2 | `figma-component-specs.md` — Priority 1–2 + node for `/` worklist | 15 min |
|
||||
| 3 | `design-tokens.ts` + skim `DESIGN.md` | 15 min |
|
||||
| 4 | `AGENT_SKILL/secrets_and_phi_safety/SKILL.md` | 10 min |
|
||||
|
||||
|
||||
Read `component-inventory.md`, `coding_convention`, and persona §3.4 **while coding**, not before Day 1 PR.
|
||||
|
||||
**Tóm tắt (VI):** Sáng ngày 1 chỉ đọc 4 tài liệu ngắn; chiều cùng ngày bắt đầu code.
|
||||
|
||||
### Should read (when ticket assigned)
|
||||
|
||||
|
||||
| Ticket | Read |
|
||||
| ---------- | ---------------------------------------------------------------------------------------- |
|
||||
| Q-1, Q-6 | Figma node for screen; matching `src/pages/*.tsx` stub |
|
||||
| Q-2 | `uix_prototype_coverage.md` §Safety; `SafetyEscalationOverlay.tsx` |
|
||||
| Q-3, Q-4 | `CONTEXT_VISION_SCOPE.md` §3.4; `frontend_spec.md` PoC § |
|
||||
| Q-5 | `figma-component-specs.md` — error boundaries item |
|
||||
| Q-8 | [Stitch board](https://stitch.withgoogle.com/projects/8188910238055386921) + live routes |
|
||||
| Any screen | `Design_Material/FR_25_UC_DESIGN/Use_Case/UC-*.md` |
|
||||
| Layout | `session_memory/26_Jun_26/Proj_context_26_Jun_26.md` — 65/35 ASCII |
|
||||
|
||||
|
||||
### Learn deeper (keywords)
|
||||
|
||||
> Abbreviations: [Glossary INDEX §12](./ONBOARDING_INDEX.md#12-glossary-of-abbreviations)
|
||||
|
||||
|
||||
| Keywords | When |
|
||||
| ---------------------------------------------------------- | ------------------- |
|
||||
| `atomic design`, `atoms molecules organisms` | component-inventory |
|
||||
| `React functional components`, `props`, `composition` | all Q tickets |
|
||||
| `design tokens`, `CSS variables`, `responsive breakpoints` | Q-1, Q-3 |
|
||||
| `mobile-first`, `375px viewport`, `touch target 44px` | Q-3, Q-6 |
|
||||
| `accessibility`, `WCAG contrast`, `font scaling` | Q-4, Q-6 |
|
||||
| `error boundaries` | Q-5 |
|
||||
| `PWA`, `service worker` | Sprint 4 (later) |
|
||||
| `Figma Dev Mode`, `Inspect` | Q-1 |
|
||||
| `Stitch design-to-code`, `HTML export as reference` | Q-8 |
|
||||
| `Vite`, `npm run dev` | daily |
|
||||
| `Vietnamese clinical UX`, `jargon-free patient copy` | Q-6 |
|
||||
|
||||
|
||||
**Tóm tắt (VI):** Đọc thêm theo ticket khi code; không ôm 7 tài liệu trước PR đầu.
|
||||
|
||||
---
|
||||
|
||||
## 4. Dev toolkit
|
||||
|
||||
|
||||
| Category | Tool |
|
||||
| ------------------- | ------------------------------------------------------------------------------------------------- |
|
||||
| Dev server | `npm run dev` → `http://localhost:5173` |
|
||||
| Design authority | [Figma](https://www.figma.com/design/uakk3T4efS1AIckfTEFSZO/MSK_Workspace_UIX-Design?node-id=0-1) |
|
||||
| Design acceleration | [Stitch whiteboard](https://stitch.withgoogle.com/projects/8188910238055386921) |
|
||||
| Coding agent | Cursor / Kilo |
|
||||
| Mobile test | Chrome DevTools → iPhone SE 375×667 |
|
||||
| PR evidence | Before/after screenshots desktop + 375px |
|
||||
|
||||
|
||||
```bash
|
||||
cd PILOT_PROJECT/workspace/sprint_1_2/CODEBASE/frontend/implementation
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
**Optional:** Stitch SDK — `public/assets/stitch/README.md` (OAuth via Dave)
|
||||
|
||||
### Agent prompt template
|
||||
|
||||
```
|
||||
Implement [screen name] for mobile (375px).
|
||||
Reference: Figma node [id] from figma-component-specs.md.
|
||||
Layout hint: [Stitch mobile export screenshot or description].
|
||||
Use existing atoms from component-inventory.md.
|
||||
Use design-tokens.ts — no hardcoded colors.
|
||||
Route: [path from figma-component-specs].
|
||||
Match navigation in uix_prototype_coverage.md.
|
||||
```
|
||||
|
||||
**Tóm tắt (VI):** npm run dev + Figma + Stitch + Cursor; test 375px; PR kèm screenshot.
|
||||
|
||||
---
|
||||
|
||||
## 5. Figma + Stitch workflow
|
||||
|
||||
### When to use which
|
||||
|
||||
|
||||
| Source | Best for | Caveat |
|
||||
| ------------- | --------------------------------------------- | --------------------------------------- |
|
||||
| **Figma** | Tokens, spacing, VI copy, auth/patient cards | Slower from scratch — use Inspect |
|
||||
| **Stitch** | Rapid mobile layout; agent reference material | Web mock ≠ mobile — create mobile frame |
|
||||
| **Live code** | Navigation truth | `uix_prototype_coverage.md` |
|
||||
|
||||
|
||||
**Legacy Stitch desktop** (`public/assets/stitch/README.md`, project `17628337625105266704`) — reference only.
|
||||
**Primary Stitch:** [project 8188910238055386921](https://stitch.withgoogle.com/projects/8188910238055386921)
|
||||
|
||||
### Workflow choices (pick one per screen — state in PR)
|
||||
|
||||
|
||||
| ID | When | Steps |
|
||||
| -------------------- | -------------------------------------------------- | --------------------------------------------- |
|
||||
| **A — Figma-first** | Screen in node map; tokens matter | Inspect → atoms → `src/pages/` |
|
||||
| **B — Stitch-first** | Mobile patient screen; Stitch mobile variant ready | Stitch mobile design → export → agent → React |
|
||||
| **C — Hybrid** | Stitch layout close; Figma has correct copy | Stitch structure + Figma polish → code |
|
||||
|
||||
|
||||
**Rule:** Final PR must match live navigation (`/` → `/workspace/:id`), not a disconnected mock.
|
||||
|
||||
**Tóm tắt (VI):** Chọn A/B/C mỗi màn hình; Figma thắng khi khác Stitch; khớp route thật.
|
||||
|
||||
---
|
||||
|
||||
## 6. Week 1 sprint — tools in 1 day, ship mobile same week
|
||||
|
||||
> **No multi-day exploration.** Figma/Stitch are means to an end — the end is a **merged mobile PR** on a live screen.
|
||||
|
||||
### Day 1 — Tools (morning) + code (afternoon)
|
||||
|
||||
|
||||
| Block | Time | Do |
|
||||
| ------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Setup** | 30 min | `npm install && npm run dev` — open `/` on desktop + DevTools 375px |
|
||||
| **Figma** | 45 min | Open [Figma](https://www.figma.com/design/uakk3T4efS1AIckfTEFSZO/MSK_Workspace_UIX-Design?node-id=0-1) → Inspect **Patient List** node `82-3155` (maps to live worklist) |
|
||||
| **Stitch** | 45 min | Open [Stitch board](https://stitch.withgoogle.com/projects/8188910238055386921) → one mobile-frame sketch OR pick closest web mock → **screenshot for agent** |
|
||||
| **Must-read** | 60 min | Section 3 four docs only |
|
||||
| **Code** | Rest of day | **Q-1 on live `/`** — mobile layout for `PatientWorklistPage.tsx` (or `patient-list-main.tsx` if Dave assigns stub route). Cursor/Kilo + agent template (§4). **375px from the start.** |
|
||||
| **EOD** | 15 min | Send Dave: draft PR **or** before/after screenshots at 375px + 1-line workflow choice (A/B/C) |
|
||||
|
||||
|
||||
**Not acceptable as Week 1 deliverable:** gap lists, alignment essays, clicking all 35 routes, Storybook setup.
|
||||
|
||||
### Day 2 — Feedback loop
|
||||
|
||||
- Apply Dave's review on spacing, tokens, navigation, touch targets
|
||||
- Push PR updates; aim for **merge-ready** by EOD if scope was ≤200 lines
|
||||
|
||||
### Day 3–5 — Second yield
|
||||
|
||||
- Merge Week 1 PR OR complete merge after small fixes
|
||||
- Start **second screen** (patient card stub or Q-3 polish on same `/` route)
|
||||
- Optional: update one Stitch frame to match what you shipped (Q-8 lite — no separate doc)
|
||||
|
||||
### Week 1 success criteria
|
||||
|
||||
|
||||
| Check | Pass |
|
||||
| ------------------------------ | ---------------------------------------------- |
|
||||
| Live route `/` usable at 375px | No horizontal scroll |
|
||||
| Uses `design-tokens.ts` | No raw hex in new code |
|
||||
| Dave reviewed once | By end of Day 1 or 2 AM |
|
||||
| Runnable demo | `npm run dev` — you walk Dave through tap flow |
|
||||
|
||||
|
||||
**Tóm tắt (VI):** Ngày 1: tool buổi sáng, code buổi chiều, gửi Dave tối ngày 1; ngày 2 sửa feedback; ngày 3–5 merge + màn hình thứ 2.
|
||||
|
||||
---
|
||||
|
||||
## 7. What exists vs what you build
|
||||
|
||||
|
||||
| Exists | You increment |
|
||||
| ---------------------------------- | -------------------------------------------- |
|
||||
| WS-25 workspace PoC (functional) | Mobile polish, not rewrite |
|
||||
| 35 Figma stub routes | Q-1: 2 priority screens |
|
||||
| Stitch web mocks | Q-8 lite: update frame after ship (optional) |
|
||||
| `SafetyEscalationOverlay` (orphan) | Q-2: wire it |
|
||||
| No error boundaries | Q-5 |
|
||||
| No patient PWA | Q-6 |
|
||||
|
||||
|
||||
### WS-25 layout (read-only context)
|
||||
|
||||
Clinician workspace is 65/35 split — your zone is **patient list, cards, patient dashboard**, not DICOM canvas:
|
||||
|
||||
```
|
||||
┌─ TopBar ─────────────────────────────────────┐
|
||||
├─ Zone A (65%) DICOM │ Zone B (35%) sidebar ┤ ← Dave/Phuc zone
|
||||
└────────────────────────────────────────────────┘
|
||||
|
||||
Your zone: / worklist, /patients, patient-card-*, /home
|
||||
```
|
||||
|
||||
See `session_memory/26_Jun_26/Proj_context_26_Jun_26.md` for full ASCII.
|
||||
|
||||
**Tóm tắt (VI):** Workspace clinician đã có; bạn làm patient list, card, dashboard mobile.
|
||||
|
||||
---
|
||||
|
||||
## 8. Your backlog (detail)
|
||||
|
||||
|
||||
| ID | Gap | Priority screens / files |
|
||||
| ------- | ----------------------- | --------------------------------------------------------------------------------------- |
|
||||
| **Q-1** | Stub → Figma fidelity | Home, Login, Patient List, Patient Cards (see `figma-component-specs.md` §Priorities) |
|
||||
| **Q-2** | Safety overlay unrouted | `SafetyEscalationOverlay.tsx`, `App.tsx` |
|
||||
| **Q-3** | No 375px pass | Assigned patient screen |
|
||||
| **Q-4** | Accessibility | Patient-facing view |
|
||||
| **Q-5** | Error boundaries | `App.tsx` workspace route |
|
||||
| **Q-6** | Patient dashboard | `patient-card-*.tsx`, FR-26 preview |
|
||||
| **Q-7** | Zero-GPU UI banner | Dave provides detection hook |
|
||||
| **Q-8** | Stitch sync (lite) | Update Stitch frame **after** you ship — optional in PR, not a standalone proposal gate |
|
||||
|
||||
|
||||
**Figma priorities (from spec):**
|
||||
|
||||
1. Home, Login, Create Account
|
||||
2. Patient List + Cards
|
||||
3. Workspace shell (read-only for you)
|
||||
4. Auth flows
|
||||
5. AI View, Chat, Ultrasound
|
||||
6. Remaining screens
|
||||
|
||||
**Tóm tắt (VI):** Ưu tiên Home, Patient List, Patient Card trước.
|
||||
|
||||
---
|
||||
|
||||
## 9. SMART milestones
|
||||
|
||||
### M1 — Week 1 ship (Jul 7 – Jul 11) ← **start here**
|
||||
|
||||
|
||||
| | |
|
||||
| -------------- | ------------------------------------------------------------------------------------------------------- |
|
||||
| **Ticket** | **Q-1 on live `/` worklist** (Dave confirms file: `PatientWorklistPage.tsx` or `patient-list-main.tsx`) |
|
||||
| **Specific** | Mobile implementation at 375px on a **live** route — not a disconnected stub |
|
||||
| **Measurable** | Draft PR Day 1 EOD; merged or merge-ready by Day 5; before/after screenshots |
|
||||
| **Achievable** | ≤200 lines; tools only Day 1 morning |
|
||||
| **Relevant** | CP-5 — fastest visible yield |
|
||||
| **Feedback** | Dave review ≤24h after first push |
|
||||
|
||||
|
||||
### M2 — Second screen (Jul 14 – Jul 25)
|
||||
|
||||
|
||||
| | |
|
||||
| --------------- | ------------------------------------------------------------------- |
|
||||
| **Ticket** | Q-1 #2 (patient card / home) or Q-3 deepen mobile on shipped screen |
|
||||
| **Deliverable** | 2nd merged PR |
|
||||
| **Relevant** | CP-5 / CP-6 |
|
||||
|
||||
|
||||
### M3 — Mobile hardening (Jul 28 – Aug 11)
|
||||
|
||||
|
||||
| | |
|
||||
| --------------- | -------------------------------------------------------------- |
|
||||
| **Ticket** | Q-3 or Q-2 |
|
||||
| **Deliverable** | 375px recording; taps ≥44px; optional Q-8 Stitch frame updated |
|
||||
| **Relevant** | CP-6 |
|
||||
|
||||
|
||||
### M4 — Accessibility (Aug 4 – Aug 21) *optional*
|
||||
|
||||
|
||||
| | |
|
||||
| --------------- | ----------------------------------------- |
|
||||
| **Ticket** | Q-4 |
|
||||
| **Deliverable** | High contrast, large type on patient view |
|
||||
| **Relevant** | CP-7 |
|
||||
|
||||
|
||||
**Tóm tắt (VI):** M1 = tuần 1 merge mobile `/` worklist; không có M0 khảo sát riêng; M2–M4 mở rộng sau khi có feedback.
|
||||
|
||||
---
|
||||
|
||||
## 10. Per-ticket workflow
|
||||
|
||||
```
|
||||
1. Dave assigns Q-n
|
||||
2. Pick workflow A / B / C — write in PR description
|
||||
3. Capture Figma + Stitch reference screenshots
|
||||
4. Cursor/Kilo: use agent prompt template (Section 4)
|
||||
5. Review every line of the diff — understand before commit
|
||||
6. npm run dev → screenshot desktop + 375px
|
||||
7. PR: Q-n, CP-n, workflow choice, design links
|
||||
```
|
||||
|
||||
**Tóm tắt (VI):** Mỗi ticket: chọn workflow → agent hỗ trợ → review diff → screenshot → PR.
|
||||
|
||||
---
|
||||
|
||||
## 11. Boundaries
|
||||
|
||||
**Touch:** `src/pages/`, `src/components/` (atoms/molecules/layout), `src/styles/`, `App.tsx`, Stitch whiteboard, `public/assets/stitch/`
|
||||
|
||||
**Do not touch:** `src/lib/llm/`, `src/workers/`, backend, ml
|
||||
|
||||
**Figma/Stitch edits:** OK to update Stitch frames and Figma comments; ask Dave before changing shared Figma components.
|
||||
|
||||
**Tóm tắt (VI):** Chỉ frontend UI; hỏi Dave trước khi sửa component Figma dùng chung.
|
||||
|
||||
---
|
||||
|
||||
## 12. Definition of done
|
||||
|
||||
- [ ] Week 1: live `/` worklist mobile at 375px shipped or merge-ready
|
||||
- [ ] Dave feedback incorporated within 48h of first push
|
||||
- [ ] ≥2 screens merged by end of Month 1 (M1 + M2)
|
||||
- [ ] Each PR: workflow A/B/C (one line) + 375px screenshot
|
||||
- [ ] Never committed `secrets/` or PHI
|
||||
|
||||
**Tóm tắt (VI):** Tuần 1 phải có mobile `/` chạy được + feedback Dave; không cần báo cáo alignment dài.
|
||||
|
||||
---
|
||||
|
||||
## 13. Agent prompt examples (optimize / change based on usecase)
|
||||
|
||||
**Learn the codebase:**
|
||||
|
||||
```
|
||||
Explain PatientWorklistPage.tsx in simple terms: what components it uses,
|
||||
where data comes from, and which Figma node it maps to.
|
||||
```
|
||||
|
||||
**Start Q-1 (Figma-first):**
|
||||
|
||||
```
|
||||
Implement /home per Figma node 33-143 in figma-component-specs.md.
|
||||
Reuse Button and Badge from component-inventory. Use design-tokens.ts only.
|
||||
Current stub: src/pages/home.tsx
|
||||
```
|
||||
|
||||
**Week 1 — ship live worklist mobile (Day 1 afternoon):**
|
||||
|
||||
```
|
||||
Mobile pass for PatientWorklistPage at 375px.
|
||||
Figma node 82-3155. Stitch screenshot attached.
|
||||
Use design-tokens.ts and existing Button, Badge, PatientCard from component-inventory.
|
||||
No horizontal scroll. Touch targets >= 44px.
|
||||
Do not change routing — stay on /.
|
||||
Show me the minimal diff.
|
||||
```
|
||||
|
||||
**Start Q-3 (mobile pass):**
|
||||
|
||||
```
|
||||
Make patient-list-main.tsx usable at 375px: no horizontal scroll,
|
||||
touch targets at least 44px. Show me which CSS to change.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 14. Bonus — Feynman Technique prompts
|
||||
|
||||
Use when React layout, routing, or design workflow feels confusing **before** you commit.
|
||||
Master template: [INDEX §9](./ONBOARDING_INDEX.md#9-bonus--feynman-technique-with-agents).
|
||||
|
||||
### Hard concepts → ready-made prompts
|
||||
|
||||
**Live route vs stub route (Week 1 critical):**
|
||||
```
|
||||
Feynman explain the difference between our LIVE routes (/ and /workspace/:id)
|
||||
and the 35 Figma STUB routes in src/pages/. Why does Week 1 target
|
||||
PatientWorklistPage on / ? Use a "demo kitchen vs blueprint room" analogy.
|
||||
Quiz me.
|
||||
```
|
||||
|
||||
**PatientWorklistPage data flow:**
|
||||
```
|
||||
Feynman explain PatientWorklistPage.tsx: where patient list data comes from
|
||||
(mockData vs patientStore), what happens when I tap "Mở phiên chẩn đoán",
|
||||
and which components re-render. ≤8 steps. No jargon without definition. Quiz me.
|
||||
```
|
||||
|
||||
**design-tokens.ts vs hardcoded CSS:**
|
||||
```
|
||||
Feynman explain why we use design-tokens.ts instead of #hex in components.
|
||||
Show one wrong example and one right example from our codebase.
|
||||
Quiz me on how to add a new spacing value correctly.
|
||||
```
|
||||
|
||||
**375px mobile layout:**
|
||||
```
|
||||
Feynman explain mobile-first pass at 375px for our worklist: flex vs grid,
|
||||
overflow-x, and 44px touch targets. What is the smallest change to
|
||||
PatientListShell or PatientWorklistPage to stop horizontal scroll?
|
||||
Teach only — no code until I answer your quiz.
|
||||
```
|
||||
|
||||
**Figma vs Stitch vs code (your workflow A/B/C):**
|
||||
```
|
||||
Feynman explain when I should use Figma-first vs Stitch-first vs hybrid
|
||||
for a patient screen. What is "reference only" Stitch export vs production code?
|
||||
Quiz me with one scenario: patient card on mobile.
|
||||
```
|
||||
|
||||
**React atoms vs molecules (component-inventory):**
|
||||
```
|
||||
Feynman explain atomic design using OUR component-inventory.md: when is
|
||||
something a Button (atom) vs PatientHeader (molecule)? Give 2 examples
|
||||
from patient list screen. Quiz me.
|
||||
```
|
||||
|
||||
### Feynman before commit rule
|
||||
|
||||
If the agent wrote code and you **cannot** Feynman-explain the diff back to a friend in 30 seconds → don't commit yet; run one Feynman prompt on the confusing file.
|
||||
|
||||
**Tóm tắt (VI):** Hỏi agent giải thích đơn giản khi khó hiểu React/route/mobile; có prompt mẫu; không commit code mình chưa giải thích lại được.
|
||||
Reference in New Issue
Block a user