From 2eb82ccdd51a0aad27df792aef27768e0dd408e1 Mon Sep 17 00:00:00 2001 From: codeonym Date: Thu, 15 Oct 2026 16:38:57 +0000 Subject: [PATCH 1/2] docs: establish domain vocabulary and identity scenarios (#5) --- .planning/README.md | 5 +- .../20261015T163800Z-5/D000-modeling-scope.md | 79 ++++++++++++++++ .../D001-staff-identity-and-membership.md | 86 +++++++++++++++++ .../D002-shared-contact-point.md | 92 +++++++++++++++++++ .../D003-request-after-reservation-expiry.md | 89 ++++++++++++++++++ .../decisions/20261015T163800Z-5/session.md | 87 ++++++++++++++++++ .../follow-up.md | 12 ++- .../follow-up.md | 12 ++- GLOSSARY.md | 85 +++++++++++++++++ README.md | 2 + docs/domain-model.md | 48 ++++++++++ 11 files changed, 589 insertions(+), 8 deletions(-) create mode 100644 .planning/decisions/20261015T163800Z-5/D000-modeling-scope.md create mode 100644 .planning/decisions/20261015T163800Z-5/D001-staff-identity-and-membership.md create mode 100644 .planning/decisions/20261015T163800Z-5/D002-shared-contact-point.md create mode 100644 .planning/decisions/20261015T163800Z-5/D003-request-after-reservation-expiry.md create mode 100644 .planning/decisions/20261015T163800Z-5/session.md create mode 100644 GLOSSARY.md create mode 100644 docs/domain-model.md diff --git a/.planning/README.md b/.planning/README.md index e6bb1c9..b95121c 100644 --- a/.planning/README.md +++ b/.planning/README.md @@ -74,6 +74,7 @@ Confirmed planning decisions inform product documents and implementation issues; | Session | Scope | Status | | --- | --- | --- | | [20261015T085738Z-3](decisions/20261015T085738Z-3/session.md) | Product functionality and initial scope; no technical stack | confirmed | +| [20261015T163800Z-5](decisions/20261015T163800Z-5/session.md) | Domain model: practice/contact identity and appointment lifecycle; no stack | active | ## Follow-ups @@ -83,8 +84,8 @@ Confirmed planning decisions inform product documents and implementation issues; | [AI-generated additional UI translations](follow-ups/20261015T110819Z-ai-generated-additional-ui-translations/follow-up.md) | feat | captured | Expansion beyond the initial four languages | | [Choose beta operating countries](follow-ups/20261015T121349Z-choose-beta-operating-countries/follow-up.md) | question | captured | Before beta eligibility/local operating rules | | [Validate WhatsApp linked-line onboarding](follow-ups/20261015T142428Z-validate-whatsapp-linked-line-onboarding/follow-up.md) | research | captured | Technical integration planning before promising connection modes | -| [Define detailed booking and rescheduling policies](follow-ups/20261015T155426Z-define-detailed-booking-policies/follow-up.md) | question | captured | Before implementing the affected scheduling policies or activating them for a practice | -| [Define identity, permissions and sharing access rules](follow-ups/20261015T155426Z-define-identity-permissions-and-sharing/follow-up.md) | question | captured | Before enabling affected record access, membership administration, sharing or booking changes | +| [Define detailed booking and rescheduling policies](follow-ups/20261015T155426Z-define-detailed-booking-policies/follow-up.md) | question | in-progress | Before implementing the affected scheduling policies or activating them for a practice | +| [Define identity, permissions and sharing access rules](follow-ups/20261015T155426Z-define-identity-permissions-and-sharing/follow-up.md) | question | in-progress | Before enabling affected record access, membership administration, sharing or booking changes | | [Define handoff, group and notification workflows](follow-ups/20261015T155426Z-define-handoff-and-notification-workflows/follow-up.md) | question | captured | Before implementing or enabling the corresponding handoff, group or delivery-failure flows | | [Define profile, intake and correction details](follow-ups/20261015T155426Z-define-profile-fields-and-intake-details/follow-up.md) | question | captured | Before implementing affected profile/intake behavior or collecting real patient intake | | [Define beta validation and public-release criteria](follow-ups/20261015T155426Z-define-beta-validation-and-release-gates/follow-up.md) | question | captured | Before inviting real beta practices or claiming readiness for broader advertising | diff --git a/.planning/decisions/20261015T163800Z-5/D000-modeling-scope.md b/.planning/decisions/20261015T163800Z-5/D000-modeling-scope.md new file mode 100644 index 0000000..b7f95da --- /dev/null +++ b/.planning/decisions/20261015T163800Z-5/D000-modeling-scope.md @@ -0,0 +1,79 @@ +--- +{ + "schema_version": 1, + "id": "20261015T163800Z-5/D000", + "session": ".planning/decisions/20261015T163800Z-5/session.md", + "title": "Domain-modeling scope and established vocabulary", + "status": "confirmed", + "round": 0, + "created_at": "2026-10-15T16:38:00Z", + "updated_at": "2026-10-15T16:38:00Z", + "asked_at": null, + "answered_at": null, + "confirmed_at": null, + "decision_owner": "user", + "recorded_by": "assistant", + "issue_url": "https://github.com/codeonym-org/medora/issues/5", + "predecessors": [ + ".planning/decisions/20261015T085738Z-3/D040-shared-understanding-confirmation.md" + ], + "related_decisions": [], + "supersedes": [], + "superseded_by": [], + "affected_components": [ + "Domain vocabulary", + "Domain relationships" + ], + "follow_ups": [], + "sources": [ + ".planning/decisions/20261015T085738Z-3/scope-review.md", + "User message invoking mattpocock-skills:domain-modeling" + ] +} +--- + +# Context — why ask this? + +The user moved from the confirmed product foundation into explicit domain modeling. Existing decisions supply resolved terms; identity and lifecycle relationships still need sharpening. + +## Predecessor decisions + +[Confirmed product foundation](../20261015T085738Z-3/scope-review.md) and its final confirmation. + +## Question + +Not applicable: the user explicitly requested domain-modeling work. + +## Recommendation and alternatives + +Create a root glossary for resolved definitions and a separate domain-model document for relationships/scenarios. No ADR is justified merely by starting a glossary. + +## User reply — original words + +Source: current conversation; original message timestamp unavailable. + +> $mattpocock-skills:domain-modeling lets model the domain, okey? + +## Interpretation + +Actively model the domain using the named skill, checking the confirmed foundation and recording terminology as it crystallizes. Keep the work stack-neutral, consistent with the preceding discussion. + +## Decision and rationale + +Domain-modeling work is authorized. The initial glossary captures already-confirmed concepts; this instruction does not resolve the new scenario questions. + +## Consequences and affected components + +Use GLOSSARY.md for definitions only, docs/domain-model.md for relationship analysis, and this session for the original exchanges. + +## Assumptions, evidence, and open questions + +There is no application code to compare against the concepts. No technology or storage design is selected. + +## Extra notes and follow-ups + +The previous discovery session remains confirmed and unchanged; this is a new session linked to issue #5. + +## History + +- 2026-10-15T16:38:00Z — Recorded the user invocation and initialized the modeling context. diff --git a/.planning/decisions/20261015T163800Z-5/D001-staff-identity-and-membership.md b/.planning/decisions/20261015T163800Z-5/D001-staff-identity-and-membership.md new file mode 100644 index 0000000..70e4e59 --- /dev/null +++ b/.planning/decisions/20261015T163800Z-5/D001-staff-identity-and-membership.md @@ -0,0 +1,86 @@ +--- +{ + "schema_version": 1, + "id": "20261015T163800Z-5/D001", + "session": ".planning/decisions/20261015T163800Z-5/session.md", + "title": "Staff accounts and memberships", + "status": "unanswered", + "round": 1, + "created_at": "2026-10-15T16:38:00Z", + "updated_at": "2026-10-15T16:38:00Z", + "asked_at": null, + "answered_at": null, + "confirmed_at": null, + "decision_owner": "user", + "recorded_by": "assistant", + "issue_url": "https://github.com/codeonym-org/medora/issues/5", + "predecessors": [ + ".planning/decisions/20261015T085738Z-3/D001-first-practice.md", + ".planning/decisions/20261015T085738Z-3/D034-practice-configuration-ownership.md" + ], + "related_decisions": [], + "supersedes": [], + "superseded_by": [], + "affected_components": [ + "Practice Membership", + "Practice Owner", + "Doctor" + ], + "follow_ups": [], + "sources": [ + ".planning/decisions/20261015T085738Z-3/D001-first-practice.md", + ".planning/decisions/20261015T085738Z-3/D034-practice-configuration-ownership.md", + "GLOSSARY.md", + "docs/domain-model.md" + ] +} +--- + +# Context — why ask this? + +A person may work in several practices and an explicit admin account is confirmed. The account identity, membership and role combination now need a precise relationship. + +## Predecessor decisions + +- [D001-first-practice](../20261015T085738Z-3/D001-first-practice.md) +- [D034-practice-configuration-ownership](../20261015T085738Z-3/D034-practice-configuration-ownership.md) + +These established requirements are inputs; no outcome of another first-round modeling question is assumed. + +## Question + +Dr Sara owns Practice A and also works at Practice B. Should she use one Medora staff account with separate memberships, allowing her to be Owner/Admin and Doctor in A but only Doctor in B? + +## Recommendation and alternatives + +Use one staff identity with practice-scoped memberships and role combinations. Entering another practice must change the active permissions and accessible records, not carry the first practice's authority across. + +This is a proposed domain relationship, not a confirmed user choice or implementation decision. + +## User reply — original words + +Pending. Prepared for the first domain-modeling round. + +## Interpretation + +Pending. + +## Decision and rationale + +Pending. + +## Consequences and affected components + +Practice Membership, Practice Owner, Doctor. The reply will sharpen terminology and relationships in the glossary/model. + +## Assumptions, evidence, and open questions + +No database schema, account implementation, global person-matching scheme, automatic verification or request-closure policy is assumed. No application code exists to cross-check. + +## Extra notes and follow-ups + +The booking-policy and identity/permissions follow-ups remain open; vocabulary work does not resolve their full scope. + +## History + +- 2026-10-15T16:38:00Z — Prepared this scenario from the confirmed foundation; user response pending. diff --git a/.planning/decisions/20261015T163800Z-5/D002-shared-contact-point.md b/.planning/decisions/20261015T163800Z-5/D002-shared-contact-point.md new file mode 100644 index 0000000..47ae85e --- /dev/null +++ b/.planning/decisions/20261015T163800Z-5/D002-shared-contact-point.md @@ -0,0 +1,92 @@ +--- +{ + "schema_version": 1, + "id": "20261015T163800Z-5/D002", + "session": ".planning/decisions/20261015T163800Z-5/session.md", + "title": "A shared patient-side number", + "status": "unanswered", + "round": 1, + "created_at": "2026-10-15T16:38:00Z", + "updated_at": "2026-10-15T16:38:00Z", + "asked_at": null, + "answered_at": null, + "confirmed_at": null, + "decision_owner": "user", + "recorded_by": "assistant", + "issue_url": "https://github.com/codeonym-org/medora/issues/5", + "predecessors": [ + ".planning/decisions/20261015T085738Z-3/D016-booking-for-someone-else.md", + ".planning/decisions/20261015T085738Z-3/D019-contact-with-multiple-patient-profiles.md", + ".planning/decisions/20261015T085738Z-3/D025-remembered-language-preference-owner.md", + ".planning/decisions/20261015T085738Z-3/D029-first-contact-existing-record-access.md" + ], + "related_decisions": [], + "supersedes": [], + "superseded_by": [], + "affected_components": [ + "Communication Contact", + "Patient", + "Patient Profile" + ], + "follow_ups": [], + "sources": [ + ".planning/decisions/20261015T085738Z-3/D016-booking-for-someone-else.md", + ".planning/decisions/20261015T085738Z-3/D019-contact-with-multiple-patient-profiles.md", + ".planning/decisions/20261015T085738Z-3/D025-remembered-language-preference-owner.md", + ".planning/decisions/20261015T085738Z-3/D029-first-contact-existing-record-access.md", + "GLOSSARY.md", + "docs/domain-model.md" + ] +} +--- + +# Context — why ask this? + +Patient and Communication Contact are already distinct. The remaining ambiguity is whether an external sender address identifies a unique person; this affects matching, remembered language and representative verification. + +## Predecessor decisions + +- [D016-booking-for-someone-else](../20261015T085738Z-3/D016-booking-for-someone-else.md) +- [D019-contact-with-multiple-patient-profiles](../20261015T085738Z-3/D019-contact-with-multiple-patient-profiles.md) +- [D025-remembered-language-preference-owner](../20261015T085738Z-3/D025-remembered-language-preference-owner.md) +- [D029-first-contact-existing-record-access](../20261015T085738Z-3/D029-first-contact-existing-record-access.md) + +These established requirements are inputs; no outcome of another first-round modeling question is assumed. + +## Question + +Two parents use the same WhatsApp number to arrange appointments for their child. Should Medora allow separate Communication Contacts to share that contact address, rather than assuming the number identifies one person? + +## Recommendation and alternatives + +Yes. Model a contact address separately from the person. If the actual speaker is unclear, ask or leave identity unverified; never infer representative authority or a person-specific preference solely from the shared number. + +This is a proposed domain relationship, not a confirmed user choice or implementation decision. + +## User reply — original words + +Pending. Prepared for the first domain-modeling round. + +## Interpretation + +Pending. + +## Decision and rationale + +Pending. + +## Consequences and affected components + +Communication Contact, Patient, Patient Profile. The reply will sharpen terminology and relationships in the glossary/model. + +## Assumptions, evidence, and open questions + +No database schema, account implementation, global person-matching scheme, automatic verification or request-closure policy is assumed. No application code exists to cross-check. + +## Extra notes and follow-ups + +The booking-policy and identity/permissions follow-ups remain open; vocabulary work does not resolve their full scope. + +## History + +- 2026-10-15T16:38:00Z — Prepared this scenario from the confirmed foundation; user response pending. diff --git a/.planning/decisions/20261015T163800Z-5/D003-request-after-reservation-expiry.md b/.planning/decisions/20261015T163800Z-5/D003-request-after-reservation-expiry.md new file mode 100644 index 0000000..d3c5678 --- /dev/null +++ b/.planning/decisions/20261015T163800Z-5/D003-request-after-reservation-expiry.md @@ -0,0 +1,89 @@ +--- +{ + "schema_version": 1, + "id": "20261015T163800Z-5/D003", + "session": ".planning/decisions/20261015T163800Z-5/session.md", + "title": "Request versus expired reservation", + "status": "unanswered", + "round": 1, + "created_at": "2026-10-15T16:38:00Z", + "updated_at": "2026-10-15T16:38:00Z", + "asked_at": null, + "answered_at": null, + "confirmed_at": null, + "decision_owner": "user", + "recorded_by": "assistant", + "issue_url": "https://github.com/codeonym-org/medora/issues/5", + "predecessors": [ + ".planning/decisions/20261015T085738Z-3/D009-routine-booking-authority.md", + ".planning/decisions/20261015T085738Z-3/D010-provisional-reservation-policy.md", + ".planning/decisions/20261015T085738Z-3/D014-review-deadline-outside-working-hours.md" + ], + "related_decisions": [], + "supersedes": [], + "superseded_by": [], + "affected_components": [ + "Appointment Request", + "Reservation", + "Appointment" + ], + "follow_ups": [], + "sources": [ + ".planning/decisions/20261015T085738Z-3/D009-routine-booking-authority.md", + ".planning/decisions/20261015T085738Z-3/D010-provisional-reservation-policy.md", + ".planning/decisions/20261015T085738Z-3/D014-review-deadline-outside-working-hours.md", + "GLOSSARY.md", + "docs/domain-model.md" + ] +} +--- + +# Context — why ask this? + +Reservation expiry releases time, but the confirmed foundation does not decide whether the patient's underlying request survives. This scenario distinguishes the lifecycles without choosing storage structures. + +## Predecessor decisions + +- [D009-routine-booking-authority](../20261015T085738Z-3/D009-routine-booking-authority.md) +- [D010-provisional-reservation-policy](../20261015T085738Z-3/D010-provisional-reservation-policy.md) +- [D014-review-deadline-outside-working-hours](../20261015T085738Z-3/D014-review-deadline-outside-working-hours.md) + +These established requirements are inputs; no outcome of another first-round modeling question is assumed. + +## Question + +A patient requests Tuesday at 10:00, but the Reservation expires before staff review it. Should the Appointment Request remain open for another slot, or should expiry close the whole request? + +## Recommendation and alternatives + +Keep the request open as needing a new slot, while clearly marking the old reservation expired and telling the contact. Staff or the patient can explicitly withdraw/close the request; an expired hold must never imply a confirmed appointment. + +This is a proposed domain relationship, not a confirmed user choice or implementation decision. + +## User reply — original words + +Pending. Prepared for the first domain-modeling round. + +## Interpretation + +Pending. + +## Decision and rationale + +Pending. + +## Consequences and affected components + +Appointment Request, Reservation, Appointment. The reply will sharpen terminology and relationships in the glossary/model. + +## Assumptions, evidence, and open questions + +No database schema, account implementation, global person-matching scheme, automatic verification or request-closure policy is assumed. No application code exists to cross-check. + +## Extra notes and follow-ups + +The booking-policy and identity/permissions follow-ups remain open; vocabulary work does not resolve their full scope. + +## History + +- 2026-10-15T16:38:00Z — Prepared this scenario from the confirmed foundation; user response pending. diff --git a/.planning/decisions/20261015T163800Z-5/session.md b/.planning/decisions/20261015T163800Z-5/session.md new file mode 100644 index 0000000..5e265be --- /dev/null +++ b/.planning/decisions/20261015T163800Z-5/session.md @@ -0,0 +1,87 @@ +--- +{ + "schema_version": 1, + "id": "20261015T163800Z-5", + "title": "Practice identity, communication identity and appointment lifecycle", + "status": "active", + "session_kind": "domain-modeling", + "created_at": "2026-10-15T16:38:00Z", + "updated_at": "2026-10-15T16:38:00Z", + "repository": "codeonym-org/medora", + "issue_number": 5, + "issue_url": "https://github.com/codeonym-org/medora/issues/5", + "participants": [ + "user", + "assistant" + ], + "facilitator": "assistant", + "origin": { + "conversation_url": null, + "message_reference": "User invocation of mattpocock-skills:domain-modeling", + "related_task": "Model the domain without selecting a stack" + }, + "predecessor_sessions": [ + ".planning/decisions/20261015T085738Z-3/session.md" + ], + "supersedes": [], + "superseded_by": [], + "related_follow_ups": [ + ".planning/follow-ups/20261015T155426Z-define-detailed-booking-policies/follow-up.md", + ".planning/follow-ups/20261015T155426Z-define-identity-permissions-and-sharing/follow-up.md" + ] +} +--- + +# Purpose and context + +Build precise shared language and relationships for Medora using its confirmed product foundation. Capture resolved terminology immediately and stress-test unresolved concepts with concrete situations. + +## Scope and constraints + +In scope: practice membership/roles, patient/contact/communication identity, appointment request/reservation/appointment semantics and relevant lifecycle boundaries. Out of scope: stack selection, database schemas, implementation and arbitrary numerical practice-policy defaults. Expand to other domain concepts only as prerequisites settle. + +## Decision tree + +- Established foundation → glossary definitions already settled. +- Staff account versus practice membership → role combinations and practice-scoped authority. +- Contact person versus shared sender address → matching, preferences and representative authority. +- Reservation expiry versus request closure → request/reservation/appointment lifecycles. +- Later scenarios depend on these answers; do not silently settle them. + +## Decision index and rounds + +| ID / link | Round | Question | Predecessors | Status | Outcome | +| --- | --- | --- | --- | --- | --- | +| [D000](D000-modeling-scope.md) | 0 | Scope and confirmed foundations | Previous session | confirmed | Stack-neutral modeling | +| [D001](D001-staff-identity-and-membership.md) | 1 | Staff accounts and memberships | Linked earlier decisions | unanswered | Pending | +| [D002](D002-shared-contact-point.md) | 1 | A shared patient-side number | Linked earlier decisions | unanswered | Pending | +| [D003](D003-request-after-reservation-expiry.md) | 1 | Request versus expired reservation | Linked earlier decisions | unanswered | Pending | + +## Current frontier + +First modeling round: D001 staff identity/membership; D002 shared patient-side contact address; D003 request after reservation expiry. All are independent scenarios with pending replies. + +## Unresolved or deferred branches + +The three current relationships are unresolved. Patient profile scope remains practice-owned according to the foundation; no global cross-practice patient identity is chosen. Exact permissions, verification, numerical booking policies and implementation boundaries remain in the existing follow-ups. + +## Shared understanding + +The glossary captures established product terms only. Contact Point and Staff Account identity arrangements remain proposals outside the glossary until resolved. Requests, reservations, appointments and delivery outcomes have distinct meanings, but the detailed lifecycle model remains active work. + +## Final user confirmation + +Pending. Domain modeling is active; no new relationship decision is inferred from the invocation. + +## Related follow-ups and work + +Issue: https://github.com/codeonym-org/medora/issues/5. + +[Initial domain model](../../../docs/domain-model.md). + +[Booking policy detail](../../follow-ups/20261015T155426Z-define-detailed-booking-policies/follow-up.md). +[Identity/permissions detail](../../follow-ups/20261015T155426Z-define-identity-permissions-and-sharing/follow-up.md). + +## History + +- 2026-10-15T16:38:00Z — Initialized domain-modeling session and prepared the first three scenarios. diff --git a/.planning/follow-ups/20261015T155426Z-define-detailed-booking-policies/follow-up.md b/.planning/follow-ups/20261015T155426Z-define-detailed-booking-policies/follow-up.md index 4e3b20c..34882e6 100644 --- a/.planning/follow-ups/20261015T155426Z-define-detailed-booking-policies/follow-up.md +++ b/.planning/follow-ups/20261015T155426Z-define-detailed-booking-policies/follow-up.md @@ -4,9 +4,9 @@ "id": "FU-20261015T155426Z-define-detailed-booking-policies", "title": "Define detailed booking and rescheduling policies", "kind": "question", - "status": "captured", + "status": "in-progress", "created_at": "2026-10-15T15:54:26Z", - "updated_at": "2026-10-15T15:54:26Z", + "updated_at": "2026-10-15T16:38:00Z", "observed_at": null, "reported_by": "assistant; deferral explicitly accepted by user in Q47", "owner": null, @@ -40,7 +40,7 @@ ], "related_follow_ups": [], "duplicate_of": null, - "tracking_issue": null, + "tracking_issue": "https://github.com/codeonym-org/medora/issues/5", "revisit": { "trigger": "Before implementing the affected scheduling policies or activating them for a practice", "due_at": null @@ -49,6 +49,10 @@ "resolved_at": null, "outcome": null, "evidence": [] + }, + "active_work": { + "session": ".planning/decisions/20261015T163800Z-5/session.md", + "scope": "Domain terminology and relationships only; remaining detailed policy/access scope stays open" } } --- @@ -104,3 +108,5 @@ Pending. The deferral is accepted; the detailed choices and implementation are n ## Extra notes and history - 2026-10-15T15:54:26Z — Created from the user-approved Q47 deferral; no external outreach, integration changes or application implementation occurred. + +- 2026-10-15T16:38:00Z — Domain-modeling portion started in issue #5 and session 20261015T163800Z-5. Status is in-progress; this does not claim all detailed policies or permissions are being resolved. diff --git a/.planning/follow-ups/20261015T155426Z-define-identity-permissions-and-sharing/follow-up.md b/.planning/follow-ups/20261015T155426Z-define-identity-permissions-and-sharing/follow-up.md index aa48d6a..86a841e 100644 --- a/.planning/follow-ups/20261015T155426Z-define-identity-permissions-and-sharing/follow-up.md +++ b/.planning/follow-ups/20261015T155426Z-define-identity-permissions-and-sharing/follow-up.md @@ -4,9 +4,9 @@ "id": "FU-20261015T155426Z-define-identity-permissions-and-sharing", "title": "Define identity, permissions and sharing access rules", "kind": "question", - "status": "captured", + "status": "in-progress", "created_at": "2026-10-15T15:54:26Z", - "updated_at": "2026-10-15T15:54:26Z", + "updated_at": "2026-10-15T16:38:00Z", "observed_at": null, "reported_by": "assistant; deferral explicitly accepted by user in Q47", "owner": null, @@ -43,7 +43,7 @@ ".planning/follow-ups/20261015T121349Z-choose-beta-operating-countries/follow-up.md" ], "duplicate_of": null, - "tracking_issue": null, + "tracking_issue": "https://github.com/codeonym-org/medora/issues/5", "revisit": { "trigger": "Before enabling affected record access, membership administration, sharing or booking changes", "due_at": null @@ -52,6 +52,10 @@ "resolved_at": null, "outcome": null, "evidence": [] + }, + "active_work": { + "session": ".planning/decisions/20261015T163800Z-5/session.md", + "scope": "Domain terminology and relationships only; remaining detailed policy/access scope stays open" } } --- @@ -107,3 +111,5 @@ Pending. The deferral is accepted; the detailed choices and implementation are n ## Extra notes and history - 2026-10-15T15:54:26Z — Created from the user-approved Q47 deferral; no external outreach, integration changes or application implementation occurred. + +- 2026-10-15T16:38:00Z — Domain-modeling portion started in issue #5 and session 20261015T163800Z-5. Status is in-progress; this does not claim all detailed policies or permissions are being resolved. diff --git a/GLOSSARY.md b/GLOSSARY.md new file mode 100644 index 0000000..19cd7cd --- /dev/null +++ b/GLOSSARY.md @@ -0,0 +1,85 @@ +# Medora + +The language of coordinating a practice, its patients, and its appointments. These terms describe the domain independently of the application stack. + +## Practices and people + +**Practice**: +The organization whose doctors, staff, schedules, and patient information are managed together in Medora. A solo practice and a clinic organization are both practices. +_Avoid_: Clinic when it could mean either the organization or one of its locations; tenant in product language. + +**Practice Membership**: +A person's participation in a particular practice, with the roles and permissions granted there. +_Avoid_: Global role when describing authority in one practice. + +**Practice Owner**: +The practice's designated administrative account holder, responsible for its administration, staff access, and connected communication lines. This responsibility alone does not establish clinical authority. +_Avoid_: Global administrator; Owner/Admin when the precise domain term is needed. + +**Doctor**: +A clinician practicing within a practice who retains responsibility for clinical decisions and approval of clinical intake content. +_Avoid_: Provider when specifically referring to a doctor rather than an external service. + +**Receptionist**: +A practice staff member authorized to coordinate administrative work such as appointment review and patient communication. +_Avoid_: Practice Owner when describing routine reception responsibilities. + +**Patient**: +The person for whom care or a consultation is sought. The patient may be different from the person arranging the appointment. +_Avoid_: WhatsApp user; phone-number holder as a synonym for Patient. + +**Communication Contact**: +The person communicating with the practice about an appointment or patient. A contact may communicate for themselves or for another patient. +_Avoid_: Patient when the speaker and recipient of care may differ; phone number as a synonym for the person. + +**Patient Profile**: +A practice's organized administrative information about a patient, including appointment context and attributed patient-reported information. +_Avoid_: Full medical record; global patient account. + +## Scheduling + +**Appointment Request**: +A request to arrange a consultation, expressing the patient's needs and scheduling preferences. +_Avoid_: Confirmed appointment; Reservation when referring to the request itself. + +**Reservation**: +A temporary, exclusive hold on a proposed appointment time while the required review or agreement is pending. +_Avoid_: Confirmed booking; Appointment as a synonym for an unconfirmed hold. + +**Appointment**: +A scheduled consultation between a patient and a doctor. A confirmed appointment represents the practice-approved commitment to that consultation. +_Avoid_: Reservation when referring to a confirmed consultation. + +**Booking**: +The process of arranging an appointment, from the request through the required review and confirmation. +_Avoid_: Booking as an unqualified synonym for either a temporary hold or a confirmed appointment. + +**Rescheduling Request**: +A request to replace an existing appointment with an agreed appointment time. +_Avoid_: Cancellation when the intention is to retain an appointment at another time. + +**Intake**: +Preliminary information collected for an appointment using practice-approved questions, with the origin of the answers identified. +_Avoid_: Diagnosis; clinician-verified findings when the information is patient-reported. + +## Communication and coordination + +**Communication Line**: +A practice-connected, externally reachable communication endpoint through which contacts converse with the practice, initially a WhatsApp line. The line may represent one doctor or a group of doctors. +_Avoid_: Communication Contact when referring to the endpoint; global Medora number as an assumed routing model. + +**Patient Conversation**: +A conversation between the practice and a communication contact concerning a patient or appointment. +_Avoid_: Private Staff Conversation when referring to messages involving the contact. + +**Staff Conversation**: +A private conversation between a staff user and Medora's assistant in the practice-management platform. +_Avoid_: Shared patient chat; practice-wide transcript as the default meaning. + +**Handoff**: +A transfer of active responsibility for a patient conversation from the agent to authorized staff, initially the practice-configured default staff member. +_Avoid_: Patient group as a synonym for every Handoff. + +**Appointment Notification**: +A communication about an appointment request, reservation, confirmed appointment, or subsequent change. Its delivery outcome is distinct from the appointment's outcome. +_Avoid_: Appointment confirmation when describing delivery alone. diff --git a/README.md b/README.md index 217833d..59c4d61 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,8 @@ Medora is an AI medical secretary for doctors and clinics. It will coordinate ap The repository currently contains product documentation and engineering infrastructure. No application, patient-data storage, AI integration, or clinical service is implemented. Development starts with reliable scheduling and backend permission enforcement. - [Product vision and phased scope](docs/product-vision.md) +- [Domain vocabulary](GLOSSARY.md) +- [Evolving domain model](docs/domain-model.md) - [Contribution workflow](CONTRIBUTING.md) - [GitHub rules and automation](docs/github-workflow.md) - [Project board](https://github.com/orgs/codeonym-org/projects/3) diff --git a/docs/domain-model.md b/docs/domain-model.md new file mode 100644 index 0000000..7220d72 --- /dev/null +++ b/docs/domain-model.md @@ -0,0 +1,48 @@ +# Medora domain model + +This is an evolving, stack-neutral model grounded in the [confirmed product foundation](../.planning/decisions/20261015T085738Z-3/scope-review.md). [GLOSSARY.md](../GLOSSARY.md) holds resolved definitions only. [The active modeling session](../.planning/decisions/20261015T163800Z-5/session.md) holds questions, replies, interpretation and history. + +## Established semantic boundaries + +- A **Practice** owns its operational records and patient profiles. A person's **Practice Membership** scopes authority in that practice. +- The **Patient** receives care. The **Communication Contact** speaks to the practice and may represent another patient. A practice-connected **Communication Line** is an endpoint, not a person. +- An **Appointment Request** expresses intent; a **Reservation** claims time provisionally; an **Appointment** represents the scheduled consultation. These meanings do not prescribe separate database tables or entity identifiers. +- **Appointment Notification** delivery is distinct from appointment confirmation. A failed message does not silently cancel a confirmed appointment. +- **Patient Profile** and **Intake** preserve the origin of information. An AI summary is not a clinician-verified finding. +- **Staff Conversation** is private by default; **Patient Conversation** involves the contact. **Handoff** changes who actively handles that patient conversation, not who has authority over every practice record. + +## Concept relationships already supported by the foundation + +The diagram shows meaning, not storage, cardinality or a finalized aggregate design. + +```mermaid +flowchart LR + Practice -->|owns| Profile[Patient Profile] + Profile -->|describes| Patient + Practice -->|connects| Line[Communication Line] + Line -->|carries| Conversation[Patient Conversation] + Contact[Communication Contact] -->|participates in| Conversation + Request[Appointment Request] -->|concerns| Patient + Hold[Reservation] -->|holds time for| Request + Request -->|may result in| Appointment + Appointment -->|for| Patient + Appointment -->|with| Doctor +``` + +## First unresolved relationships + +| Scenario | What it tests | Current proposal | +| --- | --- | --- | +| Doctor owns one practice and works at another | Staff identity versus practice membership; multiple roles | One staff identity with independent practice memberships and role combinations | +| Two adults share one WhatsApp number | Contact person versus sender address | A separate contact-address concept; do not infer speaker identity from a number | +| Reservation expires before staff review | Request lifecycle versus temporary hold lifecycle | Keep the underlying request open, explicitly without a reserved slot | + +These are proposals, not accepted domain rules. Their exact questions and recommendations are in the active session. The proposed contact-address term **Contact Point** is deliberately not yet added to the glossary. + +## Questions intentionally still open + +Account and membership cardinalities, shared addresses, request closure, and detailed cross-practice identity relationships require explicit modeling decisions. The accepted practice-scoped record boundary remains in force. Later lifecycle scenarios must address hold/replacement expiry, verification, staff approval, cancellation and rescheduling using the confirmed rules, without choosing storage structures prematurely. + +## Relation to existing follow-ups + +This session advances the domain-modeling portion of booking-policy and identity/permission work. It does not resolve their numerical settings, verification evidence, fine-grained permissions or complete acceptance matrices. No application code exists to contradict or validate the model; there is only repository tooling and documentation. From d9e87e2ee8fa54cf6fae9783d6ae5a0f84966a1b Mon Sep 17 00:00:00 2001 From: codeonym Date: Fri, 16 Oct 2026 10:19:06 +0000 Subject: [PATCH 2/2] docs: resolve initial identities and extend domain scenarios (#5) --- .../D001-staff-identity-and-membership.md | 29 +++++-- .../D002-shared-contact-point.md | 29 +++++-- .../D003-request-after-reservation-expiry.md | 26 ++++-- ...D004-one-active-reservation-per-request.md | 86 ++++++++++++++++++ ...-appointment-continuity-on-rescheduling.md | 83 ++++++++++++++++++ ...06-receptionist-doctor-assignment-scope.md | 87 +++++++++++++++++++ .../decisions/20261015T163800Z-5/session.md | 32 ++++--- .../follow-up.md | 7 +- .../follow-up.md | 8 +- GLOSSARY.md | 12 ++- docs/domain-model.md | 30 +++++-- 11 files changed, 377 insertions(+), 52 deletions(-) create mode 100644 .planning/decisions/20261015T163800Z-5/D004-one-active-reservation-per-request.md create mode 100644 .planning/decisions/20261015T163800Z-5/D005-appointment-continuity-on-rescheduling.md create mode 100644 .planning/decisions/20261015T163800Z-5/D006-receptionist-doctor-assignment-scope.md diff --git a/.planning/decisions/20261015T163800Z-5/D001-staff-identity-and-membership.md b/.planning/decisions/20261015T163800Z-5/D001-staff-identity-and-membership.md index 70e4e59..e6af9ac 100644 --- a/.planning/decisions/20261015T163800Z-5/D001-staff-identity-and-membership.md +++ b/.planning/decisions/20261015T163800Z-5/D001-staff-identity-and-membership.md @@ -4,10 +4,10 @@ "id": "20261015T163800Z-5/D001", "session": ".planning/decisions/20261015T163800Z-5/session.md", "title": "Staff accounts and memberships", - "status": "unanswered", + "status": "confirmed", "round": 1, "created_at": "2026-10-15T16:38:00Z", - "updated_at": "2026-10-15T16:38:00Z", + "updated_at": "2026-10-16T10:18:23Z", "asked_at": null, "answered_at": null, "confirmed_at": null, @@ -24,7 +24,8 @@ "affected_components": [ "Practice Membership", "Practice Owner", - "Doctor" + "Doctor", + "Staff Account" ], "follow_ups": [], "sources": [ @@ -32,7 +33,9 @@ ".planning/decisions/20261015T085738Z-3/D034-practice-configuration-ownership.md", "GLOSSARY.md", "docs/domain-model.md" - ] + ], + "reply_recorded_at": "2026-10-16T10:18:23Z", + "reply_reference": "Joint user reply: ok, next; in response to the three first-round recommendations" } --- @@ -55,19 +58,25 @@ Dr Sara owns Practice A and also works at Practice B. Should she use one Medora Use one staff identity with practice-scoped memberships and role combinations. Entering another practice must change the active permissions and accessible records, not carry the first practice's authority across. -This is a proposed domain relationship, not a confirmed user choice or implementation decision. +This was the recommendation presented before the joint reply; the acceptance and its limited interpretation are recorded below. ## User reply — original words -Pending. Prepared for the first domain-modeling round. +Joint reply to the first three modeling recommendations, recorded 2026-10-16T10:18:23Z; original message timestamp unavailable: + +> ok, next ## Interpretation -Pending. +Read as acceptance of the three recommendations just presented and a request to continue. This is a joint acknowledgment, not three separately worded answers. For this decision: One Staff Account can hold separate Practice Memberships, with multiple roles in a membership. Sara can be Owner/Admin and Doctor in A and Doctor only in B; authority and records remain practice-scoped. + +No additional policy values, verification method or implementation choices are inferred. ## Decision and rationale -Pending. +Confirmed within this scenario: One Staff Account can hold separate Practice Memberships, with multiple roles in a membership. Sara can be Owner/Admin and Doctor in A and Doctor only in B; authority and records remain practice-scoped. + +The user supplied no separate rationale. The recommendation and its reasoning above are assistant-authored. ## Consequences and affected components @@ -75,7 +84,7 @@ Practice Membership, Practice Owner, Doctor. The reply will sharpen terminology ## Assumptions, evidence, and open questions -No database schema, account implementation, global person-matching scheme, automatic verification or request-closure policy is assumed. No application code exists to cross-check. +The joint reply confirms the relationship described above. No database schema, account implementation, global person-matching scheme or automatic verification method is selected. Detailed permissions and independent request-closure policies remain open. No application code exists to cross-check. ## Extra notes and follow-ups @@ -84,3 +93,5 @@ The booking-policy and identity/permissions follow-ups remain open; vocabulary w ## History - 2026-10-15T16:38:00Z — Prepared this scenario from the confirmed foundation; user response pending. + +- 2026-10-16T10:18:23Z — Saved the joint reply verbatim and recorded its acceptance of the existing recommendation; no additional commitments inferred. diff --git a/.planning/decisions/20261015T163800Z-5/D002-shared-contact-point.md b/.planning/decisions/20261015T163800Z-5/D002-shared-contact-point.md index 47ae85e..f20ebc8 100644 --- a/.planning/decisions/20261015T163800Z-5/D002-shared-contact-point.md +++ b/.planning/decisions/20261015T163800Z-5/D002-shared-contact-point.md @@ -4,10 +4,10 @@ "id": "20261015T163800Z-5/D002", "session": ".planning/decisions/20261015T163800Z-5/session.md", "title": "A shared patient-side number", - "status": "unanswered", + "status": "confirmed", "round": 1, "created_at": "2026-10-15T16:38:00Z", - "updated_at": "2026-10-15T16:38:00Z", + "updated_at": "2026-10-16T10:18:23Z", "asked_at": null, "answered_at": null, "confirmed_at": null, @@ -26,7 +26,8 @@ "affected_components": [ "Communication Contact", "Patient", - "Patient Profile" + "Patient Profile", + "Contact Point" ], "follow_ups": [], "sources": [ @@ -36,7 +37,9 @@ ".planning/decisions/20261015T085738Z-3/D029-first-contact-existing-record-access.md", "GLOSSARY.md", "docs/domain-model.md" - ] + ], + "reply_recorded_at": "2026-10-16T10:18:23Z", + "reply_reference": "Joint user reply: ok, next; in response to the three first-round recommendations" } --- @@ -61,19 +64,25 @@ Two parents use the same WhatsApp number to arrange appointments for their child Yes. Model a contact address separately from the person. If the actual speaker is unclear, ask or leave identity unverified; never infer representative authority or a person-specific preference solely from the shared number. -This is a proposed domain relationship, not a confirmed user choice or implementation decision. +This was the recommendation presented before the joint reply; the acceptance and its limited interpretation are recorded below. ## User reply — original words -Pending. Prepared for the first domain-modeling round. +Joint reply to the first three modeling recommendations, recorded 2026-10-16T10:18:23Z; original message timestamp unavailable: + +> ok, next ## Interpretation -Pending. +Read as acceptance of the three recommendations just presented and a request to continue. This is a joint acknowledgment, not three separately worded answers. For this decision: Separate Communication Contacts may share a Contact Point. A shared address alone establishes neither the speaker, representative authority nor a person-specific preference; ask or leave identity unverified when uncertain. + +No additional policy values, verification method or implementation choices are inferred. ## Decision and rationale -Pending. +Confirmed within this scenario: Separate Communication Contacts may share a Contact Point. A shared address alone establishes neither the speaker, representative authority nor a person-specific preference; ask or leave identity unverified when uncertain. + +The user supplied no separate rationale. The recommendation and its reasoning above are assistant-authored. ## Consequences and affected components @@ -81,7 +90,7 @@ Communication Contact, Patient, Patient Profile. The reply will sharpen terminol ## Assumptions, evidence, and open questions -No database schema, account implementation, global person-matching scheme, automatic verification or request-closure policy is assumed. No application code exists to cross-check. +The joint reply confirms the relationship described above. No database schema, account implementation, global person-matching scheme or automatic verification method is selected. Detailed permissions and independent request-closure policies remain open. No application code exists to cross-check. ## Extra notes and follow-ups @@ -90,3 +99,5 @@ The booking-policy and identity/permissions follow-ups remain open; vocabulary w ## History - 2026-10-15T16:38:00Z — Prepared this scenario from the confirmed foundation; user response pending. + +- 2026-10-16T10:18:23Z — Saved the joint reply verbatim and recorded its acceptance of the existing recommendation; no additional commitments inferred. diff --git a/.planning/decisions/20261015T163800Z-5/D003-request-after-reservation-expiry.md b/.planning/decisions/20261015T163800Z-5/D003-request-after-reservation-expiry.md index d3c5678..32d3d9b 100644 --- a/.planning/decisions/20261015T163800Z-5/D003-request-after-reservation-expiry.md +++ b/.planning/decisions/20261015T163800Z-5/D003-request-after-reservation-expiry.md @@ -4,10 +4,10 @@ "id": "20261015T163800Z-5/D003", "session": ".planning/decisions/20261015T163800Z-5/session.md", "title": "Request versus expired reservation", - "status": "unanswered", + "status": "confirmed", "round": 1, "created_at": "2026-10-15T16:38:00Z", - "updated_at": "2026-10-15T16:38:00Z", + "updated_at": "2026-10-16T10:18:23Z", "asked_at": null, "answered_at": null, "confirmed_at": null, @@ -34,7 +34,9 @@ ".planning/decisions/20261015T085738Z-3/D014-review-deadline-outside-working-hours.md", "GLOSSARY.md", "docs/domain-model.md" - ] + ], + "reply_recorded_at": "2026-10-16T10:18:23Z", + "reply_reference": "Joint user reply: ok, next; in response to the three first-round recommendations" } --- @@ -58,19 +60,25 @@ A patient requests Tuesday at 10:00, but the Reservation expires before staff re Keep the request open as needing a new slot, while clearly marking the old reservation expired and telling the contact. Staff or the patient can explicitly withdraw/close the request; an expired hold must never imply a confirmed appointment. -This is a proposed domain relationship, not a confirmed user choice or implementation decision. +This was the recommendation presented before the joint reply; the acceptance and its limited interpretation are recorded below. ## User reply — original words -Pending. Prepared for the first domain-modeling round. +Joint reply to the first three modeling recommendations, recorded 2026-10-16T10:18:23Z; original message timestamp unavailable: + +> ok, next ## Interpretation -Pending. +Read as acceptance of the three recommendations just presented and a request to continue. This is a joint acknowledgment, not three separately worded answers. For this decision: Reservation expiry releases the slot and triggers notification, while the Appointment Request stays open needing another slot. Explicit withdrawal or closure remains possible; expiry never confirms an appointment. + +No additional policy values, verification method or implementation choices are inferred. ## Decision and rationale -Pending. +Confirmed within this scenario: Reservation expiry releases the slot and triggers notification, while the Appointment Request stays open needing another slot. Explicit withdrawal or closure remains possible; expiry never confirms an appointment. + +The user supplied no separate rationale. The recommendation and its reasoning above are assistant-authored. ## Consequences and affected components @@ -78,7 +86,7 @@ Appointment Request, Reservation, Appointment. The reply will sharpen terminolog ## Assumptions, evidence, and open questions -No database schema, account implementation, global person-matching scheme, automatic verification or request-closure policy is assumed. No application code exists to cross-check. +The joint reply confirms the relationship described above. No database schema, account implementation, global person-matching scheme or automatic verification method is selected. Detailed permissions and independent request-closure policies remain open. No application code exists to cross-check. ## Extra notes and follow-ups @@ -87,3 +95,5 @@ The booking-policy and identity/permissions follow-ups remain open; vocabulary w ## History - 2026-10-15T16:38:00Z — Prepared this scenario from the confirmed foundation; user response pending. + +- 2026-10-16T10:18:23Z — Saved the joint reply verbatim and recorded its acceptance of the existing recommendation; no additional commitments inferred. diff --git a/.planning/decisions/20261015T163800Z-5/D004-one-active-reservation-per-request.md b/.planning/decisions/20261015T163800Z-5/D004-one-active-reservation-per-request.md new file mode 100644 index 0000000..a945434 --- /dev/null +++ b/.planning/decisions/20261015T163800Z-5/D004-one-active-reservation-per-request.md @@ -0,0 +1,86 @@ +--- +{ + "schema_version": 1, + "id": "20261015T163800Z-5/D004", + "session": ".planning/decisions/20261015T163800Z-5/session.md", + "title": "One active reservation per request", + "status": "unanswered", + "round": 2, + "created_at": "2026-10-16T10:18:23Z", + "updated_at": "2026-10-16T10:18:23Z", + "asked_at": null, + "answered_at": null, + "confirmed_at": null, + "decision_owner": "user", + "recorded_by": "assistant", + "issue_url": "https://github.com/codeonym-org/medora/issues/5", + "predecessors": [ + ".planning/decisions/20261015T163800Z-5/D003-request-after-reservation-expiry.md", + ".planning/decisions/20261015T085738Z-3/D037-keep-original-during-rescheduling.md" + ], + "related_decisions": [], + "supersedes": [], + "superseded_by": [], + "affected_components": [ + "Appointment Request", + "Reservation", + "Availability" + ], + "follow_ups": [], + "sources": [ + ".planning/decisions/20261015T163800Z-5/D003-request-after-reservation-expiry.md", + ".planning/decisions/20261015T085738Z-3/D037-keep-original-during-rescheduling.md", + "GLOSSARY.md", + "docs/domain-model.md" + ] +} +--- + +# Context — why ask this? + +An open request can outlive a reservation. Offering several choices must now be distinguished from provisionally removing several slots from availability. + +## Predecessor decisions + +- [D003-request-after-reservation-expiry](D003-request-after-reservation-expiry.md) +- [D037-keep-original-during-rescheduling](../20261015T085738Z-3/D037-keep-original-during-rescheduling.md) + +The linked outcomes are settled prerequisites. No other round 2 answer is assumed. + +## Question + +Q4 — A patient is choosing between Tuesday at 10:00 and Wednesday at 14:00. Should one Appointment Request hold only one selected slot at a time, while the other times remain suggestions? + +## Recommendation and alternatives + +Yes: allow one active Reservation per Appointment Request. On an authorized switch, replace the old hold with the new one; if the switch fails, do not claim it succeeded or silently discard a still-valid hold. A confirmed original appointment during rescheduling is separate and remains protected by the existing rule. The alternative is holding several choices, which consumes capacity before the patient chooses. This does not set a global per-person limit or settle duplicate-request policy. + +Proposed only; awaiting the user's reply. + +## User reply — original words + +Pending. Prepared for round 2; no reply received. + +## Interpretation + +Pending. + +## Decision and rationale + +Pending. + +## Consequences and affected components + +Appointment Request, Reservation, Availability. A reply will refine the domain relationship and its acceptance scenarios without selecting implementation details. + +## Assumptions, evidence, and open questions + +All people and times in this scenario are synthetic. No application code exists to compare. Detailed policy values, verification mechanisms and storage choices remain outside this question. + +## Extra notes and follow-ups + +Existing booking-policy and identity/permission follow-ups remain in progress. This round does not resolve their entire scope. + +## History + +- 2026-10-16T10:18:23Z — Prepared the round 2 question after saving the joint round 1 answer. diff --git a/.planning/decisions/20261015T163800Z-5/D005-appointment-continuity-on-rescheduling.md b/.planning/decisions/20261015T163800Z-5/D005-appointment-continuity-on-rescheduling.md new file mode 100644 index 0000000..a09386e --- /dev/null +++ b/.planning/decisions/20261015T163800Z-5/D005-appointment-continuity-on-rescheduling.md @@ -0,0 +1,83 @@ +--- +{ + "schema_version": 1, + "id": "20261015T163800Z-5/D005", + "session": ".planning/decisions/20261015T163800Z-5/session.md", + "title": "Appointment continuity on rescheduling", + "status": "unanswered", + "round": 2, + "created_at": "2026-10-16T10:18:23Z", + "updated_at": "2026-10-16T10:18:23Z", + "asked_at": null, + "answered_at": null, + "confirmed_at": null, + "decision_owner": "user", + "recorded_by": "assistant", + "issue_url": "https://github.com/codeonym-org/medora/issues/5", + "predecessors": [ + ".planning/decisions/20261015T085738Z-3/D037-keep-original-during-rescheduling.md" + ], + "related_decisions": [], + "supersedes": [], + "superseded_by": [], + "affected_components": [ + "Appointment", + "Rescheduling Request", + "Appointment history" + ], + "follow_ups": [], + "sources": [ + ".planning/decisions/20261015T085738Z-3/D037-keep-original-during-rescheduling.md", + "GLOSSARY.md", + "docs/domain-model.md" + ] +} +--- + +# Context — why ask this? + +The original slot is retained until replacement approval and patient agreement. We have not decided whether the resulting consultation is the same appointment or a cancellation followed by an unrelated booking; this changes history and how the outcome is explained. + +## Predecessor decisions + +- [D037-keep-original-during-rescheduling](../20261015T085738Z-3/D037-keep-original-during-rescheduling.md) + +The linked outcomes are settled prerequisites. No other round 2 answer is assumed. + +## Question + +Q5 — A confirmed Monday appointment moves to Thursday after approval and patient agreement. Should it remain the same Appointment, with a recorded time-change history, rather than count as a cancellation and an unrelated new appointment? + +## Recommendation and alternatives + +Keep the same Appointment and record the approved change, linked to its Rescheduling Request. Preserve the original commitment until the replacement succeeds. A genuinely cancelled appointment remains cancelled; a later fresh booking is separate. The alternative is cancel-and-create for every move, which can obscure continuity and cancellation reporting. This is domain continuity, not a database identifier or storage decision. + +Proposed only; awaiting the user's reply. + +## User reply — original words + +Pending. Prepared for round 2; no reply received. + +## Interpretation + +Pending. + +## Decision and rationale + +Pending. + +## Consequences and affected components + +Appointment, Rescheduling Request, Appointment history. A reply will refine the domain relationship and its acceptance scenarios without selecting implementation details. + +## Assumptions, evidence, and open questions + +All people and times in this scenario are synthetic. No application code exists to compare. Detailed policy values, verification mechanisms and storage choices remain outside this question. + +## Extra notes and follow-ups + +Existing booking-policy and identity/permission follow-ups remain in progress. This round does not resolve their entire scope. + +## History + +- 2026-10-16T10:18:23Z — Prepared the round 2 question after saving the joint round 1 answer. diff --git a/.planning/decisions/20261015T163800Z-5/D006-receptionist-doctor-assignment-scope.md b/.planning/decisions/20261015T163800Z-5/D006-receptionist-doctor-assignment-scope.md new file mode 100644 index 0000000..18e8e24 --- /dev/null +++ b/.planning/decisions/20261015T163800Z-5/D006-receptionist-doctor-assignment-scope.md @@ -0,0 +1,87 @@ +--- +{ + "schema_version": 1, + "id": "20261015T163800Z-5/D006", + "session": ".planning/decisions/20261015T163800Z-5/session.md", + "title": "Receptionist doctor assignment scope", + "status": "unanswered", + "round": 2, + "created_at": "2026-10-16T10:18:23Z", + "updated_at": "2026-10-16T10:18:23Z", + "asked_at": null, + "answered_at": null, + "confirmed_at": null, + "decision_owner": "user", + "recorded_by": "assistant", + "issue_url": "https://github.com/codeonym-org/medora/issues/5", + "predecessors": [ + ".planning/decisions/20261015T163800Z-5/D001-staff-identity-and-membership.md", + ".planning/decisions/20261015T085738Z-3/D034-practice-configuration-ownership.md" + ], + "related_decisions": [], + "supersedes": [], + "superseded_by": [], + "affected_components": [ + "Practice Membership", + "Receptionist", + "Doctor", + "Administrative access" + ], + "follow_ups": [], + "sources": [ + ".planning/decisions/20261015T163800Z-5/D001-staff-identity-and-membership.md", + ".planning/decisions/20261015T085738Z-3/D034-practice-configuration-ownership.md", + "GLOSSARY.md", + "docs/domain-model.md" + ] +} +--- + +# Context — why ask this? + +Membership roles are practice-scoped, but a practice may contain several doctors. A Receptionist role alone does not yet tell us whether the person coordinates every doctor or an assigned subset. + +## Predecessor decisions + +- [D001-staff-identity-and-membership](D001-staff-identity-and-membership.md) +- [D034-practice-configuration-ownership](../20261015T085738Z-3/D034-practice-configuration-ownership.md) + +The linked outcomes are settled prerequisites. No other round 2 answer is assumed. + +## Question + +Q6 — A practice has Dr Sara and Dr Omar. Should the owner be able to assign a receptionist to Sara only, with a separate explicit option to coordinate all doctors in that practice? + +## Recommendation and alternatives + +Yes: make doctor coverage an explicit scope within the practice membership. The role alone should not silently grant access to every doctor's appointments or profiles. Coverage authorizes only the configured administrative work and does not itself grant clinical access. The alternative is practice-wide reception by default, which is simpler but cannot represent a restricted assignment. Shared-patient profile visibility and exact permissions need their own later decisions. + +Proposed only; awaiting the user's reply. + +## User reply — original words + +Pending. Prepared for round 2; no reply received. + +## Interpretation + +Pending. + +## Decision and rationale + +Pending. + +## Consequences and affected components + +Practice Membership, Receptionist, Doctor, Administrative access. A reply will refine the domain relationship and its acceptance scenarios without selecting implementation details. + +## Assumptions, evidence, and open questions + +All people and times in this scenario are synthetic. No application code exists to compare. Detailed policy values, verification mechanisms and storage choices remain outside this question. + +## Extra notes and follow-ups + +Existing booking-policy and identity/permission follow-ups remain in progress. This round does not resolve their entire scope. + +## History + +- 2026-10-16T10:18:23Z — Prepared the round 2 question after saving the joint round 1 answer. diff --git a/.planning/decisions/20261015T163800Z-5/session.md b/.planning/decisions/20261015T163800Z-5/session.md index 5e265be..2a72768 100644 --- a/.planning/decisions/20261015T163800Z-5/session.md +++ b/.planning/decisions/20261015T163800Z-5/session.md @@ -6,7 +6,7 @@ "status": "active", "session_kind": "domain-modeling", "created_at": "2026-10-15T16:38:00Z", - "updated_at": "2026-10-15T16:38:00Z", + "updated_at": "2026-10-16T10:18:23Z", "repository": "codeonym-org/medora", "issue_number": 5, "issue_url": "https://github.com/codeonym-org/medora/issues/5", @@ -43,40 +43,46 @@ In scope: practice membership/roles, patient/contact/communication identity, app ## Decision tree - Established foundation → glossary definitions already settled. -- Staff account versus practice membership → role combinations and practice-scoped authority. -- Contact person versus shared sender address → matching, preferences and representative authority. -- Reservation expiry versus request closure → request/reservation/appointment lifecycles. -- Later scenarios depend on these answers; do not silently settle them. +- D001 accepted staff account versus membership → D006 receptionist coverage within a practice. +- D002 accepted contact versus shared address → exact verification and representative-access rules still open in the identity follow-up. +- D003 accepted request survival after hold expiry → D004 active-hold limit per request. +- Confirmed foundation retains the original during rescheduling → D005 appointment continuity after an approved move. +- Round 2 questions are independent; do not infer one answer from another. ## Decision index and rounds | ID / link | Round | Question | Predecessors | Status | Outcome | | --- | --- | --- | --- | --- | --- | | [D000](D000-modeling-scope.md) | 0 | Scope and confirmed foundations | Previous session | confirmed | Stack-neutral modeling | -| [D001](D001-staff-identity-and-membership.md) | 1 | Staff accounts and memberships | Linked earlier decisions | unanswered | Pending | -| [D002](D002-shared-contact-point.md) | 1 | A shared patient-side number | Linked earlier decisions | unanswered | Pending | -| [D003](D003-request-after-reservation-expiry.md) | 1 | Request versus expired reservation | Linked earlier decisions | unanswered | Pending | +| [D001](D001-staff-identity-and-membership.md) | 1 | Staff accounts and memberships | Linked earlier decisions | confirmed | One account, independent practice memberships and role combinations | +| [D002](D002-shared-contact-point.md) | 1 | A shared patient-side number | Linked earlier decisions | confirmed | Separate people may share a Contact Point | +| [D003](D003-request-after-reservation-expiry.md) | 1 | Request versus expired reservation | Linked earlier decisions | confirmed | Request stays open after the reservation expires | +| [D004](D004-one-active-reservation-per-request.md) | 2 | One active reservation per request | Linked settled decisions | unanswered | Pending | +| [D005](D005-appointment-continuity-on-rescheduling.md) | 2 | Appointment continuity on rescheduling | Linked settled decisions | unanswered | Pending | +| [D006](D006-receptionist-doctor-assignment-scope.md) | 2 | Receptionist doctor assignment scope | Linked settled decisions | unanswered | Pending | ## Current frontier -First modeling round: D001 staff identity/membership; D002 shared patient-side contact address; D003 request after reservation expiry. All are independent scenarios with pending replies. +Round 1 is recorded and accepted through the joint reply "ok, next". Round 2 tests D004 one active hold per request, D005 appointment continuity on rescheduling and D006 receptionist doctor coverage. These independent scenarios have settled prerequisites; all three replies are pending. ## Unresolved or deferred branches -The three current relationships are unresolved. Patient profile scope remains practice-owned according to the foundation; no global cross-practice patient identity is chosen. Exact permissions, verification, numerical booking policies and implementation boundaries remain in the existing follow-ups. +Round 2 relationships are proposals only. Global patient identity, exact verification and permission matrices, duplicate-request handling, shared-patient profile access, request inactivity/closure policy and numerical booking settings remain unresolved in the existing follow-ups. ## Shared understanding -The glossary captures established product terms only. Contact Point and Staff Account identity arrangements remain proposals outside the glossary until resolved. Requests, reservations, appointments and delivery outcomes have distinct meanings, but the detailed lifecycle model remains active work. +One Staff Account may have independent Practice Memberships with multiple roles. Communication Contacts may share a Contact Point without the address proving identity or authority. Expiry releases a Reservation but leaves its Appointment Request open needing another slot. Definitions are updated in the glossary; the complete domain model is not yet confirmed. ## Final user confirmation -Pending. Domain modeling is active; no new relationship decision is inferred from the invocation. +Pending for the complete session. The user accepted the first three recommendations with "ok, next"; this is not confirmation of unanswered later scenarios or authorization to implement their proposals. ## Related follow-ups and work Issue: https://github.com/codeonym-org/medora/issues/5. +Draft PR: https://github.com/codeonym-org/medora/pull/6. + [Initial domain model](../../../docs/domain-model.md). [Booking policy detail](../../follow-ups/20261015T155426Z-define-detailed-booking-policies/follow-up.md). @@ -85,3 +91,5 @@ Issue: https://github.com/codeonym-org/medora/issues/5. ## History - 2026-10-15T16:38:00Z — Initialized domain-modeling session and prepared the first three scenarios. + +- 2026-10-16T10:18:23Z — Recorded joint acceptance of D001–D003, updated resolved vocabulary and prepared independent round 2 scenarios D004–D006. diff --git a/.planning/follow-ups/20261015T155426Z-define-detailed-booking-policies/follow-up.md b/.planning/follow-ups/20261015T155426Z-define-detailed-booking-policies/follow-up.md index 34882e6..4f4de4e 100644 --- a/.planning/follow-ups/20261015T155426Z-define-detailed-booking-policies/follow-up.md +++ b/.planning/follow-ups/20261015T155426Z-define-detailed-booking-policies/follow-up.md @@ -6,7 +6,7 @@ "kind": "question", "status": "in-progress", "created_at": "2026-10-15T15:54:26Z", - "updated_at": "2026-10-15T16:38:00Z", + "updated_at": "2026-10-16T10:18:23Z", "observed_at": null, "reported_by": "assistant; deferral explicitly accepted by user in Q47", "owner": null, @@ -33,7 +33,8 @@ ".planning/decisions/20261015T085738Z-3/D032-first-increment-appointment-lifecycle.md", ".planning/decisions/20261015T085738Z-3/D035-verified-patient-cancellation.md", ".planning/decisions/20261015T085738Z-3/D037-keep-original-during-rescheduling.md", - ".planning/decisions/20261015T085738Z-3/D039-focused-design-followups.md" + ".planning/decisions/20261015T085738Z-3/D039-focused-design-followups.md", + ".planning/decisions/20261015T163800Z-5/D003-request-after-reservation-expiry.md" ], "dependencies": [ ".planning/decisions/20261015T085738Z-3/scope-review.md" @@ -110,3 +111,5 @@ Pending. The deferral is accepted; the detailed choices and implementation are n - 2026-10-15T15:54:26Z — Created from the user-approved Q47 deferral; no external outreach, integration changes or application implementation occurred. - 2026-10-15T16:38:00Z — Domain-modeling portion started in issue #5 and session 20261015T163800Z-5. Status is in-progress; this does not claim all detailed policies or permissions are being resolved. + +- 2026-10-16T10:18:23Z — Accepted domain relationships are recorded in session 20261015T163800Z-5: D003. Detailed policies and implementation acceptance remain open. diff --git a/.planning/follow-ups/20261015T155426Z-define-identity-permissions-and-sharing/follow-up.md b/.planning/follow-ups/20261015T155426Z-define-identity-permissions-and-sharing/follow-up.md index 86a841e..b61b24d 100644 --- a/.planning/follow-ups/20261015T155426Z-define-identity-permissions-and-sharing/follow-up.md +++ b/.planning/follow-ups/20261015T155426Z-define-identity-permissions-and-sharing/follow-up.md @@ -6,7 +6,7 @@ "kind": "question", "status": "in-progress", "created_at": "2026-10-15T15:54:26Z", - "updated_at": "2026-10-15T16:38:00Z", + "updated_at": "2026-10-16T10:18:23Z", "observed_at": null, "reported_by": "assistant; deferral explicitly accepted by user in Q47", "owner": null, @@ -34,7 +34,9 @@ ".planning/decisions/20261015T085738Z-3/D019-contact-with-multiple-patient-profiles.md", ".planning/decisions/20261015T085738Z-3/D029-first-contact-existing-record-access.md", ".planning/decisions/20261015T085738Z-3/D034-practice-configuration-ownership.md", - ".planning/decisions/20261015T085738Z-3/D039-focused-design-followups.md" + ".planning/decisions/20261015T085738Z-3/D039-focused-design-followups.md", + ".planning/decisions/20261015T163800Z-5/D001-staff-identity-and-membership.md", + ".planning/decisions/20261015T163800Z-5/D002-shared-contact-point.md" ], "dependencies": [ ".planning/decisions/20261015T085738Z-3/scope-review.md" @@ -113,3 +115,5 @@ Pending. The deferral is accepted; the detailed choices and implementation are n - 2026-10-15T15:54:26Z — Created from the user-approved Q47 deferral; no external outreach, integration changes or application implementation occurred. - 2026-10-15T16:38:00Z — Domain-modeling portion started in issue #5 and session 20261015T163800Z-5. Status is in-progress; this does not claim all detailed policies or permissions are being resolved. + +- 2026-10-16T10:18:23Z — Accepted domain relationships are recorded in session 20261015T163800Z-5: D001, D002. Detailed policies and implementation acceptance remain open. diff --git a/GLOSSARY.md b/GLOSSARY.md index 19cd7cd..85ab7a6 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -8,8 +8,12 @@ The language of coordinating a practice, its patients, and its appointments. The The organization whose doctors, staff, schedules, and patient information are managed together in Medora. A solo practice and a clinic organization are both practices. _Avoid_: Clinic when it could mean either the organization or one of its locations; tenant in product language. +**Staff Account**: +A person's authenticated staff identity in Medora, which may participate in several practices through separate memberships. +_Avoid_: Practice Membership when referring to the staff identity itself. + **Practice Membership**: -A person's participation in a particular practice, with the roles and permissions granted there. +A Staff Account's participation in a particular practice, with one or more roles and the permissions granted there. _Avoid_: Global role when describing authority in one practice. **Practice Owner**: @@ -32,6 +36,10 @@ _Avoid_: WhatsApp user; phone-number holder as a synonym for Patient. The person communicating with the practice about an appointment or patient. A contact may communicate for themselves or for another patient. _Avoid_: Patient when the speaker and recipient of care may differ; phone number as a synonym for the person. +**Contact Point**: +An address through which a Communication Contact can be reached, such as a WhatsApp number; several contacts may share one. The address alone does not establish who is speaking or their authority over a patient. +_Avoid_: Communication Contact for an address; Communication Line for a patient-side address. + **Patient Profile**: A practice's organized administrative information about a patient, including appointment context and attributed patient-reported information. _Avoid_: Full medical record; global patient account. @@ -39,7 +47,7 @@ _Avoid_: Full medical record; global patient account. ## Scheduling **Appointment Request**: -A request to arrange a consultation, expressing the patient's needs and scheduling preferences. +A request to arrange a consultation, expressing the patient's needs and scheduling preferences. It is distinct from any temporary reservation made for it. _Avoid_: Confirmed appointment; Reservation when referring to the request itself. **Reservation**: diff --git a/docs/domain-model.md b/docs/domain-model.md index 7220d72..6787b33 100644 --- a/docs/domain-model.md +++ b/docs/domain-model.md @@ -4,24 +4,28 @@ This is an evolving, stack-neutral model grounded in the [confirmed product foun ## Established semantic boundaries -- A **Practice** owns its operational records and patient profiles. A person's **Practice Membership** scopes authority in that practice. -- The **Patient** receives care. The **Communication Contact** speaks to the practice and may represent another patient. A practice-connected **Communication Line** is an endpoint, not a person. +- A **Practice** owns its operational records and patient profiles. One **Staff Account** may hold separate **Practice Memberships**, each with its own roles and permissions; roles may combine within a membership. +- The **Patient** receives care. The **Communication Contact** speaks to the practice and may represent another patient. Several contacts may share a **Contact Point**, which alone proves neither identity nor authority. A practice-connected **Communication Line** is distinct from that patient-side address. - An **Appointment Request** expresses intent; a **Reservation** claims time provisionally; an **Appointment** represents the scheduled consultation. These meanings do not prescribe separate database tables or entity identifiers. - **Appointment Notification** delivery is distinct from appointment confirmation. A failed message does not silently cancel a confirmed appointment. - **Patient Profile** and **Intake** preserve the origin of information. An AI summary is not a clinician-verified finding. - **Staff Conversation** is private by default; **Patient Conversation** involves the contact. **Handoff** changes who actively handles that patient conversation, not who has authority over every practice record. -## Concept relationships already supported by the foundation +## Accepted concept relationships The diagram shows meaning, not storage, cardinality or a finalized aggregate design. ```mermaid flowchart LR + Account[Staff Account] -->|participates through| Membership[Practice Membership] + Membership -->|belongs to| Practice + Membership -->|has practice-scoped| Roles[Roles and permissions] Practice -->|owns| Profile[Patient Profile] Profile -->|describes| Patient Practice -->|connects| Line[Communication Line] Line -->|carries| Conversation[Patient Conversation] Contact[Communication Contact] -->|participates in| Conversation + Contact -->|reachable through a possibly shared| Address[Contact Point] Request[Appointment Request] -->|concerns| Patient Hold[Reservation] -->|holds time for| Request Request -->|may result in| Appointment @@ -29,19 +33,29 @@ flowchart LR Appointment -->|with| Doctor ``` -## First unresolved relationships +## Resolved first-round scenarios -| Scenario | What it tests | Current proposal | +| Scenario | What it tests | Accepted outcome | | --- | --- | --- | | Doctor owns one practice and works at another | Staff identity versus practice membership; multiple roles | One staff identity with independent practice memberships and role combinations | -| Two adults share one WhatsApp number | Contact person versus sender address | A separate contact-address concept; do not infer speaker identity from a number | +| Two adults share one WhatsApp number | Contact person versus sender address | Separate Communication Contacts may share a Contact Point; the number does not establish the speaker or representative authority | | Reservation expires before staff review | Request lifecycle versus temporary hold lifecycle | Keep the underlying request open, explicitly without a reserved slot | -These are proposals, not accepted domain rules. Their exact questions and recommendations are in the active session. The proposed contact-address term **Contact Point** is deliberately not yet added to the glossary. +The user's joint reply **"ok, next"** accepts these three recommendations. The [session index](../.planning/decisions/20261015T163800Z-5/session.md) links the original questions, exact reply and separate interpretation. Staff Account and Contact Point are now resolved glossary terms. + +When a reservation expires, release its slot, notify the contact and leave the request open needing another slot. Expiry does not close the underlying request or create a confirmed appointment. Explicit withdrawal or closure remains possible; an independent inactivity policy is still undecided. + +## Next scenarios — proposals awaiting answers + +| Scenario | Question | Recommendation, not yet accepted | +| --- | --- | --- | +| Patient compares two available times | How many active holds can one request have? | Hold one selected slot; other times are suggestions. The confirmed original appointment during rescheduling remains separate. | +| Confirmed consultation moves from Monday to Thursday | Same appointment or unrelated cancellation/new booking? | Preserve appointment continuity and record the approved change. A genuinely cancelled appointment remains cancelled. | +| Receptionist coordinates only one doctor in a multi-doctor practice | Can coverage be narrower than the whole practice? | Explicit doctor coverage within the membership, with an all-doctors option; coverage alone does not grant clinical access. | ## Questions intentionally still open -Account and membership cardinalities, shared addresses, request closure, and detailed cross-practice identity relationships require explicit modeling decisions. The accepted practice-scoped record boundary remains in force. Later lifecycle scenarios must address hold/replacement expiry, verification, staff approval, cancellation and rescheduling using the confirmed rules, without choosing storage structures prematurely. +The next scenarios remain unanswered. Exact verification, fine-grained permissions, shared-patient profile access, independent request inactivity/closure policies, duplicate requests and detailed cross-practice identity relationships still need decisions. The accepted practice-scoped record boundary remains in force. Further lifecycle scenarios must respect staff approval, patient agreement, truthful notifications and the confirmed cancellation/rescheduling rules without choosing storage structures prematurely. ## Relation to existing follow-ups