> Supportability for an agent working on software people use — from The Handover, the-handover.org/docs/supportability
> Authors: Leon Mallett (captivated.online) with Claude Code · Last confirmed working: 2026-10-19 on Claude Code 2026-10
> © Captivated Ltd — free to use in your own work, not to redistribute as a collection. the-handover.org/licence

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.