deep_research/.agents/skills/research-quality-gates/SKILL.md

---

name: research-quality-gates description: Applies stage gates for Antigravity-native Deep Research: search receipts, source access, claims ledger, triangulation, contradiction search, continuation state, and final assembly checks.

Research Quality Gates

Use this skill after every phase boundary and before any user-facing "done" claim. It is designed for Antigravity-native runs where model work happens inside Antigravity, while this repository provides the evidence discipline.

Core Principle

Evidence must persist outside the model context. A claim is not verified because the model remembers it, summarized it, or saw it in a search snippet. It is verified only when the artifact trail contains:

1. a search receipt,
2. an opened original source or explicit access failure,
3. a registered source_id,
4. an evidence span or data locator,
5. a claim-ledger record linking the claim to supporting and counter evidence.

Required Artifacts

Create these files when the relevant phase begins. Empty files are acceptable at creation time, but they must be populated before the phase gate passes.

Phase	Artifact	Purpose
Phase 1	phase1/method_decision.md	Selected method, rejected methods, evidence types, and search routes.
Phase 1	phase1/assumptions.md	Material assumptions and scope assumptions that need validation.
Phase 2	phase2/search_log.jsonl	One row per search/open/extract action.
Phase 2	phase2/sources.jsonl	Stable source registry with scores and tiers.
Phase 2	phase2/rejected_sources.jsonl	Rejected or low-quality sources with reasons.
Phase 2	phase2/claims_ledger.jsonl	Atomic factual and analytical claims with verification status.
Phase 2	phase2/coverage_matrix.md	Coverage of questions, chapters, methods, and evidence gaps.
Phase 2	phase2/unsupported_claims.md	Claims that could not be verified or need user-visible caveats.
All phases	continuation_state.json	Current phase, completed sections, artifact paths, open gaps, and next actions.
Phase 4	phase4/final_fact_check.md	Final audit showing each core fact exists in the verified claim ledger.

Search Receipt Gate

Every search or retrieval action must write a row to search_log.jsonl.

Required fields:

{
  "receipt_id": "srch_0001",
  "timestamp": "YYYY-MM-DDTHH:MM:SSZ",
  "tool": "search-cli|browser|project-search|other",
  "mode": "academic|scholar|patents|news|extract|general|deep",
  "query_or_url": "...",
  "purpose": "which task/card/chapter this supports",
  "result_count": 10,
  "opened_urls": ["https://..."],
  "status": "ok|partial|failed",
  "failure_reason": null
}

Gate fails if a model says it searched, confirmed, checked, extracted, opened, or verified a fact without a corresponding receipt.

Source Access Gate

For any source used as evidence, sources.jsonl must record access status.

Required additional fields:

{
  "id": "src_042",
  "search_receipt_ids": ["srch_0001"],
  "raw_url": "https://...",
  "canonical_url": "https://...",
  "title": "...",
  "publication_date": "YYYY-MM-DD",
  "source_type": "paper|regulator|trial_registry|patent|filing|database|consulting|media|other",
  "tier": 1,
  "score": 8.6,
  "access_status": "opened_original|opened_abstract|paywalled|failed|snippet_only",
  "evidence_locator": "page/table/section/trial id/patent claim",
  "independence_cluster": "cluster_...",
  "notes": "..."
}

snippet_only sources cannot support final claims. Paywalled or abstract-only sources can be used only with a visible caveat or a second opened source that carries the same fact.

Claim Ledger Gate

Each chapter draft must be backed by claims_ledger.jsonl. Store atomic claims, not paragraphs.

Required fields:

{
  "claim_id": "ch03_C012",
  "chapter": "ch03",
  "claim_type": "fact|trend|comparison|causal|forecast|recommendation",
  "claim": "...",
  "supporting_source_ids": ["src_042", "src_087"],
  "counter_source_ids": ["src_103"],
  "evidence_spans": [
    {
      "source_id": "src_042",
      "locator": "Table 2",
      "summary": "..."
    }
  ],
  "independence_clusters": ["cluster_a", "cluster_b"],
  "confidence": "high|medium|low|unsupported",
  "verification_status": "verified|partially_verified|conflicted|unsupported",
  "needs_delta_retrieve": false,
  "visible_caveat_required": false
}

Gate fails if:

• a core claim has fewer than 2 independent Tier 1-2 supporting sources;
• a claim has source IDs but no evidence locator;
• supporting sources all come from the same independence cluster;
• a conflicted or unsupported claim is written as a settled conclusion.

Triangulation Gate

Counting URLs is not enough. Sources are independent only when they do not trace back to the same press release, same trial registry entry, same company deck, same sell-side note, or same syndicated article.

For core conclusions, require at least two of these source families where available:

• regulator / official registry,
• peer-reviewed paper or systematic review,
• company filing / annual report / exchange disclosure,
• patent or legal record,
• independent database,
• reputable industry or consulting report,
• independent expert or professional media analysis.

If a field has only one source family available, mark the limitation explicitly in unsupported_claims.md and in the report limitations section.

Contradiction Gate

Every chapter requires at least one deliberate counter-search or falsification pass. Record it in search_log.jsonl and summarize it in the chapter brief.

Minimum counter-evidence record:

{
  "claim_id": "ch03_C012",
  "counter_query": "...",
  "counter_source_ids": ["src_103"],
  "result": "none_found|weak_counter|material_counter",
  "impact": "keep|qualify|rewrite|delete"
}

Gate fails if the chapter contains no counter-evidence section, no counter-search receipt, or no decision about how contradictions affected the draft.

Coverage Gate

Before drafting, create phase2/coverage_matrix.md with one row per chapter/task axis:

Chapter	Method	Core Question	Required Evidence	Found Evidence	Gaps	Decision

Gate fails if a chapter is drafted while its method, required evidence, or gaps are blank.

Delta-Retrieve Protocol

When a gap appears, do not patch it from memory. Create a targeted delta task:

1. write the gap in coverage_matrix.md or claims_ledger.jsonl;
2. run 1-3 targeted searches with explicit query purpose;
3. register any usable sources;
4. update the relevant claim record;
5. if still unsupported, keep the caveat visible.

Delta retrieval is mandatory when Phase 3 finds a critical evidence gap.

Continuation Protocol

For long reports or interrupted runs, keep projects/<slug>/continuation_state.json current.

Minimum fields:

{
  "version": "0.20",
  "slug": "...",
  "current_phase": "phase2",
  "active_model": "Gemini 3.1 Pro (Low)",
  "completed_artifacts": ["phase2/task_cards.json"],
  "open_gates": ["claim_ledger_gate"],
  "artifact_paths": {
    "sources": "phase2/sources.jsonl",
    "claims": "phase2/claims_ledger.jsonl",
    "search_log": "phase2/search_log.jsonl"
  },
  "open_questions": [],
  "next_actions": []
}

Before resuming a project, read this state and the latest artifacts. Do not rely on chat history alone.

Final Assembly Gate

Phase 4 must prove that final facts are a subset of verified claims:

• Sample at least 20 high-impact facts or all core claims, whichever is smaller.
• For each sampled fact, record claim_id, source_ids, verification status, and final wording decision in phase4/final_fact_check.md.
• New facts introduced during editing require new search receipts and claim-ledger records.
• Delete or caveat any unsupported factual claim before rendering PDF/DOCX.

Do not render final deliverables until the final assembly gate passes.