---
name: research-proposal
description: >
  Use when the user has a research proposal (problem + proposed methodology + planned experiments)
  and wants it iteratively strengthened until it clears a passing grade. ScholarEval grades the
  proposal against the literature (Soundness + Contribution), a Judge scores that feedback 0-100 on a
  fixed rubric, and a Reviser rewrites the proposal to fix the worst points without diluting the
  research question; loops until the grade passes or the budget is hit. Not for generating a proposal
  from scratch, and not for running a literature survey on its own.
compatibility: Requires Python 3.9+
metadata:
  version: "0.1.0"
---

# Research Proposal Loop

The artifact is a **research proposal**; the feedback signal is **ScholarEval** (literature-grounded
Soundness + Contribution) turned into a **0-100 grade** by a **Judge** against the fixed `rubric.md`.
Each iteration **evaluates → grades → revises** until the grade clears `<pass_threshold>` or the
budget runs out.

**North star.** Clearing the threshold is the stopping condition, not the goal. The goal is the
strongest, most novel, genuinely publishable version the proposal can *honestly* become — every
revision should ask "does this make the work more significant and more novel?", not just "does this
patch a flaw?". This is **grounded ambition**: the lift comes from better-justified methods, a
sharper-but-defensible novelty claim, and stronger baselines, all backed by real retrieved evidence.
Overclaiming *lowers* the grade (evidence gate + Contribution axis); it never raises it.

The cast (all in this folder):
- `roles/ScholarEval.md` — the two-module literature-grounded evaluator; emits `scholareval.json`.
- `roles/Judge.md` — grades the feedback → 0-100 + ranked fixes; emits `verdict.json` (decides pass).
- `roles/Reviser.md` — rewrites the proposal to address the fixes (guards the research intent).
- `rubrics/rubric.md` — the **fixed** grading rubric (the Judge never edits it).
- `schemas/scholareval.schema.json`, `schemas/verdict.schema.json` — the two validated outputs.

**Spawn-or-degrade.** On Claude Code, spawn ScholarEval / Reviser as real `Agent` subagents;
otherwise adopt each role inline. You are the orchestrator and the Judge.

## When to use
Use when a written proposal exists and the user wants it pushed past a quality bar with
literature-grounded critique. Default: run the full evaluate→grade→revise loop below. Escape hatch: if
the user only wants the critique (no rewriting), run one ScholarEval + Judge pass and stop. Not for
writing a proposal from a blank page, and not for a standalone literature survey.

## Setup
**Resolve bindings interactively.** If `loop.run.yaml` exists in the working dir, load it and skip to
the loop. Otherwise: on Claude Code (the `AskUserQuestion` tool is available) infer a likely value for
each binding and present it as the recommended option; on other hosts ask each as a quoted plain-text
prompt. Then write `loop.run.yaml` (format: `examples/run.example.yaml`) and confirm every value,
`<intent>`, and the live/degraded literature tier before creating any other files.

| binding | meaning | default | how to infer |
|---|---|---|---|
| `<proposal_path>` | file with problem + methodology + planned experiments | — | scan for a likely `.md`/`.txt`/`.pdf`; if only prose is pasted, save it to `<sandbox_root>/iter1/proposal.md` |
| `<intent>` | core research question + headline contribution, 2-3 sentences — **frozen**; the Reviser may never change it | — | read the proposal, extract it, have the user confirm |
| `<pass_threshold>` | grade (0-100) the proposal must reach to pass | 75 | a solid, well-grounded proposal without demanding perfection |
| `<budget>` | max iterations | 6 | — |
| `<patience>` | stop after this many consecutive no-improvement iterations | 2 | — |
| `<eval_scale>` | how much literature ScholarEval pulls per iteration (`low`/`medium`/`high`, see below) | `medium` | — |
| `grade_weights` | `soundness · contribution · evidence_quality` (must sum to 1; frozen for the run) | `0.45 · 0.35 · 0.20` | `rubric.md`; recommend default |
| `<sandbox_root>` | where snapshots, ledger, and lit cache live | `./sandbox` | — |

**Evaluation depth dial** (`<eval_scale>` caps per iteration — methods · dimensions examined ·
queries each · papers read full-text):

| preset | methods · dims | queries each | fulltext reads | effort |
|---|---|---|---|---|
| **low** | 2 · 2 | 1 | 0 (snippet/abstract only) | low |
| **medium** *(recommended)* | 4 · 3 | 2 | 2 | medium |
| **high** | 6 · 5 | 3 | 5 | high |

**Literature toolchain.** Paper search goes through the sibling **`literature-search` skill** —
resolve `<lit_skill_dir>` (it installs as a sibling, e.g. `~/.claude/skills/literature-search/`),
`<lit_py> = python3`, and `<lit> = <lit_skill_dir>/tools/lit_search.py`; append
`--cache-dir <sandbox_root>/literature/.cache` after a subcommand to reuse the cache. Confirm
`<lit> --help` works at setup; if the skill is absent, tell the user and either install it
(copy the repo's `loops/literature-search` folder into `~/.claude/skills/`) or degrade all retrieval to WebSearch/WebFetch
(no ranked snippets or citation-graph expansion). The keyless **S2 + arXiv** core
(`search`/`snippet`/`cite`/`fulltext`) needs no setup; a free `S2_API_KEY` makes `snippet`+`cite`
(ScholarEval's two defining moves) reliable.

**API key (optional, never block).** The `literature-search` skill owns the key convention: run
`<lit> keys --init`, then have the user fill the printed `keys.env` themselves and never paste secrets
into chat. Re-run `<lit> keys` to confirm presence and record the tier in `loop.run.yaml`
(`literature_tiers`, presence only). A missing key just degrades to the keyless pool → WebSearch.

**Initialise the sandbox** once bindings are confirmed:
```
<sandbox_root>/
├── loop.run.yaml        ← resolved bindings + <intent> + grade_weights + literature_tiers
├── ledger.tsv           ← header only (see Ledger)
├── literature/.cache/   ← lit_search on-disk cache
└── iter1/proposal.md    ← the input proposal (the baseline)
```

## The loop
`<N>` starts at 1; iteration 1 **evaluates the unmodified proposal** (the baseline grade — no
revision before it). Re-evaluate fresh every iteration: the grade comes only from a *new* ScholarEval
pass on the *revised* proposal, never carried over.

Copy this checklist and tick items off:
- [ ] **Evaluate** — run `roles/ScholarEval.md` (spawn-or-degrade) on `iter<N>/proposal.md` with the `<eval_scale>` caps and `<lit>`; it writes `iter<N>/scholareval.json` (validates against `schemas/scholareval.schema.json`).
- [ ] **Grade** — as the Judge (`roles/Judge.md`) apply `rubrics/rubric.md` to `scholareval.json`: evidence gate → 0-5 per axis → weighted `grade` → hard gates → `pass` + ranked `fixes`; write `iter<N>/verdict.json` (validates against `schemas/verdict.schema.json`).
- [ ] **Log** — append one `ledger.tsv` row (see Ledger).
- [ ] **Stop check** — `verdict.pass == true`, or `N == <budget>`, or grade flat for `<patience>` iterations → stop (see Stops).
- [ ] **Revise** — run `roles/Reviser.md` (spawn-or-degrade) with `verdict.json`, `scholareval.json`, `<intent>`, `<lit>`, and a small revision search budget (≈`<eval_scale>` searches + a couple of reads); it applies one focused fix batch and writes `iter<N+1>/proposal.md` + `iter<N+1>/revision_notes.md`.
- [ ] **`N = N + 1`** and repeat.

Every cited snippet must come from a real retrieval that iteration — never fabricated. When a lit tool
returns `{"error","fallback"}`, fall back to WebSearch/WebFetch; never invent a paper.

## Ledger
`<sandbox_root>/ledger.tsv`, tab-separated, never commas in free text:
```
iter	grade	pass	soundness	contribution	evidence_quality	top_fix	revision_summary
1	58.0	no	3	2	4	add MM-GBSA re-scoring	baseline (no revision)
2	71.0	no	4	3	4	add head-to-head vs [C2] pipeline	added re-scoring + scoped affinity claim
3	82.0	yes	4	4	4	-	reframed contribution around integration + new benchmark
```
The matching `scholareval.json` and `verdict.json` for each iteration live in `iter<N>/`. Report the
**best**-grade iteration when stopping on budget/plateau, not necessarily the last. Leave `ledger.tsv`,
`iter*/`, and `literature/` untracked.

## Constraints
- **Never fabricate citations or snippets** — every `evidence` entry comes from a real `<lit>`/WebFetch
  result retrieved that iteration, verbatim; the evidence gate exists to catch fabrication.
- **The rubric is fixed** — the Judge never edits `rubrics/rubric.md`, so the passing threshold stays
  meaningful across iterations.
- **Protect `<intent>`** — the Reviser may strengthen but never replace the core research question or
  headline contribution, and never gut a central method just to lift the grade.
- **Grade through evidence, not prose** — eloquence earns nothing; grounded support and surviving
  novelty earn the score.
- **One focused revision batch per iteration**, so each grade move is attributable.
- **No installs** — the sibling `literature-search` skill is stdlib-only; never print or commit API keys
  (`keys.env` stays gitignored at the project root). The sandbox is self-contained — no `../` escapes.

## Stops
The loop stops on the first of:
- **Pass** — `verdict.pass == true`. Report the final proposal (`iter<N>/proposal.md`), its grade, and
  the grade trajectory.
- **Budget** — `N == <budget>`. Report the best-grade iteration as the deliverable.
- **Plateau** — grade hasn't improved for `<patience>` consecutive iterations. Report the best
  iteration and the standing priority-1 fixes.

Always end with the deliverable proposal path, its grade and pass/fail, the grade trajectory from
`ledger.tsv`, and — if it did not pass — the standing blockers between this proposal and the bar.