Supportability for an agent working on software people use
Where people get help, which versions are supported, and what an error message, a log line and a diagnostic bundle must and must never contain.
- Authors
- Leon Mallett, Founder of Captivated Ltd with Claude Code
- Status
- Last confirmed working 19 October 2026 on Claude Code 2026-10
- Written
- 19 October 2026
- Licence
- Handover-1.0
Customise before downloading
This document has 2 fill-in fields. Complete them and you get a copy ready to commit, rather than one to edit afterwards. Nothing is sent anywhere — the file is assembled in your browser.
The one route you want users to take. Every error message and help page points here and nowhere else.
How far back fixes and help extend. Decides whether a report against an old version is a bug or an upgrade.
A customised copy is a derivative of the published document: its contents differ, so it carries a line naming the original. Any field you leave blank keeps its{{placeholder}}, so it stays obvious rather than silently empty.
How this software stays supportable once it is in people’s hands. Running it — incidents, releases, rollback, and what changes when software runs on machines you do not control — is in the operational runbook. This file is the other side: what a person who needs help sees, and what reaches us when they ask.
Where help comes from
Support is reached through {{support_channel}}. Every error message, help page, empty state and “something went wrong” screen points there and nowhere else — not a personal address, a social account, or an issue tracker the person may not be able to see.
Supported versions: {{support_window}}. A report against anything older gets an upgrade path rather than a fix, so the software should say which version it is in the same place it says how to get help.
Error messages
An error somebody sees is the first line of a support conversation. Write it to be acted on:
- Say what happened and what they can do, in their terms rather than the code’s — “Couldn’t save — check your connection and try again”, not an exception class.
- Include something support can look up: a short error code or reference, kept stable across releases.
- Never show a stack trace, a path from the build machine, a token, or anybody else’s data.
Logs and diagnostic bundles
Anything a person might send us is published to us, and sometimes beyond us. Design it on that assumption.
- Never log credentials, tokens, session identifiers, or the content of what people write. Redact where the line is written, not afterwards.
- Always include the version, the platform and a timestamp in anything a person can export. Most reports cannot be acted on without the first.
- Let the person see what they are sending before it leaves their machine, and send nothing automatically that they have not agreed to.
Turning a report into a reproduction
Ask for the version, the platform and the steps, in that order. Check the supported versions before investigating. Reproduce on the version they are running, not the latest one — a fix confirmed only against the latest version has not been confirmed for the person who reported it.
What needs a person
- Changing where help comes from or which versions are supported, or promising a response time anywhere public.
- Collecting any new kind of diagnostic data, or sending any of it automatically.
- Replying to somebody directly.