Playbook, developer tools company
The handover is only worth making if the version and the error text travel with it
On a documentation site the handover is not the interesting part, the evidence is. A report that arrives saying the upload endpoint is broken costs a day in round trips before anybody can even look. A report that arrives with the exact error string, the library version, the runtime and whether it reproduces in the sandbox can be triaged the moment somebody opens it. The assistant cannot debug anything, but it is extremely good at asking those four questions.
Why this is not the general answer
The handling pattern for asking for a person holds across every trade. What follows is the part that does not.
- The value here is in what is gathered before the handover rather than in the routing itself, which is the opposite of every other cell in this family.
- A developer will answer four precise questions without complaint, which is not true of any other kind of visitor, so it is reasonable to ask.
- Saying plainly that it cannot reproduce or debug earns cooperation from this audience, where hedging reads as incompetence.
- The message is free text, so it has to be prompted into carrying structured evidence rather than a description of the symptom.
How it arrives
- can i talk to an engineer about this
- this looks like a bug on your side, who do i report it to
- is there a support channel on the paid plans
- where do i file an issue for the client library
- i need somebody who can look at our request logs
- can you escalate this, it is blocking our release tomorrow
What has to be indexed for this to work
| The bug report template you already ask for | Most teams have one, and it names the fields triage cannot work without. Whatever those fields are, they belong in the prompt the assistant uses when it collects details, because they are the difference between a report that gets triaged and one that gets a clarifying question. |
|---|---|
| Which route handles what | Public issue tracker, support address, or a channel tied to a plan. Developers ask this directly and answering it wrongly sends a blocking problem into a queue nobody reads for a week. |
| How to gather diagnostics | Debug logging flags, request identifiers, a version command, whatever produces the output your engineers ask for first. Pointing at it while the reader is still in chat is far more effective than asking for it by email afterwards. |
| Whether a sandbox reproduction is possible | It is the fastest triage signal there is, because it separates a defect from an environment problem before anybody looks at either. If your sandbox can reproduce most failure classes, asking becomes a routine part of the handover. |
The reply
That does read like a defect rather than a configuration problem, and I cannot reproduce it or see your logs, so it needs somebody who can. Before I take your details, could you paste the exact error text, the library version you are running, the runtime and operating system, and whether it also happens against the sandbox? Send that with your name and email and I will pass the whole thing across, which saves the first round of questions on the other end.
It agrees with the reader's own diagnosis where the evidence supports it, which is what makes a developer willing to answer four questions instead of demanding a person immediately. Asking for the version and the exact string before the name and email is deliberate: the evidence is the scarce thing, the contact details are not. Explaining why it is asking, to skip a round trip, converts what would feel like a gate into something the reader wants to do.
Where it stops
The trigger. The reader believes the behaviour is a defect, asks for an engineer, or says the problem is blocking a release.
I cannot reproduce this or see anything on your side, so this needs a person. Paste the exact error text, the version, the runtime and whether it reproduces in the sandbox, then leave your name and email and I will send all of it over together.
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 an issue has been filed, a ticket raised or a report logged anywhere.
- That the engineering team is already aware of this or investigating it.
- That a fix is coming, or that it will be in a particular release.
- Anything that takes the handover without first asking for the version and the exact error text.
Questions
- Does asking four questions annoy people who just want a human?
- Less than you would expect, provided the reason is stated. Developers understand triage. What annoys them is being asked for the same four things by email a day later, which is what happens when the handover collects only a name and a sentence.
- Can it open an issue in our tracker for them?
- No. It writes into nothing, so it can point at the tracker and it can collect details into an enquiry, but the issue itself is created by a person. Saying otherwise would leave somebody waiting on a ticket that does not exist.
- What if it is not actually a bug?
- Then the evidence it collected sorts that out faster than any conversation would. A version and an exact error string usually identify a documented behaviour change within a minute of somebody reading them, which is a better outcome than the assistant deciding either way in chat.
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 asking for a person in generalThe design question at the centre of a support assistant. Offer early, offer once, collect what a reply needs, promise a time you can keep.
- 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.
- Two deployments, and two completely different answers to delete our dataFor a self hosted install there is nothing on your side to delete. For the hosted one, request logs and telemetry each run their own clock.
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.