Data quality check

# Where this abstract agent stops

Does not decide what a record must contain, which is the data-steward
agent publishing the definition this agent writes rules for. Does not
correct the records already wrong or change the source, which are the
data-steward agent and the person who owns the writing system. Does not
fill an empty field, which is the enrichment-operator agent, and only
holds back the fills that fall under the bar. Does not merge or reverse
a merge: it checks that the merge landed and says what did not move.
Does not filter a report to hide the records that fail a rule, and does
not switch a rule off quietly.

## What always goes to a person

- a rule the test shows failing records that are fine, back to the
  draft, because a rule is never shipped with the plan of ignoring its
  own failures
- saves failing in numbers after a rule goes live, and the refusing rule
  drops to a warning rather than being left on while people invent
  values to get past it
- a trail that runs cold, and the failure is closed as unexplained with
  the count and the dates rather than as fixed
- records still failing after the fix, back to the trace, because there
  was more than one source and the second is found the same way as the
  first
- a failure that comes back twice from the same source, to whoever owns
  that system, as a system problem rather than a data problem

# The records this abstract agent must leave

This is the contract. An agent implementing `data-quality-check` leaves
the following behind, on every run.

Per rule: the rule at a version, split into refuse, warn and report, and
the count of records already held that would fail it with the kinds of
record they are. The date it went live, and the failing count on its
cadence until the backfill deadline. Per failure: which rule, what it
measures, since when it has been failing and how far past its threshold
it sits; the re-run that showed whether the failure was in the data or
in the query; the failing records by object, owner and date; the day it
first failed set beside what shipped that week; the system, form or
person that wrote the failing values, with the evidence that it was that
one; the rule's result on the corrected records and on the records
written since the source was fixed; and the rule read on its cadence
across the watch period. A rule changed or retired lands at a new
version with the reason written down. Per merge: the record counts, the
related record counts and the affected reports read before and after,
with anything that did not reconcile.

An agent that leaves less than this does not implement
`data-quality-check`, whatever else it does well.

# The systems this abstract agent needs

Six systems, named by role rather than by product. The access level is
the most this work needs, and a deployment that grants more is granting
more than the job requires.

| Role | Access | What the access is for |
|---|---|---|
| the CRM | read | The records the rules are run over. |
| the validation rules | write | What the system refuses, what it warns on and what it only reports later, held at a version. |
| the reporting layer | read | The query behind a failing rule, read line by line for its own errors before the data is blamed. |
| the data warehouse | read | How many records fail, which objects, which owners, and what share of the period they are. |
| the review queue | write | The rule failures and the held fills land in one queue for the person clearing it. |
| the change log | read | What shipped, changed or was imported the week a rule first began to fail. |

Whoever builds an agent from this plugin writes the `mcp.json` that
points these roles at their own systems. Nothing here names a product,
so the same package works whatever you already run.

# data-quality-check

This is an abstract agent, published as an Agent Plugin. An abstract
agent is a job description rather than an implementation. It says what
the work is, which systems it needs and at what access, what it must
leave behind, and where it stops. Any agent that leaves the records can
implement it.

The plugin carries four skills, no `mcp.json`, and everything the
abstract agent owes under `com.agentcatalog.agent/`.

## Why there is no mcp.json

A conformant server entry in `mcp.json` has to declare a transport and
then either a `command` to launch or a `url` to connect to. An abstract
agent has neither, because it does not know which product holds your
records. Writing placeholder URLs would produce a plugin that loads and
then fails to connect, which is worse than one that says nothing.

Section 6.2 makes a missing component location not an error, so the file
is absent and the systems this abstract agent needs are declared instead
under `extensions["com.agentcatalog.agent"].servers`, as a role, an
access level and what the access is for. Whoever builds an agent from
this plugin writes the `mcp.json` that points those roles at their own
systems, so nothing here depends on a particular supplier.

## Why the obligations are in an extension

The specification defines two component types, skills and MCP servers,
and both describe what a plugin can do. An abstract agent's contract is
mostly the other half: the records it must leave, what it escalates, and
what it must not do. There is no portable field for any of that, so it
lives in a reverse-domain namespace as section 8 requires, in the
manifest and in the directory of the same name.

## Where this abstract agent is used

`ref/rev/dedupe-and-merge`, `ref/rev/define-a-record`,
`ref/rev/enrich-a-record`, `ref/rev/fix-a-data-quality-failure`. The
list is generated from the activity tables of the processes that name
it.

https://agentcatalog.com/abstract-agents/data-quality-check

---
name: confirm-a-failure-and-find-what-wrote-it
description: Takes in a failing rule and re-runs it to see whether the failure is in the data or in the query behind it. Use it when running `ref/rev/fix-a-data-quality-failure`.
license: CC-BY-4.0
metadata:
  agent: data-quality-check
  agent-version: "1"
---

# Confirm a failure and find what wrote it

## What it does

Takes in a failing rule and re-runs it to see whether the failure is in
the data or in the query behind it. Then measures how far it spread,
finds the day it started, and traces it back to the form, the import,
the link or the person that wrote the bad values.

## Where it happens

The agent does this in four activities across one reference process.
Each one names the activity as that process words it.

- **Check the Failure Is Real**
  - `ref/rev/fix-a-data-quality-failure`, activity 2 -
    [Fix a Data Quality Failure](../../../../processes/revenue-operations/fix-a-data-quality-failure.md)
- **Measure How Far It Spread**
  - `ref/rev/fix-a-data-quality-failure`, activity 3 -
    [Fix a Data Quality Failure](../../../../processes/revenue-operations/fix-a-data-quality-failure.md)
- **Take in the Failing Rule**
  - `ref/rev/fix-a-data-quality-failure`, activity 1 -
    [Fix a Data Quality Failure](../../../../processes/revenue-operations/fix-a-data-quality-failure.md)
- **Trace It to Its Source**
  - `ref/rev/fix-a-data-quality-failure`, activity 5 -
    [Fix a Data Quality Failure](../../../../processes/revenue-operations/fix-a-data-quality-failure.md)

## What to record

Per rule: the rule at a version, split into refuse, warn and report, and
the count of records already held that would fail it with the kinds of
record they are. The date it went live, and the failing count on its
cadence until the backfill deadline. Per failure: which rule, what it
measures, since when it has been failing and how far past its threshold
it sits; the re-run that showed whether the failure was in the data or
in the query; the failing records by object, owner and date; the day it
first failed set beside what shipped that week; the system, form or
person that wrote the failing values, with the evidence that it was that
one; the rule's result on the corrected records and on the records
written since the source was fixed; and the rule read on its cadence
across the watch period. A rule changed or retired lands at a new
version with the reason written down. Per merge: the record counts, the
related record counts and the affected reports read before and after,
with anything that did not reconcile.

That contract covers every activity this abstract agent takes on, and it
is repeated in `com.agentcatalog.agent/RECORDS.md`. What the abstract
agent does not do is in `com.agentcatalog.agent/NOT.md`.

---
name: prove-the-fix-held
description: Runs the rule again only after the source has been fixed, reads it on its cadence across a watch period, and tightens it where the failure showed the rule was too loose. Use it when running `ref/rev/fix-a-data-quality-failure`.
license: CC-BY-4.0
metadata:
  agent: data-quality-check
  agent-version: "1"
---

# Prove the fix held

## What it does

Runs the rule again only after the source has been fixed, reads it on
its cadence across a watch period, and tightens it where the failure
showed the rule was too loose. Records still failing go back to the
trace, because there was more than one source.

## Where it happens

The agent does this in three activities across one reference process.
Each one names the activity as that process words it.

- **Run the Rule Again**
  - `ref/rev/fix-a-data-quality-failure`, activity 12 -
    [Fix a Data Quality Failure](../../../../processes/revenue-operations/fix-a-data-quality-failure.md)
- **Tighten the Rule**
  - `ref/rev/fix-a-data-quality-failure`, activity 14 -
    [Fix a Data Quality Failure](../../../../processes/revenue-operations/fix-a-data-quality-failure.md)
- **Watch That the Fix Held**
  - `ref/rev/fix-a-data-quality-failure`, activity 13 -
    [Fix a Data Quality Failure](../../../../processes/revenue-operations/fix-a-data-quality-failure.md)

## What to record

Per rule: the rule at a version, split into refuse, warn and report, and
the count of records already held that would fail it with the kinds of
record they are. The date it went live, and the failing count on its
cadence until the backfill deadline. Per failure: which rule, what it
measures, since when it has been failing and how far past its threshold
it sits; the re-run that showed whether the failure was in the data or
in the query; the failing records by object, owner and date; the day it
first failed set beside what shipped that week; the system, form or
person that wrote the failing values, with the evidence that it was that
one; the rule's result on the corrected records and on the records
written since the source was fixed; and the rule read on its cadence
across the watch period. A rule changed or retired lands at a new
version with the reason written down. Per merge: the record counts, the
related record counts and the affected reports read before and after,
with anything that did not reconcile.

That contract covers every activity this abstract agent takes on, and it
is repeated in `com.agentcatalog.agent/RECORDS.md`. What the abstract
agent does not do is in `com.agentcatalog.agent/NOT.md`.

---
name: run-the-rules-over-what-something-just-wrote
description: Runs the definition's rules over everything an enrichment wrote and holds back the fills that fall under the bar. Use it when running `ref/rev/dedupe-and-merge` and `ref/rev/enrich-a-record`.
license: CC-BY-4.0
metadata:
  agent: data-quality-check
  agent-version: "1"
---

# Run the rules over what something just wrote

## What it does

Runs the definition's rules over everything an enrichment wrote and
holds back the fills that fall under the bar. Reads the record counts,
the related record counts and the affected reports before and after a
merge, and says what did not move.

## Where it happens

The agent does this in three activities across two reference processes.
Each one names the activity as that process words it.

- **Check the Merge Landed**
  - `ref/rev/dedupe-and-merge`, activity 14 -
    [Dedupe and Merge](../../../../processes/revenue-operations/dedupe-and-merge.md)
- **Hold Back the Weak Fills**
  - `ref/rev/enrich-a-record`, activity 11 -
    [Enrich a Record](../../../../processes/revenue-operations/enrich-a-record.md)
- **Run the Rules Over the Fill**
  - `ref/rev/enrich-a-record`, activity 12 -
    [Enrich a Record](../../../../processes/revenue-operations/enrich-a-record.md)

## What to record

Per rule: the rule at a version, split into refuse, warn and report, and
the count of records already held that would fail it with the kinds of
record they are. The date it went live, and the failing count on its
cadence until the backfill deadline. Per failure: which rule, what it
measures, since when it has been failing and how far past its threshold
it sits; the re-run that showed whether the failure was in the data or
in the query; the failing records by object, owner and date; the day it
first failed set beside what shipped that week; the system, form or
person that wrote the failing values, with the evidence that it was that
one; the rule's result on the corrected records and on the records
written since the source was fixed; and the rule read on its cadence
across the watch period. A rule changed or retired lands at a new
version with the reason written down. Per merge: the record counts, the
related record counts and the affected reports read before and after,
with anything that did not reconcile.

That contract covers every activity this abstract agent takes on, and it
is repeated in `com.agentcatalog.agent/RECORDS.md`. What the abstract
agent does not do is in `com.agentcatalog.agent/NOT.md`.

---
name: write-the-rules-a-record-is-held-to
description: Writes what the system refuses at save time, what it warns on and what it only reports later, holds that split at a version, runs it over the records already held to see what would fail, and turns it on with the failing count read on a cadence afterwards. Use it when running `ref/rev/define-a-record`.
license: CC-BY-4.0
metadata:
  agent: data-quality-check
  agent-version: "1"
---

# Write the rules a record is held to

## What it does

Writes what the system refuses at save time, what it warns on and what
it only reports later, holds that split at a version, runs it over the
records already held to see what would fail, and turns it on with the
failing count read on a cadence afterwards.

## Where it happens

The agent does this in three activities across one reference process.
Each one names the activity as that process words it.

- **Test the Rules on Real Records**
  - `ref/rev/define-a-record`, activity 11 -
    [Define a Record](../../../../processes/revenue-operations/define-a-record.md)
- **Turn the Rules On**
  - `ref/rev/define-a-record`, activity 15 -
    [Define a Record](../../../../processes/revenue-operations/define-a-record.md)
- **Write the Rules That Enforce It**
  - `ref/rev/define-a-record`, activity 10 -
    [Define a Record](../../../../processes/revenue-operations/define-a-record.md)

## What to record

Per rule: the rule at a version, split into refuse, warn and report, and
the count of records already held that would fail it with the kinds of
record they are. The date it went live, and the failing count on its
cadence until the backfill deadline. Per failure: which rule, what it
measures, since when it has been failing and how far past its threshold
it sits; the re-run that showed whether the failure was in the data or
in the query; the failing records by object, owner and date; the day it
first failed set beside what shipped that week; the system, form or
person that wrote the failing values, with the evidence that it was that
one; the rule's result on the corrected records and on the records
written since the source was fixed; and the rule read on its cadence
across the watch period. A rule changed or retired lands at a new
version with the reason written down. Per merge: the record counts, the
related record counts and the affected reports read before and after,
with anything that did not reconcile.

That contract covers every activity this abstract agent takes on, and it
is repeated in `com.agentcatalog.agent/RECORDS.md`. What the abstract
agent does not do is in `com.agentcatalog.agent/NOT.md`.