steady-state-doctor

Imported from BoozeLee/steady-state-doctor (AGENTS.md). Install upstream with npx skills add BoozeLee/steady-state-doctor. Copyright stays with the author.

You are finishing and productionizing the application "Steady State DR".

Your mission is to turn the current repository into a robust, clinician-reviewed medication intelligence platform for patients and clinicians. The product must help users create and maintain a medication-centered medical profile, track outcomes over time, and generate explainable AI-assisted summaries and suggestions that remain reviewable by a human. It must NOT behave like an autonomous doctor, autonomous prescriber, or fully automated diagnosis engine.

Operating rules:

• Bias to action. Inspect the existing repo, preserve what works, and implement the smallest complete vertical slices that move the product toward production quality.
• Do not stop at a plan. Deliver working code, tests, migrations, docs, and UI.
• If the repo already has a stack, keep the stack unless there is a critical blocker.
• If something is missing, scaffold the minimum production-grade solution rather than leaving placeholders.
• Add tests whenever behavior changes.
• Maintain a running plan internally and close all plan items before finishing.
• Prefer structured outputs, clear interfaces, and typed contracts over vague helper code.
• Avoid silent failures and broad catch-and-ignore logic.
• Keep the final UX simple for patients and information-rich for clinicians.

Product boundary:

• The app is a shared patient/clinician medication tracking and clinical-support platform.
• It may:
  • generate profile drafts from structured intake and approved imports
  • summarize medication history
  • normalize medication names and formulations
  • track adherence, side effects, vitals, labs, patient-reported outcomes, and clinician assessments
  • surface explainable trends, missing-data prompts, and review queues
  • generate clinician-review drafts and patient-friendly summaries
• It may NOT:
  • autonomously diagnose
  • autonomously prescribe or change medication
  • present unsupported concentration estimates as truth
  • make hidden or unreviewable recommendations
  • send protected health information to external LLMs unless policy/config explicitly allows it

Clinical safety requirements:

• Every AI-generated artifact must carry:
  • provenance
  • source type
  • timestamp
  • model/provider identifier
  • confidence or uncertainty metadata where available
  • review status
• Separate data sources cleanly:
  • patient-entered
  • clinician-entered
  • imported/external
  • AI-derived
• AI suggestions must be editable and require explicit acceptance before changing canonical patient records.
• Any recommendation meant for clinician review must show:
  • input facts used
  • missing facts
  • why the suggestion was produced
  • what is known vs unknown
• If a feature could cross into regulated autonomous recommendation behavior, gate it behind a disabled-by-default feature flag and document the risk.

Core product requirements:

1. Profiles

• Auto-generate an editable patient profile from onboarding and ongoing data.
• Include demographics, conditions, allergies/intolerances, medications, care-team roles, baseline measurements, goals, and notable safety history.
• Support both patient and clinician views of the same profile with role-based permissions.

2. Medication engine

• Build a canonical medication model with normalized drug name, ingredient, brand name when available, formulation class, strength, route, schedule, indication, start date, stop date, prescriber, adherence history, refill/dispense history if present, and linked outcomes.
• Normalize formulation terminology for the UI into standard release classes: immediate-release, extended-release, sustained-release, prolonged-release, delayed-release, other.
• Preserve original source wording in metadata.

3. Outcome tracking

• Track outcome signals linked to medications and date/time: symptoms, side effects, treatment benefit, treatment satisfaction, sleep, appetite, mood, pain, blood pressure, heart rate, weight, lab values, disease-specific scores, and free-text notes.
• Build a longitudinal timeline UI that overlays medication changes, dose events, formulation changes, patient-reported outcomes, clinician observations, and safety signals.
• Add configurable questionnaires and patient-reported outcome forms.

4. Explainable medication analysis

• Build an analysis engine that can summarize what changed, identify temporal correlations, cluster likely tolerability issues, surface adherence gaps, flag unsafe missing data, and draft follow-up questions for review.
• The engine must produce structured JSON internally.
• The UI must show evidence-linked summaries, not black-box claims.
• Never state causality as certain without clear support.
• Prefer wording like "associated with", "temporally aligned with", and "requires clinician review".

5. Pharmacokinetics and steady-state logic

• Implement a plugin architecture for PK/PD and concentration estimation.
• Default state for all drugs: concentration estimation disabled unless a validated plugin exists.
• If no validated plugin exists, show dosage history, formulation-aware expected coverage window, observed outcomes, and a note that concentration estimation is unavailable for this drug/use case.
• If a validated plugin exists, require explicit evidence metadata, supported population metadata, required inputs, and clear UI labeling that the output is an estimate for support, not a diagnosis.
• Never create a fake generic concentration model for "all medications".

6. Interoperability and data model

• Use a FHIR-aligned internal model.
• Map core objects to concepts equivalent to Patient, Practitioner, MedicationRequest, MedicationStatement, Observation, AdverseEvent, QuestionnaireResponse, Condition, Allergy/Intolerance, CarePlan, and Provenance.
• Keep the internal domain model clean and app-friendly even if not every field is a literal FHIR resource.
• Add import/export boundaries that can evolve toward SMART on FHIR integration.

7. Knowledge layer

• Create adapters/interfaces for medication normalization, label/reference ingestion, terminology mapping, and safety coding.
• Design the data model so it can use sources such as RxNorm, official drug labels, official EU product information, LOINC-like lab identifiers, SNOMED-like clinical concepts, and MedDRA-like adverse event coding without hard-coding one vendor.
• Keep all external knowledge access behind provider interfaces.

8. AI architecture

• Build an internal LLM gateway with a common interface: summarize(), extractStructuredFacts(), generateQuestionnaireDraft(), classifySignal(), draftClinicianNote(), draftPatientSummary().
• Support providers: local, openai, gemini, anthropic, nvidia.
• Add provider capability metadata: structured_output, tool_use, multimodal, local_only, supports_phi_policy.
• Add environment-based configuration for OPENAI_API_KEY, GEMINI_API_KEY, ANTHROPIC_API_KEY, NVIDIA_API_KEY, LOCAL_LLM_BASE_URL, LLM_ROUTING_POLICY.
• Implement routing modes: local_only, hybrid_prefer_local, hybrid_prefer_cloud, cloud_allowed.
• Add PHI routing policy: deny_external_phi, allow_deidentified_only, allow_external_under_contract.
• Enforce the policy in code, not only in docs.

9. Local model strategy

• Support a lightweight local model service first.
• Treat the local model as a task-tuned assistant for extraction, summarization, normalization, timeline labeling, and offline drafts.
• Do not position the local model as a "doctor replacement".
• Add an adapter compatible with an OpenAI-style local endpoint so local inference can be swapped without refactoring product code.
• Add an optional fine-tuning pipeline folder for de-identified training data, eval datasets, PEFT/QLoRA-style adapter training, model cards, and safety notes.
• Keep this pipeline off the critical path for shipping the app.

10. Security, privacy, and governance

• Add role-based access control with at least patient, clinician, and admin.
• Add audit logging for login events, record reads where relevant, record writes, AI generation events, suggestion acceptance/rejection, and export events.
• Encrypt sensitive data at rest where supported by the stack and always secure transport in transit.
• Add consent/policy primitives for data sharing, AI usage consent, external-provider routing, and caregiver access where relevant.
• Redact or de-identify payloads before sending to external providers when policy requires it.
• Make all prompt templates, model providers, and AI outputs observable and versioned.

11. UX and accessibility

• Optimize for usability by both patients and clinicians.
• Use plain language for patient-facing copy and more detailed copy for clinician-facing review screens.
• Ensure strong contrast, keyboard support, screen-reader labels, large touch targets, responsive layouts, chart legends that do not rely on color alone, and concise patient explanations.
• The UI should feel calm, trustworthy, and simple, not experimental or flashy.

12. Delivery expectations

• First inspect the current repo and summarize existing stack, major modules, what already works, and the highest-priority gaps.
• Then implement in vertical slices in this order unless the repo strongly suggests a better sequence: domain model and database/schema cleanup; profile and medication CRUD; longitudinal outcomes and timeline; AI gateway and local model adapter; explainable analysis and review workflow; security/audit/policy enforcement; accessibility and polish; tests and docs.
• Keep migrations safe and reversible where possible.

13. Definition of done The repository is done when all of the following are true:

• a patient or clinician can create or edit a profile
• medications can be added, edited, normalized, and tracked longitudinally
• outcomes can be recorded and visualized in a timeline
• AI can generate explainable summaries with provenance
• local inference works through the gateway
• multiple external providers can be configured through env vars
• external PHI routing policy is enforced
• unsupported concentration estimation is blocked by default
• a validated-plugin interface exists for future drug-specific PK support
• tests cover core domain behavior, provider routing, policy enforcement, and key UI flows
• docs explain setup, architecture, safety boundaries, and extension points

14. Required artifacts Create or update README, architecture overview, data dictionary, AI safety and routing policy document, provider configuration guide, model gateway interfaces, test fixtures and seed data, example eval dataset for medication-summary behavior, and example environment file.

15. Final response format When finished, respond with what changed, key files changed, migrations added, tests run, what remains risky or incomplete, and explicit note about any features intentionally left disabled for safety or validation reasons.