post-connection-implement-relinkinglisted
Install: claude install-skill merge-api/merge-unified-skills
# Implementing Relinking and Detailed Error Messaging
## Purpose
Credentials expire, permissions get revoked, and admins change — relinking lets end users re-authenticate without contacting support. Detailed error messaging (rather than "something went wrong") tells users exactly what failed and who needs to fix it.
## Prerequisites
- `post-connection-build-settings-page` complete
- `/api/merge/relink-integration` endpoint working
---
## Before Proceeding
Tell the user: "Implementing relinking requires storing error state on the `linked_accounts` table (an `error_category` column and optionally `error_detail`). I'll generate a migration for this. Ready to proceed?"
Wait for confirmation before continuing.
## Detecting that a relink is needed
There is no `relink_needed` webhook. The dashboard's event list shows `LinkedAccount.status_changed`, but it has no emitter and never fires — do not build detection on it. Three signals that do work:
1. **`Issue.new` webhook** — fires when Merge opens an issue on the account (expired credentials, missing permissions, provider outage). Pair with `Issue.resolved` to clear your banner.
2. **Poll `GET /issues?linked_account_id={id}&status=ONGOING`** — the reliable backstop, and the only way to get the error detail you need for the message copy in Part 2.
3. **`status` on `GET /account-details`** — `RELINK_NEEDED` is the account-level signal, but it lags the underlying issue.
Use 1 for latency and 2 for correctness. An account can