Research Skill

<paper> accepts: arXiv ID, DOI, or paper title (with clarify flow if ambiguous). See Unified Input Parsing section below.

All commands support optional --domain <categories> or --domain-only <categories> flags. See Unified Input Parsing section for details.

Workspace

On first invocation, create .research-workspace/ in the current working directory if it doesn't exist:

mkdir -p .research-workspace/sessions
echo '{"sessions": [], "current_session": null}' > .research-workspace/state.json

Each discover invocation creates a session: .research-workspace/sessions/{topic-slug}-{date}/ Contents:

• discover.json — search results with verdicts + landscape summary
• discuss/brief.json — research brief from discuss phase
• read/{paper_id}.json — structured paper analyses
• cite/{paper_id}.bib — verified BibTeX entries
• cite/cite-log.json — citation metadata and sources
• write/{section}.md — generated section text with metadata (output format, citations used, review gates applied)
• cache/{paper_id}/ — raw paper content cache (see Paper Cache)
• checkpoints/ — phase completion checkpoints (see State Persistence)

Paper Cache

Fetched paper content is expensive (network latency, rate limits, AlphaXiv/arXiv availability). After context compaction, all prior reads are lost. The cache stores raw content locally so it never needs to be re-fetched.

Cache directory structure

.research-workspace/sessions/{slug}/cache/{paper_id}/
├── overview.md          # AlphaXiv structured overview (if available)
├── fulltext.md          # AlphaXiv full text (if available)
├── paper.pdf            # arXiv or publisher PDF (if downloadable)
├── supplementary.pdf    # Supplementary/appendix PDF (if found)
├── openreview/
│   ├── reviews.json     # OpenReview official reviews (if venue uses OpenReview)
│   ├── rebuttal.json    # Author rebuttals (if available)
│   ├── meta_review.json # AC/SAC meta-review (if available)
│   ├── decision.json    # Accept/reject decision (if available)
│   └── discussion.json  # Threaded replies: author comments, reviewer follow-ups, ethics reviews
└── cache_meta.json      # What was cached, when, from where

cache_meta.json schema

{
  "paper_id": "s2_id or arxiv_id",
  "arxiv_id": "2401.12345",
  "doi": "10.xxxx/...",
  "cached_at": "ISO 8601",
  "contents": {
    "overview": { "source": "alphaxiv", "status": "cached|404|not_attempted" },
    "fulltext": { "source": "alphaxiv", "status": "cached|404|not_attempted" },
    "pdf": { "source": "arxiv|publisher|s2_open_access", "status": "cached|404|not_attempted" },
    "supplementary": { "source": "publisher|arxiv", "status": "cached|404|not_attempted" },
    "openreview": { "source": "openreview_api", "status": "cached|not_found|private|auth_failed|no_credentials|error|not_attempted", "venue": "ICLR 2024" }
  }
}

Cache protocol

On any paper content fetch (read, discover quick-read, discuss knowledge gap):

1. Check cache first: Look for .research-workspace/sessions/{slug}/cache/{paper_id}/. If cache_meta.json exists, read it to determine what's available.
2. Use cached content: If the needed content type has status: "cached", read from the local file. Do not re-fetch.
3. Fetch and cache on miss: If status is "not_attempted" or the cache directory doesn't exist, fetch from the network and save to cache.
4. Respect 404s: If a previous fetch returned 404 (status: "404"), do not retry — the content genuinely doesn't exist. Exception: retry after 7 days (AlphaXiv may add new papers).
5. Cross-session sharing: The cache is per-session. If the same paper appears in a different session, it will be re-fetched (sessions represent different research topics and may need different timeframes of content).

OpenReview integration

For papers published at venues that use OpenReview, attempt to fetch review records. This is a best-effort enhancement — all other features work without it.

Authentication required: The OpenReview API v2 (https://api2.openreview.net) requires a Bearer token. Obtain via POST /login with username/password. If no credentials are configured, skip entirely (log warning, set status: "no_credentials"). If /login returns mfaPending, log warning and skip (MFA accounts are not supported — they need an interactive challenge).

Credentials config: Set OPENREVIEW_USER and OPENREVIEW_PASS in .claude/settings.json under "env".

Fetch flow (when credentials are available — run every step with a short Python one-liner via python3 -c "...", using urllib.request and json.loads; no external deps):

1. Detect OpenReview venue: Check if the paper's venue (from S2 metadata) is known to use OpenReview. Known venues: ICLR, NeurIPS, ICML, AAAI, CVPR, ICCV, ECCV, COLM, EMNLP, ACL, NAACL, AISTATS, UAI, KDD, The Web Conference, TMLR, and ARR (review-only, not a publication venue). This list is not exhaustive — if a venue is not listed but the paper has an OpenReview URL in S2 metadata, attempt fetch anyway.
2. Authenticate: POST https://api2.openreview.net/login with Content-Type: application/json and body {"id": "<OPENREVIEW_USER>", "password": "<OPENREVIEW_PASS>"}. Parse response JSON — if mfaPending is truthy, set status: "auth_failed" and stop (MFA not supported). Otherwise extract token (valid 24h). Keep the token in memory for subsequent requests; if it must be persisted, use a tempfile.NamedTemporaryFile(mode='w', delete=False) with os.chmod(path, 0o600) and clean up on exit.
3. Search OpenReview: GET https://api2.openreview.net/notes/search?term=<url_encoded_title>&source=forum&limit=3 with Authorization: Bearer <token>. Match by normalized title equality (lowercase, strip whitespace). If the venue ID is known, add &content.venueid=<venue_id> to narrow results.
4. Fetch reviews: If a forum is found, GET https://api2.openreview.net/notes?forum=<forum_id>&limit=1000 with the same Bearer header. Classify notes using a dual-signal approach — check invitations[] first (strongest signal when present), then fall back to signatures + content keys (needed because invitation is often null for published papers):
   • Official reviews: invitation ending in Official_Review OR (signatures contains Reviewer_* AND content has review-like keys: summary, strengths, weaknesses, rating, confidence, soundness — field names vary by venue, e.g., review, main_review, recommendation)
   • Meta-reviews: invitation ending in Meta_Review OR (signatures contains Area_Chair_*/Senior_Area_Chair_* AND content has metareview key)
   • Decisions: invitation ending in Decision OR (signatures contains Program_Chairs AND content has decision key)
   • Author rebuttals: signatures contains Authors AND replyto points to a note already classified as a review
   • Discussion: all remaining threaded replies (author comments on forum root, reviewer follow-ups, ethics reviews, official comments)
   • Notes with replyto equal to the forum ID are direct replies. Notes with replyto pointing to another note are threaded discussion.
5. Parse v2 content shape: In API v2, note content fields are nested: note.content.{field}.value (not note.content.{field} directly). For example, rating at note.content.rating.value (e.g., "8: accept, good paper"), decision at note.content.decision.value (e.g., "Accept (poster)"). Review text may span multiple fields depending on venue — common keys include summary, strengths, weaknesses, review, main_review, comment, recommendation. Extract all content keys, don't hardcode a single field. Some fields may also have note.content.{field}.readers controlling visibility. Caution: API responses may contain raw control characters (tabs, newlines in review text). Parse with json.loads(text, strict=False); never strip control chars from stored artifacts (only do so for disposable human-readable inspection).
6. Save: Write reviews.json, rebuttal.json, meta_review.json, decision.json, discussion.json to cache/{paper_id}/openreview/.
7. Graceful degradation: Handle failures with appropriate status:
   • Auth failure (401) → status: "auth_failed", log warning
   • Restricted data (403 or notes returned with redacted/missing fields) → status: "private". Do NOT freeze as permanent — reviews may become public after camera-ready
   • Not found (empty results) → status: "not_found"
   • Network/server error (500/502/503/504) → retry once, then status: "error"
   • OpenReview data is valuable but never blocking

How cache integrates with phases

State Persistence

Long research sessions (especially discover → discuss → write chains) risk losing progress to context compaction. Each phase writes a checkpoint on completion so work can be resumed.

Checkpoint format

Save to .research-workspace/sessions/{slug}/checkpoints/{phase}_{timestamp}.json:

{
  "phase": "discover|discuss|read|cite|write",
  "status": "completed|in_progress|failed",
  "timestamp": "ISO 8601",
  "completed_steps": ["step1", "step2"],
  "pending_steps": ["step3"],
  "key_artifacts": {
    "discover_json": "relative path if exists",
    "brief_json": "relative path if exists",
    "read_analyses": ["paper_id1", "paper_id2"],
    "cite_log": "relative path if exists"
  },
  "context_summary": "1-2 sentence summary of what was accomplished and what remains",
  "skills_loaded": ["clip"],
  "user_decisions": ["chose direction A over B", "skipped experiment design"]
}

Write checkpoint

Each phase writes its checkpoint after saving its primary artifact (discover.json, brief.json, etc.). The checkpoint is a lightweight pointer — the real data lives in the phase artifacts.

Recovery on context compaction

If a session resumes after context compaction (detected by: user continues a /research command but prior conversation context is unavailable):

1. Read .research-workspace/state.json → identify current session
2. Read the latest checkpoint in checkpoints/ → reconstruct phase state
3. Read referenced artifacts (discover.json, brief.json, etc.) as needed
4. Reload domain skills from the checkpoint's skills_loaded list
5. Resume from pending_steps — do not re-run completed steps
6. Inform the user: "Resuming from checkpoint: {context_summary}"

Discuss phase mid-conversation checkpoints

The discuss phase is uniquely long-running (multi-turn). It writes incremental checkpoints at two points:

• After Phase 2 (Assumption Surfacing) completes
• After Phase 4 (Adversarial Novelty Check) completes

These capture the evolving research brief so that even if compaction occurs mid-discussion, the accumulated findings, open problems, and proposed directions are preserved.

Unified Input Parsing

Phases that accept a paper identifier (discuss, read, cite) share this logic. Discover takes a topic description, not a paper identifier.

Input Types

• arXiv ID (e.g., 2401.12345): Direct lookup via s2_match.py or S2 API
• DOI (e.g., 10.1109/...): Direct CrossRef/S2 lookup
• Free text (paper title or keywords):
  1. Try s2_match.py "<text>" for exact title match
  2. If no exact match: s2_search.py "<text>" 5 + dblp_search.py "<text>" 5

Clarify Flow

When free-text search returns multiple candidates, present each with:

• Title + authors (first 3) + year + venue
• One-sentence core contribution (from abstract)
• Quality marker (CCF/JCR tier via venue_info.py, citation count from S2 metadata)

User selects one → proceed to the requested phase.

Domain Override Flags

All commands support:

• --domain <cat1,cat2>: Additive — merge with auto-detected categories
• --domain-only <cat1,cat2>: Exclusive — use only these categories

Category names match the skill-router mapping table (semantic match OK).

Timeout Policy

Each parallel search agent has a 60-second timeout. If an agent times out or errors, proceed with results from the remaining agents. Log the failure but do not block.

Iron Rules

1. Zero hallucination citations — every citation from an API call, never from model memory
2. BibTeX priority — DBLP > CrossRef > S2 (AlphaXiv is content-only, not a citation source)
3. Exhaustive search escalation — when a retrieval task has no directly relevant results after the applicable primary searches, follow the Search Escalation Protocol before accepting "not found"
4. Quality gate — no paper presented to user without quality evaluation
5. Source tracing — every citation tagged with data source ("via DBLP", "via CrossRef", etc.)
6. Own model for analysis — never rely on AlphaXiv's AI-generated answers; use their content extraction, analyze with own Claude
7. Domain skill grounding — domain skills provide expert context, but all factual claims must still trace to paper content or API responses, never to skill-generated assertions alone
8. Adversarial before commitment — no research direction is finalized without adversarial novelty check against existing literature
9. Multi-perspective review for framing — abstract and introduction must pass reviewer, AC/SAC, and senior researcher perspectives + cross-model gate before finalization; related-work must pass coverage & fairness check (Claude + Codex)
10. Simplicity preference — between two approaches of similar merit, prefer the simpler one
11. Verify before completion — invoke superpowers:verification-before-completion before presenting final output in cite, write, and discover phases (see each phase for details)
12. Root cause before retry — when any script or API call fails, diagnose the root cause (API key expired? rate limit? malformed query? network error?) before retrying or switching strategy. Never retry blindly. (Borrowed from superpowers:systematic-debugging)

Search Escalation Protocol

When a retrieval task has no directly relevant results after the applicable primary searches, classify the failure before escalating:

Failure classification

Strategy ladder

Work through these strategies in order. Stop when directly relevant results are found and verified enough for the current phase. Earlier strategies are cheaper; later strategies cast a wider net.

1. Normalize query: expand acronyms, try alternate spellings/aliases, singular↔plural
2. Exact-match probe: s2_match.py for precise titles; DOI/arXiv ID direct lookup
3. Adjust year window: narrow for recent work, widen for foundational terminology (cheap parameter tweak)
4. Decompose: split compound queries into task + method + dataset + metric, search each separately
5. Switch retrieval mode: s2_search.py → s2_bulk_search.py → DBLP → CrossRef title search
6. Pivot to graph search: if any seed paper exists, use s2_citations.py, s2_references.py, s2_recommend.py
7. Body search: s2_snippet.py for method names or claims not in titles/abstracts
8. Abstract to adjacent fields: generalize the problem and search neighboring domains (label results as analogical evidence, not direct prior art)

Trigger conditions

Stop condition and attempt ledger

After exhausting the ladder, or when a strategy succeeds, produce an attempt ledger:

{
  "query_original": "...",
  "failure_type": "zero_results|exact_match_miss|metadata_mismatch|indexing_lag|query_drift|version_drift|timeout_or_rate_limit|source_outage",
  "attempts": [
    {
      "strategy": "normalize|exact_match|adjust_year|decompose|switch_mode|graph_search|body_search|adjacent_fields",
      "query": "expanded query text",
      "source": "s2_search|s2_bulk|s2_match|s2_citations|s2_references|s2_recommend|s2_snippet|dblp_search|dblp_bibtex|arxiv_bibtex|crossref_search|doi2bibtex|alphaxiv_agentic|alphaxiv_full_text|alphaxiv_embedding",
      "result_count": 0,
      "status": "matched|zero_results|irrelevant|timeout|rate_limited|source_down|error",
      "notes": "optional: error details, HTTP status, why results were irrelevant"
    }
  ],
  "final_outcome": "found|not_found_after_exhaustive_search|genuine_null|blocked_by_operational_failure",
  "resolved_by": "normalize|exact_match|adjust_year|decompose|switch_mode|graph_search|body_search|adjacent_fields|null"
}

"Not found after exhaustive search" is a valid, honest outcome. Some papers are not indexed, some methods have no prior work, and some queries target genuinely unexplored territory. Never fabricate papers or cite from model memory to avoid a null result.

Cross-Model Collaboration

Use a second LLM (via Codex MCP: mcp__codex__codex) throughout the lifecycle. The purpose is to surface blind spots that a single model misses and to create a three-way discussion (user + Claude + Codex) for richer exploration.

Roles

Codex participates in three modes:

• Co-thinker: Divergent phases (brainstorming, discussion) — Codex contributes independent perspectives alongside Claude. The user gets two models' views to synthesize.
• Adversarial reviewer: Convergent phases (novelty check, reviewer simulation, final commit) — Codex challenges the direction, looking for weaknesses.
• Cold reader: Simplicity test — Codex receives minimal context to test whether the idea is self-explanatory.

When to invoke

Protocol

1. Compose the prompt following the Task Brief (see below) — every Codex call must have GOAL/DELIVERABLE/EVIDENCE/CONSTRAINTS/DONE WHEN/EXCLUSIONS. Do NOT pass the entire conversation history — send only the artifacts listed in the "What to send" column.
2. Call mcp__codex__codex with the prompt.
3. For co-thinker mode: present Codex's ideas alongside Claude's, clearly labeled [Codex]. The user synthesizes both.
4. For adversarial mode: parse the response for actionable concerns (not stylistic preferences). Present labeled [Cross-model review].
5. The user decides which concerns/ideas to act on.

Phase 3 integration details

In the Discussion Loop, Codex participates as an ongoing third voice. The interaction model:

1. User raises a question or proposes a direction
2. Claude responds with analysis (infused with domain skill expertise)
3. Codex is consulted on the same question — but phrased to elicit a different angle (e.g., if Claude analyzed from a methodology perspective, ask Codex to consider from a practical/application perspective, or vice versa)
4. User sees both responses, picks what resonates, steers the next turn

Not every turn requires Codex. Use judgment:

• Invoke Codex when: the discussion hits a fork (multiple possible directions), a novel claim is made, the user questions a conclusion, or Claude is uncertain
• Skip Codex when: the turn is clarificational, the user is providing context, or the question is about a specific paper's content (domain skills + read phase handle this)

What this is NOT

• Not a score-chasing loop: No "iterate until score ≥ N." That optimizes for LLM preferences, not research quality.
• Not a rubber stamp: If Codex finds nothing, that's a valid signal.
• Not blocking: If Codex MCP is unavailable, all phases proceed with Claude-only analysis (log warning). No phase is gated on Codex availability.

Task Brief

Every delegated task — spawned agent, Codex review call, or subsearch dispatch — must follow a 6-element brief. This prevents vague tasking, bloated context, inconsistent outputs, and scope drift.

Schema

GOAL        — What decision this task informs; why it matters to the current phase
DELIVERABLE — Exact artifact to produce (format, fields, structure)
EVIDENCE    — Allowed evidence sources (which papers, which APIs, what context to send)
CONSTRAINTS — Result caps, token budget, timeout
DONE WHEN   — Acceptance criteria (how to verify the output is correct and complete)
EXCLUSIONS  — Forbidden behavior (what to exclude, what NOT to do)

Application by delegation type

Spawned search subagents (discover Step 3, dispatched via superpowers:dispatching-parallel-agents):

GOAL:       Find papers relevant to "{topic}" for landscape analysis
DELIVERABLE: JSON objects, each with: paper_id, title, year, venue, citations, doi, arxiv_id, authors, source
EVIDENCE:   Agent 1 (S2 subagent) — S2 API only (s2_search.py, s2_bulk_search.py)
            Agent 2 (AlphaXiv subagent) — three claude.ai-bound AlphaXiv MCP tools (agentic_paper_retrieval, full_text_papers_search, embedding_similarity_search), issued as three parallel tool calls in a single subagent message. Subagents inherit the top-level session's MCP bindings (empirically verified).
CONSTRAINTS: Top 20 results for S2; ~10 per AlphaXiv tool; 60-second timeout per subagent
DONE WHEN:  ≥1 result returned with all required fields populated; exit 0
EXCLUSIONS: Don't analyze, rank, or summarize papers — just retrieve and return raw results. Don't cross sources.

Codex review calls (all 10 integration points):

GOAL:       {varies — e.g., "Surface assumptions this field takes for granted" or "Find weaknesses in this research direction for {venue}"}
DELIVERABLE: Structured response: numbered findings, each with a concrete claim and evidence
EVIDENCE:   Only the artifacts listed in the "What to send" column of the invocation table — never the full conversation history
CONSTRAINTS: 3-5 actionable findings; no filler
DONE WHEN:  Each finding is specific enough to act on (names a paper, identifies a gap, flags a weakness)
EXCLUSIONS: Don't restate what was sent; don't make stylistic suggestions; don't hedge with "this could be strengthened" — say what's wrong and why

Knowledge-gap subsearches (discuss Phase 3):

GOAL:       Fill knowledge gap identified during discussion: "{specific method/baseline/claim}"
DELIVERABLE: 1-3 relevant papers with title, year, venue, and one-sentence summary of relevance
EVIDENCE:   S2 search + DBLP search; use the exact method/baseline name as query
CONSTRAINTS: Top 3 results; 30-second timeout per source
DONE WHEN:  At least one paper found that addresses the gap, or explicit "not found after exhaustive search"
EXCLUSIONS: Don't fabricate papers; don't use model memory; don't return tangentially related work

Write-phase review gates (Triple Review Gate + Codex):

GOAL:       {varies — e.g., "As an AC at {venue}, evaluate whether this abstract/intro would survive desk review"}
DELIVERABLE: 2-3 specific revision suggestions, each with: the problematic text, what's wrong, and a concrete fix direction
EVIDENCE:   Only the draft section text + research brief — not the full paper or conversation
CONSTRAINTS: Focus on substance (motivation, contribution clarity, positioning) not prose style
DONE WHEN:  Each suggestion identifies a specific passage and explains why it's a problem
EXCLUSIONS: Don't praise what works; don't suggest word-level edits; don't repeat the Iron Rules back

When to skip

Not every delegation needs full formality. Skip the brief for:

• Single-script calls (venue_info.py, ccf_lookup.py) — these have fixed I/O
• Clarificational Codex turns in discuss Phase 3 where the user is providing context

Language

All output in English. For uncommon vocabulary (GRE-level), add Chinese translation in parentheses.

Scripts

All scripts are in skills/research/scripts/. Key scripts:

Search

Quality Evaluation

Config

Dependencies

Required skills/plugins

• 85 domain skills from Orchestra-Research/AI-Research-SKILLs — bundled in vendor/ai-research-skills/ and not registered as standalone skills (only /research is exposed). The skill router loads them via Read on demand. Includes ml-paper-writing, brainstorming-research-ideas, creative-thinking-for-research, and all 21 domain categories. See phases/skill-router.md § "Loading Vendor Skills" for the load mechanism.
• humanizer skill — style review for write phase
• superpowers:dispatching-parallel-agents — parallel search in discover phase
• superpowers:verification-before-completion — output verification in cite/write/discover phases

Optional MCP servers

• Codex MCP (mcp__codex__codex) — cross-model collaboration throughout the lifecycle (discuss Phases 2-9, write Step 5.5 + 5.6). See Cross-Model Collaboration section for all 10 invocation points. If unavailable, all phases proceed with Claude-only analysis (log warning). Recommended but not blocking.
• AlphaXiv MCP (mcp__claude_ai_alphaXiv__*, via the claude.ai connection) — powers the second parallel search source in discover Step 3. The three tools (agentic_paper_retrieval, full_text_papers_search, embedding_similarity_search) are issued as three parallel tool calls inside the AlphaXiv subagent (dispatched alongside the S2 subagent via superpowers:dispatching-parallel-agents). If the MCP server is unavailable, discover falls back to S2 results only (log warning). Recommended for broader coverage but not blocking.

Required API keys

• Semantic Scholar: set S2_API_KEY in .claude/settings.json under "env". Claude Code automatically exports it as $S2_API_KEY. Get from: https://www.semanticscholar.org/product/api/api-key

Optional API credentials

• OpenReview: set OPENREVIEW_USER and OPENREVIEW_PASS in .claude/settings.json under "env". Register at: https://openreview.net/profile. Without these, OpenReview review/rebuttal data will not be fetched (all other features work normally).

Installation prompt

If dependencies are missing on first use:

Before using /research, please ensure:

1. Install required skills/plugins:
   - Orchestra-Research AI-Research-SKILLs (provides ml-paper-writing, brainstorming-research-ideas, creative-thinking-for-research, and 21 domain skill categories)
   - humanizer skill

2. Set up API keys in your .claude/settings.json:
   { "env": { "S2_API_KEY": "your-key-here", "OPENREVIEW_USER": "optional", "OPENREVIEW_PASS": "optional" } }
   Claude Code automatically exports env entries as environment variables.
   - Semantic Scholar: https://www.semanticscholar.org/product/api/api-key
   - OpenReview (optional): https://openreview.net/profile

Rate Limits