The Research Worker and the Document Auditor
Agents

The Research Worker and the Document Auditor

Skip to main content
Table of Contents
< All Topics
Print

The Research Worker and the Document Auditor

Last updated: November 20, 2026

Two of our agents never change a document. One gathers sourced research so that an editor or a builder agent can write from it. The other reads drafts and published articles and reports what is wrong with them. Keeping gathering and checking separate from writing is deliberate: the agent that checks a document is not the agent that wrote it.

What they are

kb-research-worker researches one question or one subject through our research gateway and the committed evidence store. It writes sourced findings and a results file. It mirrors the research assistant who pulls the records before anyone drafts.

doc-auditor is a read-only auditor of knowledgebase documents and drafts. It runs our checks, reads each document against its builder method and writes one findings file. It mirrors the quality reader who sends a draft back with notes and never touches the text.

When they run

Both run on demand, dispatched by an orchestrating session when it needs the work. The research worker is used when research must be gathered for a profile, a backgrounder or an audit, without anyone editing the knowledgebase. The auditor is used when a batch of drafts or published documents needs checking, or when a builder agent’s own report needs an independent check. Neither runs on a timer.

What they do

The research worker

  1. Checks what is already on file. It finds the subject’s document with a draft-aware lookup, reads it, and lists the records already committed to the evidence store. When the brief asks for it, a deterministic pre-fetch gathers the records a subject’s class requires. That pre-fetch is the only thing that writes to the evidence store. The worker never writes there by hand.
  2. Sets a budget for searches, court-record lookups, page fetches and data-client calls.
  3. Researches only through scripts/ca_research.py: searching (limited to primary-source domains where possible), extracting the pages it will cite, court-record lookups and named data clients. A refused request or a rate limit is recorded as a finding, and that line of research stops.
  4. Goes to primary records first. Officials and nominees: the financial disclosure. Donors: campaign-finance filings. Board members: proxy statements. Nonprofits: Form 990. Court matters: the docket. OpenSecrets and Wikipedia are leads to the record, never the cited source.
  5. Writes findings.md. One entry per claim, with the source (publication, title, exact date, URL), an evidence tier (documented, credibly reported or unverified) and, for court records, whether the subject is confirmed as a party. A court-record search that returns a count of zero is recorded as “unverified”. It is never written up as “no litigation.”

The auditor

  1. Resolves each slug with the draft-aware lookup, and reads its frontmatter and how each link resolves. A slug that matches both a published document and a draft is itself a finding.
  2. Runs the draft gate in strict mode (scripts/check_draft.py --strict). A failure is a finding, not a reason to stop.
  3. Runs the case-caption check (scripts/check_captions.py). It spends the shared court-record budget, so the auditor treats a budget-skipped result as “not checked”, never as a pass.
  4. Reads the document against its builder skill: the section order, the basis-for-inclusion block, the scoring block (nominees are scored only once confirmed and serving, otherwise it reads “not scored: no actions in office”), the factcheck notice before the sources, primary disclosures cited ahead of secondary coverage, and whether a dated sibling copy exists beside the original, which it should not.
  5. Writes findings.md. One row per finding, with the slug, the check, a severity of ERROR, WARN or NOTE, the file and line where there is one, and the evidence: the command and its output, or the quoted text. It says which findings came from a code check and which from the auditor’s own reading.

Skills they apply

The auditor reads documents against Accountability Profile Builder for a person and Agency Damage Assessment for an agency. The research worker’s source-first ordering follows the same profile method. The checks the auditor runs are those described in Draft Checks and Human Review. Both agents follow the shared delegation rules for our agents, which are an internal working document and are described, not linked, here.

Rules and gates they obey

Both agents are bound by the runtime limits in AI and Research Runtime Guardrails and the sourcing rules in Evidence, Sourcing and Language Rules. The research worker may not write a source it cannot support: a claim it cannot source is reported as unsourced. The auditor is bound by one rule above the rest: it audits, it does not fix.

What they may never do

The research worker never:

  • edits, creates or moves anything under the knowledgebase;
  • fabricates a source, quote, date, docket number or statute;
  • prints, logs or copies a key value;
  • makes a network request except through scripts/ca_research.py;
  • commits, pushes, merges, runs the GitHub tool or publishes.

The auditor never:

  • edits, moves or reformats any document, frontmatter or manifest, including an obvious fix;
  • runs a writer: no apply mode, no promotion, no publishing and no pre-fetch, because the pre-fetch writes to the evidence store;
  • commits, pushes, merges or runs the GitHub tool.

Where a human decides

Findings are not decisions. An orchestrator or an editor reads findings.md and decides what to fix, what to ignore and whether a document goes forward. The research worker’s output becomes a document only when an editor or a builder agent writes it. Each agent ends with a results file stating status, what it found and did not find, and its open questions, and a run without one is a failed step.

Team personas

These agents mirror three roles on the team: Elara Moncrieff — Document Research Specialist and Dana Whitfield — Public Records Research Specialist for the research worker, and Elliot Reeves — Internal Quality Auditor for the auditor. For the profile builders whose work the auditor checks, see The Profile Builder Agents and the Batch Kit. The full set of agents is in Agents and Automation: The AI That Works Here, and Its Limits.

Factual correction requests: If you believe information in this page is incorrect, please contact factcheck@citizenanalyst.ai with your name (optional), the specific claim, and any supporting documentation. We review all submissions and correct verified errors promptly.

Was this article helpful?
0 out of 5 stars
5 Stars 0%
4 Stars 0%
3 Stars 0%
2 Stars 0%
1 Stars 0%
5
Please Share Your Feedback
How Can We Improve This Article?