Scheduling against the real world

The problem

Booking a time looks trivial until the real world turns up: no-shows, insurance plans that change what a slot even means, professionals with their own skills and calendars, buffers between appointments, and a calendar that still has to turn a profit. And there's the part nobody expects: you can't trust a model with date arithmetic. Ask it which day next Tuesday falls on near a month boundary and it will get it wrong, confidently.

Constraints

• 01The server owns the calendar. Weekday and date are resolved in code; the agent states the intent and the server turns it into a real slot.
• 02Ask the constraints before booking. Insurance plan, professional, duration. A slot booked on a wrong assumption is a no-show waiting to happen.
• 03Respect the buffer and the duration per offer. A 15-minute buffer nobody sees on screen still has to be real in the engine.
• 04Keep it profitable. Slots aren't all equal: the calendar has to be able to reserve, cap and prioritise by value, not just by "is it free".

Architecture

The "wrong time" bug was a chain of four, and killing it meant killing the idea that the agent should reason about dates at all. It doesn't pick option numbers, doesn't add days, doesn't name weekdays. It says the customer wants Tuesday afternoon, and the server resolves that against the real calendar, buffers included.

The hard part

The "it booked the wrong time" reports were maddening, because they were four different bugs with one symptom. The agent named a weekday that didn't match the date. It offered a slot ignoring the buffer. A reschedule quietly dropped the professional the appointment was tied to. And it leaned on a brittle "pick option 2" shorthand that broke as soon as the list changed.

What untangled them was the trace: each report pointed at a different turn doing a different wrong thing. The fix running through all four was taking date reasoning out of the model entirely. Every attempt to be clever about "next Tuesday" inside the prompt was a bug generator. With the server resolving dates and the agent only stating intent, three of the four stopped being possible.

Trade-offs

• Moving date logic to the server makes the agent less magical, because it can't improvise a clever booking. That's the goal: improvising is what produced the wrong times.
• Modelling buffers, resources and profitability is a lot of constraint for something users see as "a calendar". The complexity is real because the business is; hiding it in the engine is the best I can do.
• Profitability rules add power and a new way to misconfigure. Worth it for a calendar that has to earn, but it's asking for a screen that explains the floor, not just one that lets you move it.

What I'd do differently

I'd model the calendar's constraints as data from the start instead of discovering them as bugs. No-shows, insurance, buffers and profitability each arrived on their own, as a fix to something that broke. If "what makes a slot valid and worth booking" had been a configurable rule set from day one, all of it would have landed as configuration instead of four separate incidents.