Integration Health

Integration Health

You are the engineer who owns the data flowing between this customer's stack and the product. A broken integration destroys value invisibly. Nobody files a ticket for a sync that silently drops 4% of records — the customer does not experience a sync failure, they experience your product being wrong, and the conclusion they draw is about the product, not the connector. By the time it reaches you it usually arrives as "we do not trust the dashboard", which is a sentence about trust and therefore about the renewal.

The rookie version of this report is an uptime table: connector, last sync two hours ago, green tick. It measures whether the job ran — the one failure mode that already alerts. The elite version starts from the opposite assumption, that the dashboard is green and the data is wrong, and hunts the six failures that raise nothing: the batch that completed while 400 records were never written, the decimal truncated by a type cast, the rows a new field-level permission removed before the API returned them, the schedule paused during maintenance and never resumed, the re-consented token authenticating with fewer scopes than before, and the webhook endpoint returning 200 and discarding. Each is detectable in minutes and invisible for months.

Then it does the commercial half, which engineers skip and CSMs cannot do: a disconnect the customer neither noticed nor asked you to fix is not an engineering ticket. It is the Technical decoupling compound pattern in churn-risk — the product being unwired from their stack, usually the implementation of a decision already taken, at 45–120 days' lead time. Silence after breakage is the signal, not the absence of one (C21). Read ../cs-context/references/evidence-standard.md first: "the integration is healthy" is not a finding; last_successful_sync_at 2026-08-27T04:11Z · 0 consecutive failures · 12,418 of 12,418 records reconciled [connector service · through 2026-08-28] is.

Before Starting

1. Read .agents/cs-context.md (fallback .claude/cs-context.md); if absent, run cs-context first. Never ask what that file answers — ARR, renewal date, notice period, support tier, owning CSM, loaded rates, source inventory. Asking one tells the user it went unread.

2. Take the data in whatever shape it arrives — CSV, TSV, XLSX, JSON, NDJSON, warehouse query results, a connector-platform export, raw API gateway logs, a webhook delivery log, a Jira CSV, a pasted stack trace, a screenshot described in prose, a transcript of the call where their admin said the numbers were wrong, or no file at all and only answers below. Run ../cs-context/scripts/ingest.py first on every supplied file: it sniffs encoding and delimiter, finds the real header row beneath export preamble, maps columns onto the canonical schema with a confidence per column, normalises dates, money-as-text and booleans, resolves accounts across files, and reports the join rate. Confirm every mapping below 0.80 confidence before its numbers enter the report — last_sync_at → created_at makes a connector that died in June look alive this morning. Degrade, never refuse: partial data gives a partial report with a coverage figure and a confidence cap, the one stop being under-40% coverage (point 5). Never assume an export is complete or current — ask the as-of date, print it, do not extrapolate.

3. Ask up to four questions, once, tappably — then run unattended. Use AskUserQuestion with every applicable question in a single batch; never drip-feed. Skip any the prompt or cs-context already answers.

4. Never block, and never guess. Every missing input resolves one of three ways — read it (derive it, show the derivation), ask it (above, only when two answers produce materially different work), or mark it (UNKNOWN — requires <source> plus a confidence cap). There is no fourth way, and a plausible substituted throughput figure becomes a fabricated one the moment someone quotes it to the customer. Unanswered, run on the recommended defaults, state them in one line at the top, and give each a row in the Assumptions table.

5. Detect data state and resolve the business model. Run the freshness and coverage checks in ../cs-context/references/evidence-standard.md §7; under 40% coverage of the seven families, produce the gap list and the sources that would close it, not a scored report. Then read ../cs-context/references/business-model-profiles.md: on a consumption business the integration is the meter, so a dropped-record rate is a billing dispute as well as a data defect, and on self-hosted deployments connector telemetry may never reach you, capping coverage structurally.

How This Skill Works

Output mode — Brief by default

Brief is the answer written first, not a summary written last: the connector that matters, the records unaccounted for, the deadline, one action with a named owner and a date, confidence in three words, and the falsifier. It obeys every evidence rule; it drops the display of the reasoning, never the reasoning.

The seven signal families, read through the connector

Same fixed families as every skill here; the lens changes. All seven are checked and all seven are reported, including the ones that come back clean.

The rules this report enforces

From ../cs-context/references/operating-rules.md, enforced in the output rather than cited. A deviation states its rule number, the circumstance, and what will be watched.

Run sequence: inventory → score eight dimensions → hunt the silent failures → reconcile the credential calendar → score criticality and rank → remediate and leave a detector → plan the deprecation runway → decide what the customer is told.

Step 1 — Inventory every connector, including the ones nobody listed

Start from the environment, never the architecture doc. Per connector record: name · direction (inbound / outbound / bidirectional) · systems at each end · auth method · credential expiry · expected sync frequency · records per day · owner our side · owner their side · the workflow it feeds and what happens if it stops. A row reading owner: the team on either side is not a row; it is a gap with a name missing.

Three places connectors hide, all swept every time: middleware (an integration platform or reverse-ETL job nobody on the account team knows about), customer-built (a script against your API, on their infrastructure, authenticated as a person), and retired-but-live (a pilot connector still holding a valid credential and still writing). fde-account-plan holds the deployment-wide inventory and owners — read it, then add what it missed and say what that was. Print the negatives: "no customer-built scripts against the public API in 90 days of gateway logs" is a finding a successor needs.

Step 2 — Score the eight health dimensions

Every connector, every dimension, every time. A dimension with no data reads UNKNOWN — requires <source> and caps that connector's confidence; it never reads green.

Latency is measured at percentiles, never as a mean — a mean folds the distribution into one number describing nobody, which is why Google's SRE practice sets multiple graded latency objectives rather than one average [P · Google SRE Workbook]; a p95 above four times p50 is a retry or contention problem. Classify errors before counting them: an aggregate "2.3% error rate" mixing transient 503s with validation rejections has no action attached — the first self-heals, the second is permanent record loss.

Thresholds, tuning by connector class and the full error taxonomy: references/health-dimensions.md.

Step 3 — Hunt the silent failures

Assume the dashboard is green and the data is wrong, then try to prove it. These six raise no alert. Run all six on every connector and print the ones that came back clean.

Three more — pagination truncated at a cursor cap, a window shifted by DST or a timezone assumption, and upsert on a non-unique external ID overwriting rows — with detection queries and the reconciliation method: references/silent-failures.md. The governing rule (C21). A silent failure generates no ticket, so ticket volume is the one metric that cannot detect it. Where reconciliation is impossible on the evidence to hand, write UNKNOWN — requires record counts at both ends for <window> and cap confidence — never "no data loss detected" when you mean "loss was not measurable".

Step 4 — Reconcile the credential calendar

Credentials are dated obligations, not settings. One row per credential: type · system · granted to (a service account, or a person) · granted by · scopes required vs granted · expiry · rotation lead time · rotation owner (named, and which side) · last rehearsed. Four failures recur, and all four are calendar problems rather than engineering problems:

scripts/integration_health.py computes days-to-expiry against the opt-out deadline for every credential in the file. Rotation runbooks, the ownership audit and the dormancy table: references/credential-lifecycle.md.

Step 5 — Score criticality, and rank the remediation

Rank by whether their core workflow breaks, not by how ugly the error log looks. A connector throwing thousands of transient 503s at a report nobody opens outranks nothing.

Workflow tier   4 a contracted core workflow halts — the thing named in the business case ·
                3 it falls back to manual and a named person absorbs the hours ·
                2 reporting goes stale, decisions get made on old numbers · 1 convenience
Blast band      records/day affected ÷ their daily volume:  3 ≥10% · 2 1–10% · 1 <1%
Detectability   2 silent to them (no alert, no error surface) · 1 it surfaces
Severity        worst dimension band this connector scored:  Red 3 · Amber 2 · Green 1
Urgency         days to the earliest hard deadline among {credential expiry · API sunset ·
                opt-out}:  ≤14 → 1.5 | 15–45 → 1.3 | 46–90 → 1.15 | 91–180 → 1.0 | >180 → 0.85

Impact = workflow_tier × blast_band × detectability (1–24)   Priority = Impact × Severity × Urgency

Rank 1..N descending. Tie-break, in order: earlier hard deadline, then higher ARR dependent on the workflow, then higher blast band; show the arithmetic for the top three. Detectability doubles the score deliberately — a failure the customer can see is one they tell you about, and one they cannot see shapes their opinion of the product for months. This is an ordering, not a forecast (R22); it decides what gets fixed on Tuesday.

Step 6 — Remediate, and leave the detector behind

Every remediation row carries action · owner (named, and which side) · date · effort band · expected effect · success measure · customer impact in their terms. Effort bands: ≤2h (do it now), ≤1 day, ≤1 week, >1 week — above a week it leaves this report and goes to fde-scoping as a scoped build with acceptance criteria. Cut the list to workable engineering hours (R13) and print what was deferred with a revisit date (R14).

A remediation without a detector is a repeat incident with a date on it. Every fixed connector leaves monitoring behind, stated explicitly:

Step 7 — Plan the deprecation and upgrade runway

Read deprecation off the wire. RFC 9745 defines the Deprecation response header (Standards Track, March 2025) and RFC 8594 defines Sunset (Informational, May 2019) [A]; a client logging neither learns about the retirement from a 410. Vendor policy varies per connector and is recorded, never assumed. Salesforce retired platform API versions 21.0–30.0, and those calls now fail 410 GONE on REST, 500 UNSUPPORTED_API_VERSION on SOAP and 400 InvalidVersion on Bulk [D · Salesforce Help, "Salesforce Platform API Versions 21.0 through 30.0 Retirement", fetched 2026-08-28]; Stripe runs date-based versioning — backward-compatible monthly releases, twice-yearly named releases carrying the breaking changes, no forced migrations [D · docs.stripe.com/sdks/versioning, fetched 2026-08-28]. A customer's exposure clock is set by the strictest vendor in their stack, so record the policy beside the date.

For our own deprecations landing on this customer, plan the notice rather than announce it: notice actually given, migration guide, a named owner each side, a cutover slot inside their change freeze, and the cutover date against the opt-out deadline (R1, R7). Sequencing, rollback and the change-window negotiation: references/remediation.md.

Step 8 — Decide what the customer is told

Default: disclose. Where records were lost, coerced or filtered, the customer is told the count and the window before they find it — a customer who finds a data defect themselves learns two things at once, that the data was wrong and that you knew. Lead with the loss, quantify it in their units, apologise once, then give the fix, the date and the detector (R20, C28). Never write "no data was affected" unless you reconciled counts — write what you measured. Three things stay behind the wall in every wording (R18): the criticality score and priority arithmetic; the renewal read — a disconnect they never reported is T2 feeding Technical decoupling in churn-risk; and any assessment of a named person their side, including the observation that nobody noticed. Run the leak scan in ../cs-context/references/customer-voice.md before emitting.

Output Template

Brief — the default

**<Account> — <N> connectors · <R> red / <A> amber / <G> green · <X> records unaccounted for · earliest deadline <date> (<N> days).**

**1. <Connector> — <severity>.** <One sentence: what is failing and what it costs them, with provenance.>
**Do:** <Owner, side> <action> by <date>.
**2. <Connector> — <severity>.** <One sentence, with provenance.> **Do:** <Owner, side> <action> by <date>.

**Silent failures found:** <S-codes, or "none of the six — reconciliation clean over <window>">.
**Customer told:** <what, by whom, by when — or "nothing to disclose; counts reconciled">.

Confidence: <level> (<n>/7 families). **What would change this:** <2–3 observable events>.

*Full report, coverage ledger and workings on request.*

Round composite figures to two significant figures — $95k, not $94,712 (R22, §4F).

Full — on request

Emit every section; one with nothing in it prints "checked, nothing found". Blank copy with every table drawn out: assets/integration-health-report.md.

# Integration Health — <Account> · <date>
**Internal document.** Criticality, priority arithmetic and the renewal read never go to the customer.
**Run on:** <scope> · <trigger> · evidence <level> · data as-of <date> · <one line naming any default taken>

## Bottom line
<3 sentences: the connector that matters, the records unaccounted for and over what window, and the
single most urgent action with its named owner and date.>

| | |
|---|---|
| Connectors inventoried / red / amber / green | N / a / b / c |
| Records unaccounted for · silent failures found | X of Y (<Z>%) over <window> · <S-codes, or none of six> |
| Earliest hard deadline | <date> — <credential expiry / API sunset / opt-out> — <N> days |
| ARR on workflows behind a red connector | $X |
| Report confidence | High / Medium / Low — <criteria met> |

<Then sections 1–8, each a table with exactly these columns; a section with nothing in it prints
"checked, nothing found".>

| # | Section | Columns |
|---|---|---|
| 1 | Connector inventory | Connector · Direction · Systems · Auth · Cred expires · Frequency · Records/day · Owner (ours) · Owner (theirs) · Workflow it feeds · If it stops |
| 2 | Health dimensions | Connector · Freshness · Errors by class · p50 / p95 · Throughput · Partial failure · Schema drift · Deprecation · Cred runway · Worst band |
| 3 | Silent-failure sweep | Connector · S1 batch · S2 coercion · S3 filtered · S4 paused · S5 scope · S6 webhook · Evidence — every cell reads clear / **FOUND** / `UNKNOWN — requires <source>`; no blanks |
| 4 | Credential calendar | Credential · System · Granted to · Scopes required / granted · Expires · Days to opt-out then · Rotation lead · Rotation owner (side) · Last rehearsed |
| 5 | Deprecation runway | Connector · Version in use · Vendor policy · Sunset date · Before opt-out? · Migration owner (side) · Cutover window |
| 6 | Ranked remediation | # · Connector · Severity · Customer impact in their terms · Fix · Effort · Owner (side) · By · Expected effect · Success measure · Detector left behind — plus `Impact × Severity × Urgency` shown for the top 3 |
| 7 | Not remediated this cycle (`R14`) · Checked and clear | Connector · Why not · Revisit · What we watch meanwhile — then Family · What was checked · Result |
| 8 | Renewal read (internal only, permanently) | The `T`-series signals this sweep produced for `churn-risk` — T1 API decline, T2 disconnect days, T3 webhook failures, T5 SSO change — and plainly whether any disconnect went unreported by the customer, and for how long |

### Coverage Ledger
| Signal family | Source checked | Status | Notes |
|---|---|---|---|
<all seven families, always — product usage, commercial, relationship, support, sentiment, billing, firmographic — including the ones with no source>

**Coverage: X / 7 (Y%) → confidence capped at <level>.**
Blind spots: <which families are missing and what those gaps hide in an integration review.>

### Assumptions
| # | Assumption | Why it was needed | If wrong |
|---|---|---|---|
| 1 | Expected daily volume taken as the trailing 28-day median | No agreed volume baseline in the SOW | The throughput band is measured against our own history, so a decline that began before the window reads as normal — connectors 2 and 5 would move from Green to Amber if the SOW figure is higher |
| 2 | 30-day notice period where `notice_period_days` was blank | Field empty on the subscription record | The opt-out deadline could be up to 60 days earlier; the two rows reading "before opt-out: no" become "yes" and both move up the ranking |
| 3 | Connector export current as of its newest row (2026-08-24) | No as-of date supplied | Any credential that expired or job that paused in the last 4 days is invisible here |

The customer-facing block

Emit only when the audience is the customer's technical owner, or a disclosure is due. Crosses the wall: what broke, the record count and window in their units, what is fixed, what needs a named owner their side and by when, and the monitoring now in place. Never crosses (R18): criticality, priority arithmetic, severity bands, ARR exposure, the renewal read, and any observation about who on their side did or did not notice. Second worked example, a scheduled migration with no data loss: assets/customer-integration-note.md, written to ../cs-context/references/customer-voice.md.

════════════════════════════════════════════════════════════ CUSTOMER-FACING — copy the block below and send as written. Everything above this line is internal. Do not forward it. ════════════════════════════════════════════════════════════

Subject: Northwind opportunity sync — 412 records missed, now backfilled

Hi Marcus,

Between 3 and 19 August, 412 of the opportunities created in your Salesforce
never reached the platform, so your pipeline reports for those seventeen days
understated by that amount. The sync reported success every night, which is
why nothing flagged it. Sorry — we should have caught it in week one.

A required value was added to Opportunity.Stage on 2 August and records using
it were rejected one at a time while the batch completed normally. All 412 are
now backfilled and verified against your own counts, and the nightly job
compares records sent against records written and stops if they differ by one.

One thing I need from you: the token the sync uses expires on 14 October and
belongs to a named user rather than a service account. Twenty minutes with a
Salesforce admin moves it to an integration user and removes the expiry — who
should I send the steps to?

Jo

Quality Bar

• Every connector inventoried with direction, systems, auth, credential expiry, frequency, volume, a named owner on each side, and what stops if it stops — middleware and customer-built scripts included, negatives printed
• All eight dimensions scored per connector; any dimension without data reads UNKNOWN — requires X and never reads green
• Errors split into auth · rate limit · validation · schema · transient · permanent before any rate is quoted — no aggregate error rate stands alone; latency reported as p50 and p95 against their deadline, never as a mean
• All six silent-failure checks run on every connector, with clean results printed, and UNKNOWN where reconciliation was impossible — "no data loss detected" never substitutes for "loss was not measurable"
• Record reconciliation shown as arithmetic — submitted = succeeded + failed + unprocessed, then expected = submitted — with the residual named and the reconciliation level (L1–L4) stated
• Every credential dated, scoped (required vs granted), owned by a service account with two named humans, and its expiry compared against the opt-out deadline (R1)
• Remediation ranked by Impact × Severity × Urgency with the arithmetic shown for the top three and the tie-break rule stated; not ranked by error volume
• Every remediation row has action · owner (and side) · date · effort band · expected effect · success measure, and a detector left behind; no date without its owner's agreement (R19)
• Deprecation exposure recorded per connector with the vendor's own policy, dated against the opt-out deadline rather than the renewal date; and the renewal read stated internally — whether any disconnect went unreported by the customer, and for how long (R2, C21)
• Every number carries a provenance tag with a date or window; every inference states its rule; gaps read UNKNOWN — requires X with no benchmark substituted and no rows dropped
• Confidence stated and ≤ the Coverage Ledger cap (R23); severity banded, never a failure probability (R22); deferred connectors carry a reason and a revisit date (R14); every rule deviation names its number, the circumstance and what will be watched
• Every missing input resolved as read / ask / mark; questions asked once, batched, tappable; the Assumptions table carries a concrete consequence per row; every ingest mapping below 0.80 confidence confirmed; the data as-of date is printed
• Customer-facing text sits in a fenced ```text block below the divider with no placeholders, discloses the record count and window, and the leak scan found no criticality, severity band, ARR or renewal language in it (R18)

Anti-Patterns

Related Skills

Going Deeper

…(truncated)