Literature Review Integration

How the OpenClaw literature-review capability fits into the Codex-native workflow.

Design Reference · /home/jonas/social-carousel-codex/docs/literature-review-integration.md

Last modified: 2026-03-29T11:31:32.196Z

# Literature Review Integration

## Purpose

Phase 5 does not create a new literature-review engine. It reuses the existing OpenClaw literature-review capability as a supporting research tool for the Codex-native carousel workflow.

Supporting skill path:

- `.codex/skills/carousel-literature-review/`

Supporting skill name:

- `carousel-literature-review`

OpenClaw reference source:

- `/home/openclaw/workspace/skills/literature-review/`

## What Is Reused

Already usable from the OpenClaw reference:

- academic search across PubMed, OpenAlex, Semantic Scholar, and Crossref
- DOI-based detail lookup
- source deduplication
- PubMed-first biomedical search behavior

Reference script:

- `/home/openclaw/workspace/skills/literature-review/scripts/lit_search.py`

Reference commands:

```bash
python3 /home/openclaw/workspace/skills/literature-review/scripts/lit_search.py search "<query>" --limit 5 --source all
python3 /home/openclaw/workspace/skills/literature-review/scripts/lit_search.py search "<query>" --source pm
python3 /home/openclaw/workspace/skills/literature-review/scripts/lit_search.py details "DOI:<doi>"
```

## What Is Not Reused

Not reused as core workflow logic:

- OpenClaw multi-agent ownership
- OpenClaw packaging assumptions
- any live state inside `/home/openclaw/workspace`
- any Slack or Airtable orchestration around research

## Codex-Native Integration Pattern

The supporting skill is intentionally narrow:

1. The main workflow reaches a research step that needs evidence search.
2. `$carousel-workflow` invokes `$carousel-literature-review`.
3. `$carousel-literature-review` uses the OpenClaw script as a search capability only.
4. The synthesized output is persisted through the repo-local wrapper:
   - `python3 scripts/literature_review_wrapper.py build-package <spec.json>`
   - use `--summary-only` when the research package must stop for human approval before `research-lock.json` exists
   - then use `python3 scripts/runtime_state.py approve-research-proposal <idea_id>` for the normal approval-gated lock transition
5. Control returns to the main workflow for drafting, QC, and preview.

## Current Usable Capability

Usable now:

- search for papers by topic
- search PubMed specifically for medical topics
- inspect known DOI metadata
- persist a deterministic research summary plus either a pre-approval lock proposal or an approved research lock through the wrapper

Still missing:

- richer evidence synthesis beyond deterministic source transformation
- automatic semantic interpretation of abstracts into stronger evidence bullets

## Required Output Shape For The Main Workflow

At minimum, the main workflow needs:

`research-summary.json`

- idea id
- selected angle
- evidence summary
- sources
- required coverage
- slide architecture guidance

`research-lock.json`

- idea id
- research bundle id
- approved angle
- source citation map
- allowed claims
- required coverage
- forbidden claims or inferences
- approval metadata

Pre-approval artifact:

- `artifacts/research/<idea_id>/<research_bundle_id>/research-lock-proposal.json`
- no `approved_at`
- meant for operator review and later approval payload creation

## Invocation

Primary runtime invocation:

```bash
python3 scripts/literature_review_wrapper.py build-package <spec.json>
```

Approval-gated variant:

```bash
python3 scripts/literature_review_wrapper.py build-package <spec.json> --summary-only
```

Intended invocation in Codex:

```text
Use $carousel-literature-review to gather evidence for <idea_id> and synthesize a repo-local research package and research lock.
```

## Current Recommendation

Keep this as a supporting skill. The wrapper now closes the deterministic persistence gap while still treating the OpenClaw script as a reference search capability rather than a workflow owner.

Ready