Clay Failure Triage

What this does

Clay failures cluster into a small number of recurring shapes, and almost all of them present as the same symptom: a column that is empty when the data is obviously there. This skill walks the symptom to the root cause in the order that resolves fastest, cheapest checks first, and never suggests re running the column until the cause is named.

Requirements

Check these before you run the skill. Nothing outside this table is needed.

Requirement	Needed	Used for	What it costs you
A Clay workspace	Required	The failing column	Billed by Clay in credits on your own plan.

Missing a required item? Stop before the live steps and tell the user which item is missing and what it is for. Do not run the step without it and do not present an empty result as an answer. Keys are read from the environment at run time and are never written into a file, a prompt or the output.

When to use it

• my Clay column is empty
• Clay enrichment returns null
• Find People returned zero rows
• this worked last week and now it does not
• why is my Clay table broken

Inputs

• column: which column is failing and what action or provider backs it
• symptom: empty, wrong shape, zero rows, or intermittent
• sample: one row that should have worked, with its input values

Shared context this skill reads

Before doing anything else, read whichever of these exist at the project root and use them instead of asking the user to repeat themselves:

• ICP.md

If none exist, do the work from what the user gives you, then offer to write the missing file so the next skill in the pack starts warmer.

Tool connection

This skill needs no live data tool. It works from the files, exports and answers you give it, so it runs the same in any agent with no setup.

Method

1. Classify the symptom first: null on a row with good inputs, zero rows returned, an object where a scalar was expected, or a pipeline that degraded over time. The four take different paths.
2. Null with good inputs: check field name casing against the column output preview. This is the single most common cause and costs nothing to rule out.
3. Null with good inputs, casing correct: check whether the response is wrapped. A path of results.0.field and a path of field both look plausible and only one is real.
4. Zero rows: check the action name. Find People, Find People at Company and Enrich People are distinct actions. Enrich People needs a person identifier and returns nothing from a company filter.
5. Zero rows on a company lookup: check whether a company name was passed where a domain is required.
6. Object where a scalar was expected: read the provider schema in the response preview. Location is a string for some providers and a nested object for others.
7. Worked last week, blank now: the provider changed its response envelope. Re inspect raw JSON and update the extraction path. Log the date so the next degradation is measurable.
8. Intermittent: check the run condition, not the column. A conditional gate reading a column that is itself still running produces a race, not a failure.
9. Only after the cause is named, re run, and re run on 10 rows, not the table.
10. Check the output with scripts/check-output.py before you return it.

Approval stop

This skill does not send email or write to a CRM. If the user asks it to, stop first: show what would be sent or written and wait for an explicit yes.

Output

A short triage report: symptom class, cause, the exact fix, and the check that proves the fix worked. If the cause cannot be isolated from the sample given, say which single piece of evidence would settle it.

Check the output before you return it

Save the output to a file and run python3 scripts/check-output.py <file>. The contract it checks is scripts/output-contract.json.

• Exit 0, COMPLETE: return the output.
• Exit 2, INCOMPLETE: do not present the output as finished. Fill what you can, run the check again, and if parts stay missing, return the output under the heading Incomplete with every reason the check printed.

Quality bar

• The report names one root cause, not a list of possibilities
• The fix references a value the user can see in their own column preview
• No advice to re run the full table appears anywhere
• The proof step is a check, not an assertion

Related skills

• clay-build-gate
• clay-cost-audit
• clay-actor-column-wiring

Ships in the clay-operator pack.