PRISM

Generate literature-grounded research proposals from an existing ML repository.

PRISM (Plan Retrieval and Integrated Survey Methodology) points a sequence of criticized Claude Code agent teams at your repository, surveys real academic literature for it, and comes back with independent research directions — each one backed by an actual cited paper, not an invented one — rendered as a single short Markdown report.

What PRISM is not

• Not a code generator. No team in this pipeline evaluates implementation feasibility, writes code, or opens a PR. The output is research directions and the literature that grounds them — what to investigate, not how to build it.
• Not for arbitrary repos. Every stage assumes the target repo has a task, an evaluation metric, and a domain (the kind of thing an ML paper's "Method"/"Experiments" sections describe). Pointing it at a web app or a general-purpose library will produce thin or confused output.
• Not run from a different project. PRISM resolves "the repository" as the project Claude Code is currently open in. Open Claude Code inside the repo you want PRISM to study, install the plugin there, and run the commands from that session.

Run only as much as you need

The diagram above shows the shape of it; in practice PRISM is incremental, not all-or-nothing. Each stage writes its result to state/<team>/final.md and never re-runs work that's already there — so you stop wherever the depth you have is enough, and pick back up later without repeating anything. These are real numbers from runs against research-shaped repos; yours will vary with repo complexity and how many criticism retries get triggered.

Stage	Command(s)	You get	Typical cost
Repository Profiling	/prism:0_problem_framing_team, /prism:1_repository_problem_profile_team	A problem framing + repository profile — no literature, no candidates yet.	~335k tokens, ~18 agent calls, ~9 min
Literature Survey	/prism:2_task_survey_team, /prism:2_method_survey_team	A literature survey for just the angle you ran — these two are independent sub-teams; run one, both, or neither.	~300k tokens, ~7 agent calls, ~11–12 min, per sub-team
Candidate Generation	/prism:6_plan_generation_team	Independent, citation-backed research candidates (not yet rendered to a report).	~125k tokens, ~5 agent calls, ~4 min
Report Generation	/prism:7_plan_rendering_team	report.md — a human-readable rollup of the survey and candidates. This is where most users stop.	Free, instant — a deterministic script, no agents
Research Seed Expansion (optional)	/prism:8_research_seed_story_team	One candidate from the report expanded into paper-shaped sections (Background, Goal, Related Research, Method, Experimentation, Conclusion).	~150k tokens, ~5 agent calls, ~5–6 min
Practical Research Narrative (optional)	/prism:9_practical_research_narrative_team	That seed story stress-tested by four adversarial personas (professor, scout, IT engineer, student) — sections can come back marked open if no one could defend them.	~400–500k tokens, ~100+ tool calls, ~15+ min

Every stage depends on the ones before it — Literature Survey needs Repository Profiling's output to know what to search for, Candidate Generation needs the Literature Survey to cite, and so on — so "run only what you need" means choosing how far down this chain to go, not skipping a stage in the middle. The one real exception is inside Literature Survey itself: its two sub-teams are independent of each other, so run only the angle you actually care about.

For the full command-by-command breakdown of how each stage is implemented, see docs/pipeline.md.

Install

/plugin marketplace add tim-nish/PRISM
/plugin install prism

Prerequisites

• uv on your PATH (the literature-search MCP server is a standalone uv project — uv sync runs automatically the first time it's invoked).
• Python 3.11+ for that MCP server.
• No API keys are required. OpenAlex works anonymously; Semantic Scholar and PubMed work at shared rate limits without a key. All of the following are optional, set via the plugin's configuration:

Setting	Purpose
state_root	Where PRISM writes its output. Defaults to .claude/prism/ inside the current project.
openalex_mailto	Contact email for OpenAlex's faster "polite pool".
ncbi_email, ncbi_api_key	Contact email / higher rate limit for PubMed.
semantic_scholar_api_key	Higher Semantic Scholar rate limit.

Quick start

From inside the repository you want PRISM to study, run each stage in order:

1. Repository Profiling — /prism:0_problem_framing_team, then /prism:1_repository_problem_profile_team
2. Literature Survey — /prism:2_task_survey_team, /prism:2_method_survey_team
3. Candidate Generation — /prism:6_plan_generation_team
4. Report Generation — /prism:7_plan_rendering_team

Then open .claude/prism/report.md.

Worked example: nanoGPT

This is real output from running the six commands above against nanoGPT (a GPT-2 reproduction/training repo) in a clean session opened inside that repository. Results from your own run will differ — literature search results drift over time, and the generation/criticism steps are not deterministic.

This run, in numbers: 19 search queries → 25 papers retained after alignment filtering → 8 candidates drafted → 2 rejected for insufficient grounding → 6 final candidates, citing 9 papers.

report.md came back with those 6 independent candidates. Two of them:

Investigate parameter-efficient adaptation techniques (e.g., low-rank or adapter-based delta-tuning) as an alternative to full-parameter finetuning for adapting the pretrained GPT-2 weights to the small, narrow target corpus used in the low-data finetuning regime.

Evidence strength: Strong (3 papers, avg alignment score 4.0/4) Cited: Parameter-efficient fine-tuning of large-scale pre-trained language models (2023), QLoRA: Efficient Finetuning of Quantized LLMs (2023), On the Effectiveness of Adapter-based Tuning for Pretrained Language Model Adaptation (2021)

Apply inference-time decoding algorithms — speculative sampling with a smaller draft model, and contrastive decoding contrasting an expert and amateur model — to the autoregressive token-by-token generation process, evaluating their effect on generation behavior without altering the underlying trained model or its training objective.

Evidence strength: Strong (2 papers, avg alignment score 4.0/4) Cited: Accelerating Large Language Model Decoding with Speculative Sampling (2023), Contrastive Decoding: Open-ended Text Generation as Optimization (2023)

The full report also includes a referenced-papers table (9 papers across the 6 candidates), an explicit "no candidate is unsupported" missing- evidence check, and an open-questions list naming exactly which survey queries came back too sparse to ground a candidate — visible reasoning about what the pipeline couldn't find, not just what it could.

Two of the generator's eight initial candidates didn't survive review. Both tried to ground a direction in the same paper — a non-attention sequence architecture — first as a direct architecture-swap proposal, then, after the one allowed revision, reworded into a narrower "add it alongside attention instead of replacing it" framing. The criticism agent rejected both: the cited paper's own abstract describes removing attention entirely, so neither framing was actually supported by what it said. Per the pipeline's rule (one revision, then stop if still rejected), the team halted there instead of forcing a synthesis — the final drop was a human call, not an automatic resolution. That's the behavior worth trusting: PRISM would rather come back with 6 candidates than 8 with one quietly unsupported.

Output

Everything PRISM writes lives under <state_root> (default .claude/prism/), and nothing else in your repository is touched:

• state/<team>/final.md — each team's latest result; downstream teams read these.
• runs/<timestamp>/<team>/ — a full, immutable trace of every agent call in every run, including rejected/revised attempts, for audit.
• runs/index.yaml — one line per run: tokens, tool calls, duration, pass/fail, across the whole pipeline's history.
• report.md — Report Generation's output.

.claude/prism/ is meant to be gitignored in the repo you run it against; treat it as a build artifact, not something to commit.

Known limitations

• MCP tool availability. The Literature Survey stage's search phase depends on the bundled literature-search MCP server. In some environments the tool doesn't get exposed to agents even when claude mcp list reports the server connected. If a search step comes back saying the tool is unavailable, verify with claude mcp list in a plain terminal session (not just the IDE extension), and try restarting Claude Code from there.
• Survey results are not reproducible. OpenAlex/Semantic Scholar/PubMed indexes change over time; re-running the same query later can surface different papers.
• Criticism doesn't always converge. Every criticized step gets at most one revision. If the critic still rejects after that, the stage either persists its output flagged as criticism_approved: false (Repository Profiling, Literature Survey) or stops outright and enters a human decision point (Candidate Generation, Research Seed Expansion) — by design, not as a bug. At that point the critic's job is done and the call is yours: accept the rejection and stop, ask the team to drop just the rejected candidate and continue with the rest, or explicitly invoke criticism_override to proceed anyway. criticism_override isn't a way to silence the critic — its rejection and issues stay in the run's trace regardless; overriding only transfers final responsibility for the result to you. See docs/pipeline.md for exactly which stages use which rule and the full breakdown of this decision point.

Data sent to third parties

The literature-search MCP server sends your survey queries (derived from the repository's profile, not raw source code) to the OpenAlex, Semantic Scholar, and PubMed public APIs to retrieve papers. No part of PRISM writes to, or modifies, the repository it's studying — output is confined to <state_root>.

License

MIT