Playbook, developer tools company
The only question on the site during an incident is the one it cannot answer
During an incident every other question stops and one arrives repeatedly for an hour. It is also the single question this kind of assistant is least equipped to handle, because what it knows about your availability is whatever your status page said the last time the material was read. Repeating that during an outage is not a small inaccuracy. It is a screenshot.
Why this is not the general answer
The handling pattern for service outages holds across every trade. What follows is the part that does not.
- Its knowledge of your systems is a snapshot, and an incident is precisely the moment when a snapshot is guaranteed to be wrong.
- Volume collapses onto one question, so whatever the wording is, it is about to be read by everybody at once.
- The reader is usually angry and mid firefight, so a reassuring answer that turns out false is remembered far longer than a refusal.
- There is a real answer available that is not the status itself: the documented retry and backoff behaviour, which is what they should be doing while they wait.
How it arrives
- is the api down right now
- are you having issues, all our calls are timing out
- is there an incident affecting webhook delivery
- when is this going to be fixed
- does the outage affect the european region too
- we are seeing 503s, is that you or us
What has to be indexed for this to work
| The status page address and how to subscribe to it | The one thing the assistant should produce in this situation, every time, without characterising what is on it. Subscription matters more than the link, because it moves the reader from refreshing a page to being told. |
|---|---|
| Documented retry, backoff and idempotency behaviour | The genuinely useful answer during a degradation: how the client retries, what is safe to send twice, and how long to back off. It is documented, it is stable, and it is what a competent reader needs while they wait for the incident to clear. |
| Your incident communication policy | How incidents are declared, where updates are posted and how often, and where the write up appears afterwards. Setting expectations is possible even when reporting the state is not. |
| Past incident write ups | Useful for a different question that arrives in the same hour, which is whether this has happened before and what was done about it. They are also the only availability material that is safe to quote, because they are historical by definition. |
The reply
I have no live view of the platform, so I cannot tell you whether anything is degraded right now, and I would rather say that than repeat something out of date. Current status and any open incident are on the status page, and subscribing there will push updates to you rather than making you refresh it. While you wait, the documented client behaviour is exponential backoff with jitter, and the write operations listed in the idempotency reference are safe to retry without duplicating anything.
The first sentence refuses and explains why in the same breath, which is what stops it reading as evasion to somebody already frustrated. It then does the one useful thing available, which is routing to a live source and to subscription rather than to a page they will refresh. Ending on retry behaviour gives a reader in the middle of an incident something correct to act on, which is the closest this cell gets to actually helping.
Where it stops
The trigger. The reader needs an incident acknowledged, wants an update commitment, or is reporting an impact that is not on the status page.
If you are seeing something that is not reflected on the status page, that needs to reach the team directly rather than through me. Leave your name, your email, the region and the time the failures started, and I will pass it on so they can check it against what they are seeing.
It stops answering before it guesses, says who will pick it up, and asks for the one thing that makes a reply possible. Nothing about it reads as a dead end.
Never say this here
Out of bounds
- That the service is up, healthy, unaffected or operating normally.
- That an incident is ongoing, resolved or under investigation.
- Any estimate of when something will be fixed.
- That the failure is on the reader's side, while an incident is even possible.
Questions
- Can we connect it to our status page so it knows?
- It answers from indexed material, so what it has is the state as of the last read rather than a live feed. Unless you have separately connected a source that carries live status, the correct behaviour is to route to the status page rather than to report from it.
- Should we turn the widget off during an incident?
- There is a case for it, and there is a better case for wording it properly once so it stays useful. During an incident it can still answer the retry and backoff questions, which is exactly what people need, provided it never asserts a state.
- What is the most common mistake here?
- Indexing the status page itself and leaving it there. The page then contributes a cheerful all systems operational line to the corpus, which the assistant will happily surface at the worst possible moment.
Keep reading
- Everything for a developer tools companyOn a docs site an assistant competes with search, not a phone line. Version skew, deprecations and error strings decide whether it earns its place.
- Handling service outages in generalThe assistant knows nothing about an incident unless your material says so. A status page it can read is the fix, and reassurance is the trap.
- The handover is only worth making if the version and the error text travel with itA developer handover succeeds or fails on what the form carries. The four details to gather in chat before taking a name and an email.
- Nobody is asking what it costs, they are asking what counts as oneRequests, builds, minutes or seats. What a metered price has to state before a developer can model a month and defend the number internally.
- An engineer has been asked to explain a spike to somebody in financeReconciling a usage counter against a line item, spikes with a timestamp behind them, and the purchase order details a finance team blocks on.
Try it on your own material
Upload a document or point it at your site, paste one line of HTML, then ask it something only your business could answer.