Literature Search

---
name: literature-search
description: Run the canonical literature search bridge for one evidence query and persist traceable evidence artifacts.
---

# literature-search

Goal:

- Run the canonical literature search bridge for one evidence query and persist traceable evidence artifacts.

Inputs:

- active run directory
- a `SearchRequestContract` payload or enough context to build one
- optional existing `literature/queries/<query_id>/REQUEST.json`

Outputs:

- `literature/queries/<query_id>/REQUEST.json`
- `literature/queries/<query_id>/PROVIDER_RECEIPTS.json`
- `literature/queries/<query_id>/CANDIDATE_PAPERS.json`
- `literature/queries/<query_id>/VERIFIED_PAPERS.json`
- `literature/queries/<query_id>/EVIDENCE_BUNDLE.json`
- `literature/queries/<query_id>/EVIDENCE_BUNDLE.md`
- `literature/queries/<query_id>/SEARCH_TRACE.jsonl`
- `literature/bundles/<bundle_id>.json`

Context Loading:

- Open `skills/shared-references/schema-index.md`.
- Open `skills/shared-references/literature-search-contract.md`.
- Read `packages/agent_contracts/literature.py` before building or editing a search request or evidence bundle.
- Read `tools/literature_search_client.py` before invoking the bridge.

Execution Contract:

- Import and call `from tools import search_literature`.
- When the host exposes the configured `co_scientist_search_bridge` MCP server, its tools are an allowed transport for the same canonical bridge.
- If the MCP server is unavailable, fall back to the Python tools surface instead of performing informal web search.
- Do not perform informal web search as a substitute for `tools.search_literature(...)`.
- Do not invent papers, DOIs, arXiv IDs, venues, citation counts, or abstracts.
- Preserve provider failure receipts. A failed provider is evidence about retrieval coverage and must not be hidden.
- If `retrieval_metadata.status` is `blocked`, return that blocked state to the caller instead of fabricating an evidence bundle.
- If `retrieval_metadata.status` is `partial`, downstream callers may continue only when they preserve the partial-source limitation.

Execution Steps:

1. Open `skills/shared-references/schema-index.md`, `skills/shared-references/literature-search-contract.md`, and `packages/agent_contracts/literature.py`.
2. Build a `SearchRequestContract` with a stable `query_id`, `goal`, `query`, `query_type`, `providers`, `filters`, and `consumer`.
3. Call `tools.search_literature(run_dir, request)` through the stable tools surface, or call the equivalent configured MCP search bridge tool when it is available.
4. Read the returned `EvidenceBundleContract` and confirm the run-local artifacts were written.
5. If the bundle status is `blocked`, stop and report the blocked retrieval state to the caller.
6. If the bundle status is `partial` or `succeeded`, return the `bundle_id` and `query_id` to the caller.
7. Run `python -m tools.validation.contract_validation <run_dir> --skill literature-search`.

Completion Rule:

- This skill is complete only when the search bridge has written a canonical evidence bundle or an auditable blocked retrieval state, and the literature artifacts validate.