Reviewing an incident, end to end

The records, and what each one answers#

The chain a review runs through#

1. TRIGGER — a report: a customer complains, a probe fires, a number on a screen is wrong, or a call went silent.
2. USER / EXTERNAL EVENT — establish what the person outside actually experienced, in their words, before touching any record.
3. AUTH / WORKSPACE RESOLUTION — establish which workspace and which audience. A report about one account is a question about both: an Owner path and a customer path differ, and a capability the customer facade does not recognise becomes a 403 rather than an error anyone can read.
4. INGEST / REQUEST — find the request or the event. On the phone that means call_events, which stores every normalised provider event once under a partial unique index.
5. CANONICAL RECORD — open the row itself: the calls row, the thread, the follow-up. Note outcome and disposition separately; they are kept apart so a late webhook cannot overwrite what a person decided.
6. CLASSIFICATION / RESEARCH / REASONING — read what Connect concluded, not what you assume it concluded. A summary written from too little input is its own failure mode.
7. KNOWLEDGE + MEMORY + RULES — check whether the answer came from a grounded fact, from memory, or from neither. A wrong answer with a right source is a different fix from a wrong answer with no source.
8. AUTONOMY / APPROVAL — check whether the action was permitted, held or refused. A refusal is a decision and is recorded as one.
9. ACTION / PROVIDER — compare your record with the provider's. A completed call on their side with no row on yours is a bug every time.
10. RESULT — attribute the ending. hangup_by names one of caller, model, owner, engine, carrier or agent; before that existed, everything that was not the caller read 'agent'.
11. RELATIONSHIP / TIMELINE / MEMORY — check what the incident wrote into the relationship. A wrong fact remembered outlives the incident and needs forgetting explicitly.
12. AUDIT / USAGE / NEEDS YOU — take the correlation id. It is what turns a single bad outcome into the sequence that produced it.
13. NEXT — write the finding down, and add the assertion that would have caught it.

The questions worth answering#

1. What did Connect complete? Name it precisely. 'The reply was drafted and held' and 'the reply was sent' are different incidents with different obligations to the customer.
2. What did Connect not complete? This is the half that gets skipped, and it is the half the customer is waiting on.
3. Was it silent? Silence is the worst class here. Five inbound calls on one day in September 2026 sat in silence and were recorded as 'the caller hung up before speaking'; the record was confidently wrong, which is harder to notice than an error.
4. Is it new? Reading the diff answers 'is this mine' in seconds and is the first move, not the last. Building a second environment to compare against is the last one.
5. Which audience? Check the other one before concluding. An asymmetry between the Owner's path and a customer's is the single most common shape of 'it works for me'.

What to write down#

The correlation id

One id ties the decision to everything it caused. Without it a reviewer months later is reading coincidences.

What the outside world saw

The caller's experience, the recipient's inbox, the screen the person was on. Not the exception.

The cause, not the symptom

A patch that swallows an error or defaults a bad value ends the incident and keeps the defect.

The proof

The command, the test, the row, the provider log line. A fix asserted without evidence is a fix nobody can re-check.

The assertion that would have caught it

Written as a test, and shown to fail once with the fix disabled. An assertion that has never been red has proved nothing.

Closing it#

An incident is closed when the cause is named, the fix is proved, the record says what completed and what did not, and there is an assertion that fails without the fix. A probe that fires on a correct release is worse than no probe, so if the incident produced an alert, check that the alert would not now fire on a healthy day.

Queue entries settle by themselves. Line health and the operational problems raised into Needs You drain as their cause clears, so a queue that is still full an hour after the fix is telling you the cause has not cleared — not that the queue is stale.

Questions#

Related#

• Troubleshooting
• There is no audit entry for something
• A probe that fires on a correct release is worse than no probe
• When a call is answered in silence
• Communicating during an interruption
• Proving a change did not break anything
• Security and isolation