inferrex-diagnose-flow · Get SKILL.md

Diagnose a failing flow or system in Inferrex

Read first. Do not change anything until you can name the cause. Most sudden failures are one of five things: a sign-in the system now refuses, a paused system, a safety stop holding the sync, a repair question waiting for an answer, or records the destination will not accept.

Words: a flow is a pipeline in tool and route names. A failed write is a quarantine row. A repair is a heal. A safety stop is a circuit breaker.

When to use

"The orders flow has stopped." / "Nothing has synced since yesterday."
"Why is this system showing as unhealthy?"
"What needs my attention in Inferrex?"

Prerequisites

InferrexMCP at https://mcp.inferrex.com/mcp (sign-in or API key in a header), or InferrexAPI at https://api.inferrex.com with X-API-Key: $INFERREX_API_KEY.
Read-only diagnosis needs read scopes: workspace:read, pipelines:read, connections:read, jobs:read, heals:read, monitoring:read, pipeline-events:read, circuit-breakers:read. connections_test_saved_connection needs connections:write, though it changes nothing.
Fixes need the matching write scope. If a call answers 403 scope_denied, report the scope named in the message and stop.

Steps: find the cause

Work down the list. Stop at the first step that explains the failure, then go to "Propose a fix".

Overview. Call workspace_get_environment_overview with detail: "brief". Note every critical and warning item that names the flow or its systems. For more on one area, call it again with module set to that area's key.
Identify the flow. Call pipeline_list, match the user's name, then pipeline_status with its id. Note status (draft, reviewing, active, paused, error, upgrading, archived), source_connection_id and target_connection_id.
- draft: it was never turned on. That is the answer.
- paused: go to step 3.
Check its systems. Call connection_list. For the source and each destination, note status, paused_at, reconnect_required_at and reconnect_reason.
- paused_at set: the system is paused, and every flow that uses it is paused with it.
- reconnect_required_at set: someone must sign in again.
Test each sign-in. Call connections_test_saved_connection with each system's id. It only reads. A pass is outcome signed-in or read-without-sign-in. Otherwise report outcome, httpStatus and detail. Also call credentials_list_failing_secrets.
Read the last runs. Call pipeline_history. Note the latest run's status and its counts of records read, written, skipped and failed. Call jobs_list and jobs_get_job for the failed run and read error.
Look for a safety stop. Call monitoring_stream_circuit_breakers_list with connection_id. If one is open, call monitoring_list_circuit_breaker_records to see what it holds.
Look for a repair question. Call heals_list with status: "open" and pipeline_id. For each, heals_get_heal gives the message, the question and its options.
Look at failed writes. Call pipelines_list_pipeline_quarantine with id and status: "open". Group by failure_reason.
Look at events and anomalies. Call monitoring_pipeline_events_list with pipeline_id, and pipelines_get_anomalies.
Check the mapping version. Call pipelines_list_pipeline_mappings, then mappings_list_mapping_pipelines with the mapping id. upToDate: false means the flow runs an older version than the one last edited.

Propose a fix

State the cause in one sentence with the evidence (the tool and the field). Then propose one fix and wait for a yes.

Cause	Fix	Tool
Sign-in refused	Replace the credentials. Use `inferrex-replace-credentials`.
Provider sign-in lapsed	A person signs in again in the app, on the system's Sign-in tab.
System paused	Resume it. Flows its pause stopped go live again.	`connections_resume_connection`
Flow paused	Turn it back on. A sync starts at once.	`pipeline_activate`
Repair question open	Give the user the question and options. Send their answer.	`heals_answer_heal`
Failed writes, reason starts `record_validation:`	The record lacks a value the destination requires. It must be corrected in the source system. Nothing to do in Inferrex.
Other failed writes	Usually nothing. The next sync retries each one. To retry one held record now:	`pipelines_release_quarantined_record`
Safety stop holding records	The user decides after seeing the held records.	`monitoring_approve_quarantined`, `monitoring_partial_approve`, `monitoring_reject_quarantined`, `monitoring_hold_open`
Flow on an old mapping version	Move it, with the version the user reviewed.	`pipelines_apply_mapping_to_pipeline`
The system's API changed address or sign-in method	Read it again. For a system in use the new reading waits beside the live one for approval.	`connections_reinfer_connection`

After a fix, confirm it: run step 4 again for a sign-in fix, or pipeline_sync then jobs_get_job and pipeline_history for a flow fix. Report the result of that run.

Checks before any write

Every tool in the "Fix" table changes something. Get a yes for each one.
monitoring_reject_quarantined deletes the held data. Show the held records first and say that it deletes them.
monitoring_force_close closes a stop without a decision on its records. Do not offer it as a first choice.
pipeline_activate starts a full sync at once. Say so.
Do not run a full sync to "see if it helps".

Equivalents

Check	InferrexMCP tool	InferrexAPI
Overview	`workspace_get_environment_overview`	`GET /v1/workspace/overview`
One flow	`pipeline_status`	`GET /v1/pipelines/:id`
Flows with something waiting	`pipelines_get_pipeline_attention`	`GET /v1/pipelines/attention`
Systems	`connection_list`	`GET /v1/connections`
Test saved sign-in	`connections_test_saved_connection`	`POST /v1/connections/:id/test`
Failing secrets	`credentials_list_failing_secrets`	`GET /v1/workspace/secrets/failing`
Runs	`pipeline_history`	`GET /v1/pipelines/:id/history`
Job	`jobs_get_job`	`GET /v1/jobs/:id`
Safety stops	`monitoring_stream_circuit_breakers_list`	`GET /v1/circuit-breakers`
Held records	`monitoring_list_circuit_breaker_records`	`GET /v1/circuit-breakers/:id/records`
Repairs	`heals_list`, `heals_get_heal`	`GET /v1/heals`, `GET /v1/heals/:id`
Answer a repair	`heals_answer_heal`	`POST /v1/heals/:id/answer`
Failed writes	`pipelines_list_pipeline_quarantine`	`GET /v1/pipelines/:id/quarantine`
Events	`monitoring_pipeline_events_list`	`GET /v1/pipeline-events`
Health scores	`monitoring_get_connection_health`	`GET /v1/monitoring/health`
System history	`connection_audit`	`GET /v1/connections/:id/audit`

Report back

The cause, in one sentence, with the evidence.
What you checked and found clear, so the user knows what was ruled out.
The fix proposed, whether it was applied, and the result of the run that confirmed it.
Anything that needs a person in the app or in the source system.

If no step explains it, say so. List what you checked and give the failed job's id and error. Do not guess.

Never

Never change anything before you can name the cause.
Never reject or force close a safety stop on your own judgement.
Never answer a repair question for the user.
Never archive or recreate a flow or a system to clear an error. Mappings, flows and rules refer to them by id.
Never read a health score for a system marked unmeasured as a problem. It means no activity.
Never ask for, print or log a credential value. Inferrex never returns one.