File structure

CODEBLOCK0

The lifecycle

CODEBLOCK1

The skill owns every stage except the ones that need a phone call.
For those, it does everything up to handing you the number and the script.

Booking methods

Online booking (handled automatically):
Agent uses the browser tool to find and complete the booking.
No action required from the user beyond the initial request.

Phone-only providers (handled up to the call):
Agent finds the number, identifies the best time to call,
drafts a script with all the information needed, and sends it ready to use.
The call is the user's — everything else is handled.

Manual logging:
User booked it themselves. Agent logs it and sets up the reminder chain.
/appt log [description] [date/time]

Setup flow

Step 1 — Reminder preferences

Ask once. Store in config.md. All future appointments use this.

Default chain:

• - 24 hours before: full reminder with address, what to bring, journey time
• 2 hours before: short nudge with location
• 15 minutes before: final ping (off by default — ask if they want it)

Also ask: follow-up prompt after appointment? Default on.
"[APPOINTMENT] is done — anything to note?"

Step 2 — Location

Ask for home location / postcode if not already in USER.md.
Used for: journey time estimates, finding local providers.

Step 3 — Calendar

If Google Calendar is connected: ask if they want appointments added automatically.
Default: yes.

Step 4 — Write config.md

CODEBLOCK2

Booking flow — online provider

When user says "book me a dentist appointment" or "I need a GP appointment next week":

Step 1 — Identify the provider

Check providers.md for a preferred or previously used provider.
If found: confirm with user — "Use [PROVIDER] again, or try somewhere new?"
If not found: ask for their preferred provider, or offer to find one nearby.

Finding a provider (if needed):

web_search: "[appointment type] near [location]"

Step 2 — Find the booking page

CODEBLOCK4
Look for: online booking link, booking system (Doctolib, Zocdoc, Calendly, proprietary).
If booking system found: proceed to Step 3.
If no online booking: proceed to phone-only flow.

Step 3 — Check availability

Use browser tool to navigate the booking system.
Find available slots. Check against user's calendar if connected.

Ask the user: "Any preference on day or time? Morning or afternoon?"
Default: next available slot that doesn't conflict with calendar.

Present top 3 options:
CODEBLOCK5

Step 4 — Complete the booking

Navigate and complete the booking in the browser.
Fill in required details (name, DOB, reason for visit — ask user if needed).
Get confirmation number or confirmation email.

Confirm to user:
CODEBLOCK6

Log to appointments.md and update providers.md with booking details.

Step 5 — Register reminder cron jobs

For each reminder in the chain, register an isolated cron job:

CODEBLOCK7

Repeat for 2h reminder. Store cron job IDs in appointments.md.

Booking flow — phone-only provider

When the provider has no online booking:

Step 1 — Find the number

CODEBLOCK8
Extract: main booking number, best time to call, any notes ("call after 9am", "press 2 for appointments").

Step 2 — Draft the call script

Generate a complete script ready to use:

CODEBLOCK9

Send the script to the user's channel. Everything they need is in one message.

Step 3 — Set a call reminder

If the user hasn't logged the appointment within 2 days:
"Did you manage to call [PROVIDER]? If you've booked, just log it and I'll set up reminders."

Appointment types and prep notes

The skill knows what different appointments typically require.
The 24h reminder includes type-specific prep notes.

Medical / GP:

• - Bring: [any referral letters, current medication list, insurance card if applicable]
• Note: arrive 5-10 minutes early if first visit
• Journey: [estimated travel time from home]

Dentist:

• - Avoid eating 1 hour before if possible
• Bring: [dental insurance card if applicable]
• Journey: [estimated travel time]

Optician:

• - Bring: current glasses/contact lenses
• Note: driving after eye test may not be possible if drops are used

Haircut / beauty:

• - Bring: reference photos if you have a specific style in mind
• No special prep

Specialist / hospital:

• - Bring: referral letter, any previous test results, medication list, insurance card
• Note: allow extra time for registration
• Journey: [hospital can be large — check which department and entrance]

Custom:
For appointment types not in the library, ask the user once: "Anything specific to bring or prepare?"
Store in providers.md for future bookings at the same provider.

appointments.md structure

CODEBLOCK10

providers.md structure

CODEBLOCK11

providers.md grows over time. Every new provider is stored.
Future bookings at the same provider skip the research step entirely.

Reminder formats

24h reminder

CODEBLOCK12

2h reminder

CODEBLOCK13

15min reminder (if enabled)

CODEBLOCK14

Follow-up prompt (1h after end time)

CODEBLOCK15

Reschedule flow

INLINECODE1

1. 1. Cancel existing reminder cron jobs
2. Navigate back to booking system (for online bookings)
3. Find new slot — present options
4. Complete reschedule
5. Update appointments.md
6. Register new reminder cron jobs
7. Update Google Calendar event

Cancellation flow

INLINECODE2

1. 1. Cancel reminder cron jobs (delete them)
2. Ask: "Do you want me to cancel with the provider too, or just remove your reminders?"
3. If cancelling with provider: navigate to online cancellation or provide phone number + cancellation script
4. Update appointments.md status to "cancelled"
5. Update Google Calendar event

Management commands

• - /book [description] — start booking flow
• INLINECODE4 — all upcoming appointments with dates
• INLINECODE5 — anything today
• INLINECODE6 — manually log a booked appointment
• INLINECODE7 — mark complete with follow-up notes
• INLINECODE8 — cancel appointment and reminders
• INLINECODE9 — reschedule flow
• INLINECODE10 — past appointments log
• INLINECODE11 — past visits to one provider
• INLINECODE12 — list of known providers

What makes it good

The phone-script for phone-only providers is the most underrated feature.
It removes the only thing the skill can't do automatically — the call itself —
by making the call as easy as possible. Number, navigation instructions, exact words to say.
The user spends 3 minutes on hold instead of 20 minutes procrastinating.

The providers.md memory compounds.
The second time you book at the same dentist, there's no research, no finding the number,
no remembering which booking system they use.
The skill knows. It just asks "same place?" and proceeds.

The 24h reminder with journey time is the one people notice.
"Leave by 9:45 to arrive on time" is more useful than "appointment at 10:30."