git:20260502.5bc84e8 to git:20260912.5e86435

95 added, 168 removed. Audit A to A.

---

name: reaper

- description: "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."

+ description: "This skill runs the full Reaper research pipeline. You use it with a research goal and an optional paper."

user-invocable: true

argument-hint: "\"<research-goal>\" [paper-path] [--codex]"

license: Apache-2.0

- compatibility: "Requires python3 with arxiv, requests, beautifulsoup4 packages, internet access, and PDF reading capability. The --codex flag requires an MCP-capable host."

+ compatibility: "This skill requires python3, arxiv, requests, beautifulsoup4, internet access, and PDF reading. Codex review requires an MCP host."

---

- # Reaper: AI-Native Research Pipeline

+ # Reaper Research Pipeline

- You are the Reaper orchestrator. You take a research goal — optionally with a research paper — and autonomously conduct rigorous, multi-step academic research.

+ You must read and apply the [language rules](references/language.md) before you write any output.

## Usage

- 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).

+ You invoke this skill by name with a quoted research goal. You can add a paper path and `--codex`. Slash-command hosts use `/reaper "..."`.

```

- # 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 `--codex` 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 `references/codex-consultation.md` for the full protocol. Requires a host with MCP support and a registered Codex MCP server (e.g. [codex-mcp-server](https://github.com/tuannvm/codex-mcp-server)); silently no-op on hosts without MCP.

+ The research goal is required. An additional path to an existing PDF or text file identifies the paper. The `--codex` flag enables optional Codex reviews across the pipeline. You follow `references/codex-consultation.md` for that protocol.

+ Codex review requires an MCP host and a registered Codex MCP server. Hosts without MCP skip those reviews.

- When `--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.

+ You pass `--codex` context to each skill when the flag is present. Each skill uses its specified review point and a shared session ID.

## Peer Skills

- 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`).

+ The dependency table lists all required skills.

+ If a skill is missing, you ask the user to run `npx skills add SebastianElvis/reaper`.

## Invocation Convention

- 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:

- - **Slash-command hosts** (e.g. Claude Code): `/<sub>` (e.g. `/clarify-goal`)

- - **Auto-discovery hosts** (e.g. Cursor, Codex CLI, Cline, Continue, Gemini CLI, Copilot, Windsurf, OpenCode): the agent loads peer `SKILL.md` files from the skills folder and routes by `name` + `description` match.

- - **Manual invocation hosts**: explicitly point the agent at the installed skill's `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`).

+ You invoke each skill by name with the host's skill mechanism. You read its `SKILL.md` for instructions. Slash-command hosts use `/<name>`. Other hosts discover installed skills or need a pointer to `SKILL.md`. The `/<skill>` form identifies skills in these documents.

## Design Principles

- 1. **Separation of concerns**: Each skill has one job. Skills communicate through workspace files, not shared memory.

- 2. **Fixed evaluation signal**: Every investigation cycle produces a binary keep/discard verdict.

- 3. **Structured results log**: `notes/results.md` is the single source of truth for what has been tried and what happened.

- 4. **Keep-or-discard loop**: Only "keep" findings flow into `current-understanding.md`. Discards stay in the audit trail.

- 5. **Never stop**: The pipeline runs to completion. Uncertainty about user intent is never a reason to pause.

- 6. **Clarity and simplicity**: Prefer simpler proofs, fewer assumptions, shorter arguments.

+ - Each skill has one task. Skills exchange state through workspace files.

+ - Each cycle returns keep or discard. Only keep findings enter `current-understanding.md`.

+ - `notes/results.md` records each hypothesis's latest result. Logs preserve previous cycles.

+ - The pipeline runs to completion. You prefer simple proofs with fewer assumptions.

## Workflow

- ### Step 1: Initialize Workspace

+ ### Step 1: Initialize the Workspace

- Create the workspace directory structure:

+ You create `reaper-workspace/` with `notes/`, `papers/`, `investigations/`, `feedbacks/`, and `logs/`.

- ```

- 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

- ```

+ You use these file rules:

- **File mutation rules:**

+ | Files | Rule |

+ |---|---|

+ | `notes/current-understanding.md`, `notes/results.md`, `notes/ideas.md`, `notes/problem-statement.md`, `notes/literature.md` | One agent edits each file in place per batch. |

+ | `papers/*-notes.md`, `investigations/*/analysis.md`, `investigations/*/proof.md` | One agent edits each file in place per batch. |

+ | `logs/cycle-*.md`, `feedbacks/round-*.md`, `feedbacks/codex-consultation-*.md` | You create each file once. You never change it after creation. |

+ | `notes/paper-summary.md`, `notes/clarified-goal.md`, `report.md` | The responsible skill writes the file. It can regenerate the file on a rerun. Other skills do not edit it. |

- | 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. |

+ The `review-literature` skill creates `notes/literature.md`. The `investigate` skill adds new literature findings in place.

- **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`.

+ Investigation directories use `NNN-<slug>/` with leading zeros. Cycle logs use `cycle-NNN-<slug>.md`. Feedback files use `round-N.md` or `codex-consultation-N.md`. Paper notes use `<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.

+ Early stages read source files directly. Loop stages use `current-understanding.md` as their main source. They read paper summaries and literature only when a hypothesis needs them or progress stops.

- Initialize `reaper-workspace/notes/results.md` with:

+ You initialize `notes/results.md` with this table:

```markdown

# Investigation Results

- |-------|-----------|--------|---------|------------|--------|-------------|

+ |-------|------------|--------|---------|------------|--------|-------------|

```

- Initialize `reaper-workspace/notes/current-understanding.md` with:

+ You initialize `notes/current-understanding.md` with this text:

```markdown

# Current Understanding

- *No investigation cycles completed yet.*

+ The investigation has no completed cycles.

```

- ### Step 2: Clarify the Research Goal

- **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.

- ### Step 3: Establish Baseline (parallel)

- **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:

+ ### Step 2: Clarify the Goal

- 1. Invoke **`/analyze-paper`** with `<paper-path>` — produces `notes/paper-summary.md`

- 2. Invoke **`/review-literature`** with `"<research-goal>"` — produces `notes/literature.md`

+ You invoke the `clarify-goal` skill with `"<research-goal>"` and the paper path, if available. It asks 3-5 questions when the scope, assumptions, or success criteria need clarification. It writes `notes/clarified-goal.md` directly if the goal is already precise. Later stages use that file for the refined goal.

- Use the refined goal from `clarified-goal.md` for the literature review argument. Both must complete before proceeding.

+ ### Step 3: Establish the Baseline

- **If no paper was provided**, run only:

+ If the user supplies a paper, you run two independent subagents in parallel:

- 1. Invoke **`/review-literature`** with `"<research-goal>"` — produces `notes/literature.md`

+ 1. You invoke the `analyze-paper` skill with `<paper-path>` to write `notes/paper-summary.md`.

+ 2. You invoke the `review-literature` skill with the refined goal to write `notes/literature.md`.

- Skip `/analyze-paper` entirely — there is no paper to analyze. The pipeline proceeds without `notes/paper-summary.md`.

+ You use the host's parallel tool, or sequential execution if that tool is unavailable. You wait for both stages before you continue. Without a paper, you run only `review-literature`. In that mode, the workspace has no `notes/paper-summary.md`.

### Step 4: Formalize the Problem

- 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).

- ### Step 5: Brainstorm → Investigate → Critique Loop

- Run the core research engine: a recurring loop of brainstorm (generate ideas), investigate (execute on ideas), and critique (external perspective).

- #### Adaptive Loop Structure

- The loop adapts to problem complexity. Assess complexity after formalization, before the first brainstorm:

- - **Simple** (1-3 hypotheses, narrow scope, single claim to check): 2 brainstorm-investigate rounds, 3 cycles each, 1 critique. Total: ~6 investigation cycles.

- - **Moderate** (3-5 hypotheses, multiple steps or properties): 2 brainstorm-investigate rounds, 5 cycles each, 1-2 critiques. Total: ~10 investigation cycles.

- - **Complex** (5+ hypotheses, multiple interacting properties, broad scope): 3+ brainstorm-investigate rounds, 5 cycles each, 2+ critiques. Total: ~15+ investigation cycles.

- #### Default Patterns

- **Default (no `--codex`):**

- ```

- brainstorm → investigate N → critique --self → brainstorm → investigate N

- ```

+ You invoke the `formalize-problem` skill with the refined goal. It reads `clarified-goal.md`, `literature.md`, and `paper-summary.md` if available. It writes model assumptions, properties, and performance targets to `notes/problem-statement.md`. It writes initial hypotheses to `notes/ideas.md`.

- **With `--codex`:**

- ```

- brainstorm → investigate N → critique --codex → brainstorm → investigate N → critique --codex

- ```

+ ### Step 5: Run the Research Loop

- Where N is determined by the complexity assessment above.

+ You repeat brainstorm, investigation, and critique stages. You assess complexity before the first brainstorm round.

- #### Adaptation Signals During the Loop

+ | Complexity | Scope | Initial cycle plan |

+ |---|---|---|

+ | Simple | The goal has 1-3 hypotheses and one narrow claim. | You run two rounds of three cycles and one critique. |

+ | Moderate | The goal has 3-5 hypotheses or multiple properties. | You run two rounds of five cycles and 1-2 critiques. |

+ | Complex | The goal has at least five hypotheses or interacting properties. | You run at least three rounds of five cycles and two critiques. |

- - If >50% of cycles in a batch are "discard," the hypotheses may be poorly formulated — run brainstorm before the next batch rather than continuing with existing hypotheses.

- - If investigate returns early (all hypotheses resolved), run brainstorm to check for overlooked directions before moving to synthesis.

- - If a critique round generates 3+ new actionable hypotheses, extend the loop with another investigate batch.

- - If 2 consecutive batches produce only "keep" results with high confidence and no new hypotheses, convergence is likely — proceed to synthesis.

+ You invoke `brainstorm`, `investigate N`, `critique --self`, `brainstorm`, then `investigate N`.

+ With `--codex`, you replace `--self` with `--codex` and add `critique --codex` after the last batch.

+ N follows the complexity table.

- #### Re-Formalization Handling

+ You apply the first matching condition:

- If `/investigate` returns with a re-formalization signal (any cycle logged with outcome `reformulate`):

+ - If two consecutive batches contain only high-confidence keep results and no new hypotheses, you proceed to synthesis.

+ - Otherwise, if critique adds at least three useful hypotheses, you add an investigation batch.

+ - Otherwise, if all hypotheses resolve early or more than half of a batch has status `discard`, you run `brainstorm`.

- 1. **Preserve state**: Do NOT clear `notes/results.md`, `notes/current-understanding.md`, or existing investigation directories.

- 2. **Archive old formulation**: Rename `notes/problem-statement.md` to `notes/problem-statement-v<N>.md` before re-running.

- 3. **Re-run `/formalize-problem`**: It reads the reformulation signal from the triggering cycle's `analysis.md`.

- 4. **Reset ideas selectively**: In `ideas.md`, mark hypotheses that depended on the old formulation as `[superseded by v<N>]`. Add new hypotheses below.

- 5. **Restart loop**: Fresh cycle budget for the new formulation.

+ The `brainstorm` skill edits `ideas.md` with source tags `[Brainstorm-N]`. The `critique` skill can add ideas with `[Codex-N]` or `[Self-N]`. The next investigation batch selects unresolved ideas. You do not ask whether the user wants the loop to continue.

- #### Loop Mechanics

+ #### Re-Formalization

- 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.

+ If any cycle returns outcome `reformulate`, you take these actions:

- This loop runs autonomously — do not interrupt or ask if it should continue.

+ 1. You preserve results, current understanding, and investigation directories.

+ 2. You rename `notes/problem-statement.md` to `notes/problem-statement-v<N>.md` before the next formalization.

+ 3. You invoke the `formalize-problem` skill with the triggering cycle's `analysis.md` as context.

+ 4. You mark ideas that depend on the old formulation `[superseded by v<N>]`.

+ 5. You add new hypotheses below the preserved ideas.

+ 6. You restart the loop with a new cycle budget.

### Step 6: Synthesize

- Invoke the **`/synthesize`** skill — it reads all workspace files and produces `report.md`.

+ You invoke the `synthesize` skill. It reads the relevant workspace evidence and writes `report.md`.

### Step 7: Present Results

- After synthesis completes:

- 1. Read `reaper-workspace/report.md`

- 2. Present the key findings to the user

- 3. Point them to the full workspace for the audit trail

- 4. Proceed to Step 8

- ### Step 8: Offer Iteration

- After 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 `/critique` skill 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.

- ## Skill Dependency Graph

- ```

- /clarify-goal ──► /analyze-paper ──┐

- (if paper provided) ├──► /formalize-problem ──► /brainstorm ◄──► /investigate ◄──► /critique

- /review-literature ┘ │

- (calls /analyze-paper /synthesize ◄──────────┘

- for each paper)

- ```

+ You read `reaper-workspace/report.md`. You present key findings with links to the report and audit record.

- | 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 |

+ ### Step 8: Explain Further Iteration

- ## Important Notes

+ You explain that quoted feedback to `critique` can start another review. Slash-command hosts can use `/critique "your feedback here"`. You do not wait for a reply. After later critique cycles, you invoke `synthesize` for an updated report.

- - Sub-skills are invoked using the host agent's native skill mechanism — by `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.

- - Skills communicate exclusively through workspace files — no in-memory state passing

- - If a skill fails, read its output file to diagnose, then retry

- - The workspace is the source of truth — if context is compressed, re-read workspace files

- - Never ask the user "should I continue?" during the pipeline — run to completion

+ ## Dependencies and Outputs

- ## Context Window Recovery

+ | Skill | Required input | Output |

+ |---|---|---|

+ | `/clarify-goal` | Goal; optional paper | `notes/clarified-goal.md` |

+ | `/analyze-paper` | Paper; optional goal and output path | `notes/paper-summary.md` or `papers/<id>-notes.md` |

+ | `/review-literature` | Goal; optional paper summary | `notes/literature.md`, `papers/*` |

+ | `/formalize-problem` | Clarified goal, literature, optional paper summary | `notes/problem-statement.md`, `notes/ideas.md` |

+ | `/brainstorm` | Problem, ideas, current understanding, results | Updated `notes/ideas.md` |

+ | `/investigate` | Problem, ideas, current understanding, results | Updated notes; `investigations/*`, `logs/*` |

+ | `/critique` | Current understanding, results, problem, ideas | `feedbacks/*`; possible new ideas and cycles |

+ | `/synthesize` | Current understanding, results, problem, ideas | `report.md` |

+ | `/search-paper` | Query or paper identifier | Search results, citations, or venue |

- If the context window is compressed or the orchestrator loses track of its position, reconstruct the pipeline state from workspace files alone:

+ ## Failure and Context Recovery

- 1. **Check which files exist** in `reaper-workspace/notes/`

- 2. **Read `notes/results.md`** to determine investigation progress (count cycles, check for unresolved hypotheses)

- 3. **Read `ideas.md`** to find unresolved hypotheses (cross-reference with `notes/results.md`)

- 4. **Check for `report.md`** to determine if synthesis is complete

- 5. **Check `feedbacks/`** for iteration rounds

+ If a skill fails, you read its output to identify the cause before you retry. If conversation context is lost, you reconstruct state from workspace files:

- **Decision table:**

+ 1. You check `reaper-workspace/notes/` for existing files.

+ 2. You read `notes/results.md` for cycle progress.

+ 3. You compare `ideas.md` with results to identify unresolved hypotheses.

+ 4. You check `report.md` for completed synthesis.

+ 5. You check `feedbacks/` for later review rounds.

- |---|---|---|---|---|

- | 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. |

+ | State | Action |

+ |---|---|

+ | The source paper summary is missing. | You run Step 3 if the user supplied a paper. Otherwise, you check the literature review only. |