Run the full Reaper research pipeline: analyze a paper (optional), review literature, formalize the problem, investigate hypotheses with critique loops, and synthesize a report. Use when given a research goal, optionally with a paper.
You are the Reaper orchestrator. You take a research goal — optionally with a research paper — and autonomously conduct rigorous, multi-step academic research.
Invoke the /reaper skill with a research goal (quoted string), optionally followed by a paper path and/or --codex. Examples below use a generic name-based form; the slash-command form /reaper "..." works on hosts with slash-command routing (e.g. Claude Code).
# Without a paper — pure goal-driven research
reaper "explore the feasibility of post-quantum threshold signatures"
# With a paper
reaper "determine if the security proof in Section 4 holds under asynchrony" path/to/paper.pdf
# With external-model consultation for automated AI feedback between investigation cycles
reaper "determine if the security proof in Section 4 holds under asynchrony" path/to/paper.pdf --codex
Argument parsing: The research goal (quoted string) is required. If a path to an existing file (PDF or text) is also provided, treat it as the paper. Pass to enable external-model consultation across the entire pipeline — every skill gains an optional step where it consults an external model for a second opinion at a natural checkpoint. See for the full protocol. Requires a host with MCP support and a registered Codex MCP server (e.g. ); silently no-op on hosts without MCP.
--codexreferences/codex-consultation.mdWhen --codex is set, propagate this context to all skill invocations. Each skill will consult Codex only at its designated checkpoint (defined in references/codex-consultation.md), using compressed context and a shared session ID for continuity across the pipeline.
This orchestrator chains 8 sub-skills that must be installed alongside it: /clarify-goal, /analyze-paper, /review-literature, /formalize-problem, /brainstorm, /investigate, /critique, /synthesize. One more (/search-paper) is called transitively by /review-literature and /investigate. The /<skill> form is the canonical display convention used in these docs; substitute the host-native invocation form (slash command, auto-discovery, manual SKILL.md pointer) when actually running them.
If any of these are missing from your agent's skills folder, ask the user to reinstall the full Reaper package (npx skills add SebastianElvis/reaper).
References below to running a sub-skill use the host-agnostic phrase "invoke the <name> skill" — invoke each sub-skill by its name using your host's native skill-loading mechanism. The loaded SKILL.md provides the full instructions for that stage. Concrete invocation form varies by host:
/<sub> (e.g. /clarify-goal)SKILL.md files from the skills folder and routes by name + description match.SKILL.md (typical paths: ~/.claude/skills/<name>/SKILL.md, ~/.cursor/skills/<name>/SKILL.md, ~/.agents/skills/<name>/SKILL.md, ~/.continue/skills/<name>/SKILL.md, ~/.windsurf/skills/<name>/SKILL.md, or <repo-root>/skills/<name>/SKILL.md during development — substitute <name> with the sub-skill directory name like clarify-goal).notes/results.md is the single source of truth for what has been tried and what happened.current-understanding.md. Discards stay in the audit trail.Create the workspace directory structure:
reaper-workspace/
├── notes/ # Evolving — edited inline to reflect latest state
│ ├── current-understanding.md # Initialize empty — "branch tip"
│ └── results.md # Initialize with table header — one row per hypothesis, updated inline on revisit
├── papers/ # Evolving — per-paper notes can be updated
├── investigations/ # Evolving — reuse directory on revisit, edit inline
├── feedbacks/ # Append-only — one file per event, never modified
├── logs/ # Append-only — one file per cycle, never modified
File mutation rules:
| Category | Files | Policy |
|---|---|---|
| Evolving (inline edit) | notes/current-understanding.md, notes/results.md, notes/ideas.md, notes/problem-statement.md, notes/literature.md, papers/*-notes.md, investigations/*/analysis.md, investigations/*/proof.md | Edit in place. Single writer per file per batch. notes/literature.md is created by /review-literature and extended inline by /investigate during mid-cycle literature search. |
| Append-only | logs/cycle-*.md, feedbacks/round-*.md, feedbacks/codex-consultation-*.md | Create once, never modify. |
| Write-once | notes/paper-summary.md, notes/clarified-goal.md, report.md | Created by one skill. May be regenerated on re-run but not incrementally edited by other skills. |
File naming conventions: Investigation dirs: NNN-<slug>/ (zero-padded). Cycle logs: cycle-NNN-<slug>.md. Feedback: round-N.md, codex-consultation-N.md. Paper notes: <id>-notes.md.
Lazy-load protocol: Early-pipeline skills (/formalize-problem, /analyze-paper) read source files eagerly. Loop skills (/brainstorm, /investigate, /critique, /synthesize) use current-understanding.md as primary source and lazy-load paper-summary.md and literature.md only when stuck or when a specific hypothesis requires it.
Initialize reaper-workspace/notes/results.md with:
# Investigation Results
| Cycle | Hypothesis | Action | Outcome | Confidence | Status | Description |
|-------|-----------|--------|---------|------------|--------|-------------|
Initialize reaper-workspace/notes/current-understanding.md with:
# Current Understanding
*No investigation cycles completed yet.*
If a paper was provided:
Invoke the /clarify-goal skill with arguments "<research-goal>" <paper-path> — it does a quick scan of the paper, asks the user 3-5 targeted clarifying questions about scope, assumptions, and success criteria, then writes notes/clarified-goal.md.
If no paper was provided:
Invoke the /clarify-goal skill with argument "<research-goal>" — it asks the user 3-5 targeted clarifying questions based on the goal alone (no paper scan), then writes notes/clarified-goal.md.
If the goal is already precise and unambiguous, this step writes the file without asking questions.
All downstream skills should read clarified-goal.md for the refined goal and context.
If a paper was provided, run these two skills as parallel subagents using your host's parallel-spawn primitive (e.g. Claude Code's Agent tool, or the equivalent on your host; if the host has no parallel primitive, run them sequentially) — they write to non-overlapping files:
/analyze-paper with <paper-path> — produces notes/paper-summary.md/review-literature with "<research-goal>" — produces notes/literature.mdUse the refined goal from clarified-goal.md for the literature review argument. Both must complete before proceeding.
If no paper was provided, run only:
/review-literature with "<research-goal>" — produces notes/literature.mdSkip /analyze-paper entirely — there is no paper to analyze. The pipeline proceeds without notes/paper-summary.md.
Invoke /formalize-problem with "<research-goal>" — it reads the baseline outputs (clarified-goal.md, literature.md, and paper-summary.md if available) and produces notes/problem-statement.md (trust assumptions, security properties, performance goals) and notes/ideas.md (prioritized ideas).
Run the core research engine: a recurring loop of brainstorm (generate ideas), investigate (execute on ideas), and critique (external perspective).
The loop adapts to problem complexity. Assess complexity after formalization, before the first brainstorm:
Default (no --codex):
brainstorm → investigate N → critique --self → brainstorm → investigate N
With --codex:
brainstorm → investigate N → critique --codex → brainstorm → investigate N → critique --codex
Where N is determined by the complexity assessment above.
If /investigate returns with a re-formalization signal (any cycle logged with outcome reformulate):
notes/results.md, notes/current-understanding.md, or existing investigation directories.notes/problem-statement.md to notes/problem-statement-v<N>.md before re-running./formalize-problem: It reads the reformulation signal from the triggering cycle's analysis.md.ideas.md, mark hypotheses that depended on the old formulation as [superseded by v<N>]. Add new hypotheses below.The /brainstorm step reads the current state and updates ideas.md (adding new ideas, editing existing ones inline) (tagged [Brainstorm-N]). The /critique step may also add hypotheses (tagged [Codex-N] or [Self-N]). The next /investigate batch picks up all unresolved ideas automatically.
This loop runs autonomously — do not interrupt or ask if it should continue.
Invoke the /synthesize skill — it reads all workspace files and produces report.md.
After synthesis completes:
reaper-workspace/report.mdAfter presenting results, let the user know they can iterate:
If you'd like to refine, deepen, or challenge any aspect of this research, invoke the
/critiqueskill with your feedback as a quoted string. (Slash-command hosts:/critique "your feedback here".)
Do not block waiting for a response — the pipeline is complete. The user can invoke /critique with quoted feedback at any time to start a feedback round. The critique skill classifies the feedback, may run targeted investigation cycles, and then you should re-invoke /synthesize to produce an updated report.
/clarify-goal ──► /analyze-paper ──┐
(if paper provided) ├──► /formalize-problem ──► /brainstorm ◄──► /investigate ◄──► /critique
/review-literature ┘ │
(calls /analyze-paper /synthesize ◄──────────┘
for each paper)
| Skill | Requires | Produces |
|---|---|---|
/clarify-goal | (paper path, optional) | notes/clarified-goal.md |
/analyze-paper | (paper path) — skipped at top level if no paper; also called by /review-literature for each downloaded paper | notes/paper-summary.md or papers/<id>-notes.md (when --output is specified) |
/review-literature | (research goal); calls /analyze-paper --goal per downloaded paper | notes/literature.md, papers/* |
/formalize-problem | clarified-goal.md, literature.md, paper-summary.md (optional) | problem-statement.md, ideas.md |
/brainstorm | problem-statement.md, ideas.md, current-understanding.md, results.md | Updates ideas.md |
/investigate | problem-statement.md, ideas.md, current-understanding.md, results.md | Updates results.md, current-understanding.md, ideas.md; creates investigations/*, logs/* |
/critique | current-understanding.md, results.md, problem-statement.md, ideas.md | feedbacks/*; may update ideas.md |
/synthesize | current-understanding.md, results.md, problem-statement.md, ideas.md | report.md |
/search-paper | (query) | stdout — search results, citations, or resolved venue |
name plus arguments. The exact API differs per host (e.g. Claude Code's Skill tool with skill: "analyze-paper", args: "paper.pdf"; Cursor/Codex/Cline auto-route based on the loaded SKILL.md). Refer to the host's skill documentation for the exact form.If the context window is compressed or the orchestrator loses track of its position, reconstruct the pipeline state from workspace files alone:
reaper-workspace/notes/notes/results.md to determine investigation progress (count cycles, check for unresolved hypotheses)ideas.md to find unresolved hypotheses (cross-reference with notes/results.md)report.md to determine if synthesis is completefeedbacks/ for iteration roundsDecision table:
paper-summary.md | problem-statement.md | notes/results.md rows | report.md | Action |
|---|---|---|---|---|
| missing | - | - | - | Run Step 3 (baseline). If no paper was provided, this is normal — proceed with literature review only. |
| exists or N/A | missing | - | - | Run Step 4 (formalize) |
| exists or N/A | exists | 0 | - | Run Step 5 (brainstorm + investigate). Check ideas.md for unresolved hypotheses. |
| exists or N/A | exists | >0, unresolved H | - | Continue Step 5 (investigate or brainstorm). Check ideas.md for unresolved hypotheses. |
| exists or N/A | exists | >0, all H resolved | missing | Run Step 6 (synthesize) |
| exists or N/A | exists | >0 | exists | Run Step 7-8 (present + offer iteration) |