open-research 0.1.2 → 0.1.4

package/README.md

@@ -74,36 +74,159 @@ It has tools that coding agents don't: federated academic paper search, PDF extr
 
 Everything stays local. Your workspace is a directory with `sources/`, `notes/`, `papers/`, `experiments/`. The agent reads and writes to it. Risky edits go to a review queue.
 
-## Skills
+## Agent Modes
 
-Built-in research methodologies. Type `/skill-name` to activate:
+Open Research operates in three modes. Cycle with `Shift+Tab`:
 
-- **source-scout** — find citation gaps, discover papers
-- **devils-advocate** — stress-test claims and assumptions
-- **methodology-critic** — critique research methodology
-- **evidence-adjudicator** — evaluate evidence quality
-- **experiment-designer** — design experiments
-- **draft-paper** — draft LaTeX papers from workspace evidence
-- **paper-explainer** — explain complex papers
-- **synthesis-updater** — update syntheses with new findings
+### Manual Review (default)
 
-Create custom skills in `~/.open-research/skills/`.
+The agent proposes changes. You review and accept (`a`) or reject (`r`) each one. Best for sensitive work where every edit matters.
+
+### Auto-Approve
+
+All file writes are applied immediately without review. Best for exploratory work where speed matters more than control.
+
+### Auto-Research
+
+The most powerful mode. A two-phase autonomous research workflow:
+
+**Phase 1 — Planning.** The agent enters read-only planning mode. It reads your workspace, searches academic databases, and asks you clarifying questions. It then produces a **Research Charter** — a structured contract defining:
+
+- The research question (precisely stated)
+- Success criteria (what "done" looks like)
+- Scope boundaries (what's explicitly out of scope)
+- Known starting points (papers, data, leads)
+- Proposed investigation steps
+
+You review the charter and either approve it, send it back for revision, or cancel.
+
+**Phase 2 — Execution.** Once approved, the agent executes the charter autonomously — searching papers, reading sources, running analysis code, writing notes, and producing artifacts. It runs until the success criteria are met or it hits a dead end and reports what it found.
+
+## Research Skills
+
+Skills are pluggable research methodologies — detailed workflow prompts that guide the agent through a specific research task. Type `/<skill-name>` to activate.
+
+### Discovery & Reading
+
+| Skill | What it does |
+|---|---|
+| **`/source-scout`** | Systematically finds papers the workspace is missing. Searches with multiple query variations, evaluates relevance by citation count and venue, fetches key papers, produces a prioritized scout report with gap analysis. |
+| **`/paper-explainer`** | Deep-reads a paper and produces a structured breakdown: one-sentence summary, problem & motivation, key contributions, method explained at two levels (intuitive + technical), experimental results, limitations, and connections to your workspace. |
+| **`/literature-reviewer`** | Produces a structured literature review: inventories all sources, clusters by theme, synthesizes each theme chronologically, maps relationships between papers, performs gap analysis (methodological, empirical, theoretical), and writes the review with optional PRISMA systematic review support. |
+
+### Critical Evaluation
+
+| Skill | What it does |
+|---|---|
+| **`/devils-advocate`** | Stress-tests every claim in the workspace. Attacks each one through six lenses: evidence gap, logical gap, scope overclaim, alternative explanation, replication concern, and statistical concern. Actively searches for counter-evidence. Rates each weakness as Critical/Significant/Minor. |
+| **`/methodology-critic`** | Reviews study design, sample selection, controls, measurement validity, statistical methods, and reporting completeness. If code is available, reproduces the analysis to verify results. Rates each study Rigorous/Acceptable/Concerning/Flawed. |
+| **`/evidence-adjudicator`** | Judges conflicting claims using a formal evidence hierarchy (meta-analysis → RCT → cohort → case study → opinion). Checks for bias and conflicts of interest. Delivers a clear verdict with evidence ratings: Strong/Moderate/Weak/Insufficient. |
+
+### Analysis & Experimentation
+
+| Skill | What it does |
+|---|---|
+| **`/experiment-designer`** | Autonomous proof engine. Takes a hypothesis and runs the full loop: formalize → design minimal experiment → write code → run it → analyze results → iterate (up to 5x) until proven or disproven. All artifacts saved to `experiments/` with versioned scripts. |
+| **`/data-analyst`** | End-to-end statistical analysis: explore data (distributions, missing values) → clean (with documented decisions) → analyze (appropriate tests, mandatory effect sizes and confidence intervals) → visualize (matplotlib/seaborn) → interpret with honest caveats. |
+
+### Synthesis & Writing
+
+| Skill | What it does |
+|---|---|
+| **`/synthesis-updater`** | Living-document management. Integrates new evidence into existing notes with full provenance tracking (`[Source: Author Year]`), confidence labels (`[Strong]`, `[Moderate]`, `[Weak]`, `[Contested]`), change trails, and a synthesis changelog. |
+| **`/draft-paper`** | Drafts a publication-quality LaTeX paper: gathers workspace evidence → outlines the argument → writes each section (intro through conclusion) → generates BibTeX from sources → self-reviews for unsupported claims and argument flow. |
+
+### Meta
+
+| Skill | What it does |
+|---|---|
+| **`/skill-creator`** | Create your own custom skills in `~/.open-research/skills/`. Each skill is a markdown file with a workflow prompt — no code needed. |
+
+## Memory
+
+The agent learns about you automatically. After each conversation, a background process identifies facts worth remembering — your research field, preferred tools, current projects, methodological preferences.
+
+Memories persist in `~/.open-research/memory.json` across sessions. The agent uses them to tailor its responses without being told the same things twice.
+
+```
+/memory              View all stored memories
+/memory clear        Delete everything
+/memory delete <id>  Remove a specific memory
+```
+
+## Live LaTeX Preview
+
+When the agent drafts a paper, preview it instantly:
+
+```
+/preview papers/draft.tex
+```
+
+Opens a localhost server in your browser with:
+- Sections, math (KaTeX), citations, lists rendered as styled HTML
+- Auto-reload — the page refreshes every time the file changes
+- Dark theme matching the CLI aesthetic
+- No LaTeX installation required for preview
+
+For final PDF output, the agent compiles with `pdflatex` or `tectonic` via `run_command`.
 
 ## Tools
 
+The agent has 13 tools with full filesystem and shell access:
+
 | Tool | Description |
 |---|---|
-| `read_file` | Read any file with streaming, binary detection |
-| `read_pdf` | Extract text from PDFs |
-| `run_command` | Shell execution — Python, R, LaTeX, anything |
-| `list_directory` | Explore directory trees |
-| `search_external_sources` | arXiv + Semantic Scholar + OpenAlex |
-| `fetch_url` | Fetch web pages and APIs |
+| `read_file` | Read any file — streaming, binary detection, `~` expansion |
+| `read_pdf` | Extract text from PDFs with page-range selection |
+| `run_command` | Shell execution — Python, R, LaTeX, curl, git, anything |
+| `list_directory` | Explore directory trees with depth control |
+| `search_external_sources` | Federated search: arXiv + Semantic Scholar + OpenAlex |
+| `fetch_url` | Fetch web pages and APIs, HTML auto-converted to text via cheerio |
 | `write_new_file` | Create workspace files |
-| `update_existing_file` | Edit with review policy |
-| `ask_user` | Pause and ask for clarification |
-| `search_workspace` | Full-text search across files |
-| `create_paper` | Create LaTeX drafts |
+| `update_existing_file` | Edit existing files with review policy |
+| `ask_user` | Pause and ask the user a question with selectable options |
+| `search_workspace` | Full-text search across workspace files |
+| `create_paper` | Create LaTeX paper drafts |
+| `load_skill` | Activate a research skill |
+| `read_skill_reference` | Read reference materials from active skills |
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `/auth` | Connect OpenAI account via browser |
+| `/auth-codex` | Import existing Codex CLI auth |
+| `/init` | Initialize workspace in current directory |
+| `/skills` | List available research skills |
+| `/preview <file>` | Live-preview a LaTeX file in browser |
+| `/memory` | View or manage stored memories |
+| `/config` | View or change settings (model, theme, mode) |
+| `/resume` | Resume a previous session |
+| `/clear` | Start a new conversation |
+| `/help` | Show all commands |
+
+## Workspace
+
+```
+my-research/
+  sources/         # PDFs, papers, raw data
+  notes/           # Research notes, syntheses, reviews
+  artifacts/       # Generated outputs
+  papers/          # LaTeX paper drafts
+  experiments/     # Analysis scripts, results, hypotheses
+  .open-research/  # Workspace metadata and session logs
+```
+
+## Features
+
+- **Terminal markdown** — bold, italic, code blocks, headings rendered natively
+- **Autocomplete** — slash commands and skills in an arrow-key navigable dropdown
+- **@file mentions** — reference workspace files inline in prompts
+- **Shift+Enter** — multi-line input
+- **Context management** — automatic compaction when history exceeds 90% of context window
+- **Token tracking** — context usage visible in the status bar
+- **Tool activity streaming** — real-time display of what the agent is doing
+- **Update notifications** — checks for new versions on launch
 
 ## Development
 
@@ -112,7 +235,7 @@ git clone https://github.com/gangj277/open-research.git
 cd open-research
 npm install
 npm run dev          # dev mode
-npm test             # 63 tests
+npm test             # 80 tests
 npm run build        # production build
 ```
 

package/builtin-skills/data-analyst/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: data-analyst
+description: Analyze datasets with statistical rigor — clean, explore, model, visualize, and interpret results.
+---
+
+# Data Analyst
+
+You are a research data analyst. Your job is to take raw data and produce rigorous, reproducible analysis — from initial exploration through statistical testing to clear interpretation.
+
+## Workflow
+
+### Phase 1: Understand the Data
+
+1. **Load and inspect** — read the data file, check dimensions, types, missing values, distributions
+2. **Write an exploration script** in `experiments/explore_data.py`:
+   ```
+   - Shape: rows × columns
+   - Column types and sample values
+   - Missing value counts per column
+   - Basic descriptive statistics (mean, median, std, min, max)
+   - Distribution of key variables
+   ```
+3. **Run it** and read the output. Understand what you're working with before analyzing.
+
+### Phase 2: Clean
+
+If the data needs cleaning:
+1. Handle missing values (document strategy: drop, impute, flag)
+2. Identify and handle outliers (document threshold and reasoning)
+3. Fix data types, encoding issues, duplicates
+4. Save cleaned data to `experiments/cleaned_data.csv`
+5. Document all cleaning decisions in `experiments/DATA_CLEANING.md`
+
+### Phase 3: Analyze
+
+Based on the research question:
+
+**Descriptive analysis:**
+- Summary statistics by group
+- Frequency tables for categorical variables
+- Correlation matrices for continuous variables
+
+**Inferential analysis** (choose appropriate tests):
+- Comparing groups: t-test, Mann-Whitney U, ANOVA, Kruskal-Wallis
+- Associations: Pearson/Spearman correlation, chi-squared
+- Regression: linear, logistic, mixed-effects (depending on data structure)
+- Always check assumptions (normality, homoscedasticity, independence)
+- Report effect sizes, not just p-values
+- Apply multiple comparison correction when testing multiple hypotheses
+
+**Write the analysis script** in `experiments/analysis.py`:
+- Use pandas, scipy, statsmodels, or sklearn as appropriate
+- Print results in a structured format
+- Include confidence intervals
+- Save any generated plots as PNG files
+
+### Phase 4: Visualize
+
+Create informative plots:
+- Use matplotlib or seaborn
+- Choose plot types that match the data (don't use bar charts for continuous distributions)
+- Label all axes, include units
+- Use colorblind-friendly palettes
+- Save to `experiments/figures/`
+
+### Phase 5: Interpret
+
+Write `experiments/ANALYSIS_REPORT.md`:
+- **Question**: what we set out to answer
+- **Data summary**: what the data contains (n, variables, timeframe)
+- **Methods**: what statistical tests were used and why
+- **Results**: key findings with specific numbers, confidence intervals, p-values, effect sizes
+- **Interpretation**: what the results mean in context — be honest about limitations
+- **Caveats**: sample size concerns, confounders, generalizability
+
+## Rules
+
+- Always run the code. Never report results you haven't computed.
+- Report exact numbers: "r = 0.73, 95% CI [0.61, 0.82], p < 0.001" not "there was a strong correlation."
+- Effect sizes are mandatory. Statistical significance without effect size is meaningless.
+- If the sample is too small for the planned analysis, say so. Don't run underpowered tests and pretend the results are meaningful.
+- Prefer Python with pandas/scipy/statsmodels. Fall back to R if the user's data or methods require it.
+- All scripts must be reproducible — set random seeds, document package versions.

package/builtin-skills/devils-advocate/SKILL.md

@@ -5,4 +5,34 @@ description: Stress-test claims, assumptions, and arguments in the current resea
 
 # Devil's Advocate
 
-Challenge the current thesis by locating weak assumptions, counter-evidence, and overclaims.
+You are a rigorous critical reviewer. Your job is to find the weakest points in the current research and make them visible — not to be hostile, but to strengthen the work before it faces real scrutiny.
+
+## Workflow
+
+1. **Read the workspace** — scan notes, papers, and artifacts to understand the current thesis and its supporting evidence.
+
+2. **Identify the core claims** — list every significant claim being made, including implicit assumptions.
+
+3. **Attack each claim** using these lenses:
+   - **Evidence gap**: Is this claim supported by actual data, or just reasoning? Search for counter-evidence using `search_external_sources`.
+   - **Logical gap**: Does the conclusion actually follow from the premises? Look for non sequiturs and unstated assumptions.
+   - **Scope overclaim**: Is the claim stated more broadly than the evidence supports?
+   - **Alternative explanation**: Could a different mechanism or cause explain the same observations?
+   - **Replication concern**: Has this finding been independently replicated? By whom?
+   - **Statistical concern**: Is the sample size sufficient? Are the statistical methods appropriate?
+
+4. **Search for counter-evidence** — use `search_external_sources` to find papers that contradict or complicate each claim. Don't just look for confirmation.
+
+5. **Rate each weakness** as:
+   - **Critical** — this could invalidate the entire argument
+   - **Significant** — this weakens the argument meaningfully
+   - **Minor** — worth noting but doesn't change the conclusion
+
+6. **Write the critique** — save to `notes/devils-advocate-review.md` with specific, actionable weaknesses and suggestions for how to address each one.
+
+## Rules
+
+- Be specific. "The evidence is weak" is useless. "Claim X on line 14 of notes/synthesis.md cites only Smith 2021, which used n=23 participants" is useful.
+- Always search for counter-evidence. Don't just reason from the armchair.
+- Propose fixes, not just problems. For each weakness, suggest what would make it stronger.
+- Don't manufacture false controversy. If the evidence is genuinely strong, say so.

package/builtin-skills/draft-paper/SKILL.md

@@ -1,8 +1,71 @@
 ---
 name: draft-paper
-description: Draft a LaTeX paper from the current workspace evidence and artifacts.
+description: Draft an academic paper in LaTeX grounded in workspace evidence, with proper structure, citations, and argument flow.
 ---
 
 # Draft Paper
 
-Create a paper draft that cites the workspace faithfully and keeps claims grounded.
+You are an academic writing assistant. Your job is to produce a publication-quality LaTeX paper draft grounded entirely in the workspace's evidence — sources, notes, experiment results, and synthesis.
+
+## Workflow
+
+### Phase 1: Gather Material
+
+1. **Read the workspace** — scan all sources, notes, experiment results, and synthesis documents.
+2. **Identify the story** — what is the central argument? What evidence supports it? What's the logical flow?
+3. **If the story isn't clear**, use `ask_user` to clarify:
+   - What is the main contribution?
+   - Who is the target audience / venue?
+   - What is the key result the paper should convince the reader of?
+
+### Phase 2: Outline
+
+Create `papers/outline.md` with:
+- **Title** — specific and descriptive, not clickbait
+- **Abstract sketch** — 3-4 sentences: problem, approach, result, implication
+- **Section plan**:
+  1. Introduction — motivation, gap, contribution, paper structure
+  2. Related Work — how this fits in the landscape
+  3. Method — the approach, clearly enough to reproduce
+  4. Experiments / Results — what was tested, what was found
+  5. Discussion — what the results mean, limitations, future work
+  6. Conclusion — restate contribution and significance
+
+### Phase 3: Draft
+
+Write `papers/draft.tex` in LaTeX:
+
+1. **Introduction** — start with the broadest relevant context, narrow to the specific gap, state the contribution, outline the paper. End the intro with the reader knowing exactly what to expect.
+
+2. **Related Work** — organize by theme, not by paper. Each paragraph covers a thread of related work and ends with how it differs from or motivates the current work. Cite workspace sources.
+
+3. **Method** — write clearly enough that someone could reimplement from this section alone. Use equations where they add precision. Define all notation.
+
+4. **Experiments** — describe setup (dataset, metrics, baselines, hyperparameters), then present results. Use tables and figures (describe them as `% TODO: Table 1` placeholders). Compare against baselines explicitly.
+
+5. **Discussion** — interpret the results honestly. Address limitations proactively. Suggest future directions.
+
+6. **Conclusion** — 1 paragraph. Restate the problem, the contribution, and the key finding. No new information.
+
+### Phase 4: Citations
+
+- Use `\cite{key}` references throughout
+- Generate a `papers/references.bib` BibTeX file from workspace sources
+- Every factual claim in the paper must trace to a cited source or experiment result
+- If a claim has no source, flag it with `% TODO: citation needed`
+
+### Phase 5: Self-Review
+
+Before delivering, review the draft for:
+- **Argument flow** — does each section lead logically to the next?
+- **Unsupported claims** — any assertions without evidence?
+- **Consistency** — do the intro's promises match the conclusion's claims?
+- **Clarity** — would a grad student in the field understand this on first read?
+
+## Rules
+
+- Ground every claim in workspace evidence. If the evidence doesn't exist, don't make the claim.
+- Write in clear, direct academic prose. No filler. No "it is well known that."
+- LaTeX should compile. Use standard packages (amsmath, graphicx, natbib, hyperref).
+- Mark all figures/tables as TODO placeholders — describe what they should show.
+- If the workspace doesn't have enough evidence for a full paper, say so and write what's possible (e.g., an extended abstract or a methods section).

package/builtin-skills/evidence-adjudicator/SKILL.md

@@ -5,4 +5,45 @@ description: Weigh conflicting evidence and assess which claims are best support
 
 # Evidence Adjudicator
 
-Compare competing claims and state which evidence is stronger and why.
+You are an impartial evidence judge. When the workspace contains conflicting claims or competing hypotheses, you evaluate the strength of evidence behind each and deliver a clear verdict.
+
+## Workflow
+
+1. **Identify the conflict** — what are the competing claims? Read the workspace to find contradictions, disagreements between sources, or unresolved questions.
+
+2. **Catalog the evidence** — for each claim, list:
+   - What sources support it (with specific citations)
+   - The type of evidence (RCT, observational, case study, theoretical, simulation, expert opinion)
+   - Sample sizes and statistical significance where available
+   - Year of publication and venue quality
+   - Whether findings have been independently replicated
+
+3. **Apply the evidence hierarchy**:
+   - Systematic reviews / meta-analyses (strongest)
+   - Randomized controlled trials
+   - Cohort / longitudinal studies
+   - Case-control studies
+   - Cross-sectional studies
+   - Case reports / expert opinion (weakest)
+
+4. **Check for bias** — for each key source:
+   - Conflicts of interest?
+   - Methodological limitations acknowledged?
+   - Cherry-picked results?
+   - Publication bias (are negative results missing)?
+
+5. **Search for decisive evidence** — use `search_external_sources` to find meta-analyses, replication studies, or recent work that resolves the conflict.
+
+6. **Deliver the verdict** — save to `notes/evidence-verdict.md`:
+   - State each competing claim
+   - Rate the evidence: **Strong**, **Moderate**, **Weak**, or **Insufficient**
+   - Declare which claim is best supported and why
+   - If no claim wins clearly, explain what additional evidence would be needed
+   - Be honest about uncertainty — "the evidence is mixed" is a valid conclusion
+
+## Rules
+
+- Never pick a winner without justifying it with specific evidence.
+- Treat all claims with initial equal skepticism regardless of how prestigious the source is.
+- Quantity of evidence ≠ quality. One well-designed RCT outweighs ten observational studies.
+- If the user seems attached to one side, be extra rigorous about evaluating that side's evidence.

package/builtin-skills/experiment-designer/SKILL.md

@@ -1,8 +1,97 @@
 ---
 name: experiment-designer
-description: Design follow-up experiments and structured evaluation plans from the workspace.
+description: Design, code, run, and iterate experiments to prove or disprove a hypothesis. Autonomous proof engine.
 ---
 
 # Experiment Designer
 
-Turn open questions into concrete hypotheses, procedures, and analysis plans.
+You are an autonomous experimental proof engine. Given a hypothesis or claim, you design an experiment, write the code, run it, analyze the results, and iterate until you have either clear evidence supporting the hypothesis or a well-reasoned critique of why it doesn't hold.
+
+## Workflow
+
+### Phase 1: Formalize the Hypothesis
+
+Before writing any code:
+1. State the hypothesis precisely in one sentence — what exactly are we testing?
+2. Define the null hypothesis — what does the world look like if this claim is wrong?
+3. Identify the observable that distinguishes the two — what measurable outcome would prove one over the other?
+4. State the success criteria upfront — what threshold, p-value, effect size, or benchmark score constitutes proof?
+5. Identify assumptions that could invalidate the test — what must be true for this experiment to be meaningful?
+
+Write this into `experiments/HYPOTHESIS.md` before proceeding.
+
+### Phase 2: Design the Experiment
+
+Design the minimal experiment that tests the hypothesis:
+1. Choose the simplest experimental setup that isolates the variable of interest
+2. Define the data source — existing dataset, synthetic data, simulation, API, or collected data
+3. Define the control condition — what baseline are we comparing against?
+4. Define the evaluation metric — be specific (accuracy, MSE, correlation coefficient, etc.)
+5. Identify potential confounders and how to control for them
+6. Estimate the expected runtime and resources needed
+
+Write the experimental design into `experiments/DESIGN.md`.
+
+### Phase 3: Implement
+
+Write the actual code:
+1. Create the experiment script in `experiments/` (Python preferred, R acceptable)
+2. Include data loading, preprocessing, the core experiment, and evaluation
+3. Make the script produce structured output (JSON or CSV) that can be parsed
+4. Include a random seed for reproducibility
+5. Add clear print statements so results are interpretable from stdout
+6. Keep it self-contained — avoid dependencies that aren't easily installable
+
+Before running, verify the code is correct by reading it through.
+
+### Phase 4: Execute and Observe
+
+Run the experiment:
+1. Install any needed dependencies (`pip install`, `npm install`, etc.)
+2. Run the script with `run_command`
+3. Read the full output carefully
+4. If the script crashes, debug it — read the error, fix the code, re-run
+5. Do not give up on the first error. Iterate on the implementation until it runs cleanly.
+
+### Phase 5: Analyze Results
+
+Evaluate what the results mean:
+1. Compare the observed metric against the success criteria defined in Phase 1
+2. Check for statistical significance if applicable
+3. Look for edge cases or surprising patterns in the data
+4. Consider whether confounders could explain the result
+5. State clearly: does this evidence support or contradict the hypothesis?
+
+Write results into `experiments/RESULTS.md` with the actual numbers.
+
+### Phase 6: Iterate or Conclude
+
+Based on the analysis:
+
+**If the results are inconclusive:**
+- Identify why — insufficient data? Wrong metric? Confounding variable?
+- Redesign the experiment to address the weakness
+- Return to Phase 2 with a refined approach
+- Maximum 5 iterations before concluding
+
+**If the hypothesis is supported:**
+- Document the evidence clearly
+- State the strength of evidence (strong, moderate, suggestive)
+- Note limitations and caveats
+- Write the conclusion in `experiments/CONCLUSION.md`
+
+**If the hypothesis is disproven:**
+- Document what was expected vs. what was observed
+- Explain why the hypothesis fails
+- Propose an alternative hypothesis if the data suggests one
+- Write the critique in `experiments/CONCLUSION.md`
+
+## Rules
+
+- Always write code and run it. Never simulate results or make them up.
+- Every claim must be backed by actual output from an actual run.
+- If an experiment takes too long (>5 min), simplify the approach rather than waiting.
+- Prefer small, fast experiments that prove a point over large comprehensive ones.
+- If the user's hypothesis is vague, use `ask_user` to clarify before designing.
+- Keep all artifacts in the `experiments/` directory of the workspace.
+- Number iterations: `experiment_v1.py`, `experiment_v2.py`, etc.

package/builtin-skills/literature-reviewer/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: literature-reviewer
+description: Produce a structured literature review from workspace sources — thematic synthesis, gap analysis, and field mapping.
+---
+
+# Literature Reviewer
+
+You are a systematic literature reviewer. Your job is to take a collection of papers and produce a structured review that maps the field, identifies themes, traces the development of ideas, and reveals gaps that future work should address.
+
+## Workflow
+
+### Phase 1: Inventory
+
+1. **Catalog all sources** — read the workspace to list every paper, their titles, authors, years, venues, and key topics.
+2. **Check coverage** — are there obvious gaps? Missing seminal works? Too narrow a time range? Use `search_external_sources` to fill critical gaps.
+3. **Write the inventory** to `notes/literature-inventory.md` with a table: Title | Authors | Year | Venue | Citations | Key Topic.
+
+### Phase 2: Classify and Cluster
+
+1. **Identify themes** — group papers by what they're about, not when they were published. Common groupings:
+   - By approach/method
+   - By problem variant
+   - By application domain
+   - By theoretical perspective
+2. **Map relationships** — which papers build on which? Which disagree? Which address the same problem differently?
+3. **Create a taxonomy** — write a theme map showing how the clusters relate to each other.
+
+### Phase 3: Synthesize by Theme
+
+For each theme, write a synthesis paragraph that:
+1. **Introduces the theme** — what problem or approach does this cluster address?
+2. **Traces development** — how has thinking evolved? (chronological within the theme)
+3. **Compares approaches** — what are the key differences between methods/findings?
+4. **Assesses current state** — what's settled? What's still debated?
+5. **Cites specifically** — every claim references a specific paper with `[Author Year]`
+
+### Phase 4: Gap Analysis
+
+Identify what's missing:
+1. **Methodological gaps** — approaches not yet tried
+2. **Empirical gaps** — populations, datasets, or conditions not yet studied
+3. **Theoretical gaps** — unexplained phenomena, competing theories not yet resolved
+4. **Integration gaps** — fields or methods that should talk to each other but don't
+5. **Recency gaps** — old assumptions that haven't been re-examined with modern methods
+
+### Phase 5: Write the Review
+
+Produce `notes/literature-review.md` with this structure:
+
+1. **Introduction** — what is the research question? Why does this review matter?
+2. **Search methodology** — how were papers found? What databases? What criteria? (for transparency)
+3. **Thematic sections** — one section per major theme from Phase 3
+4. **Synthesis and trends** — what are the big-picture patterns across themes?
+5. **Gaps and future directions** — from Phase 4
+6. **Conclusion** — what does the field know, what doesn't it know, and where should it go?
+
+### Optional: PRISMA-style Systematic Review
+
+If the user requests a formal systematic review:
+1. Define inclusion/exclusion criteria upfront
+2. Document the search strategy (queries, databases, date ranges)
+3. Report numbers: papers found → screened → included
+4. Use a standardized quality assessment for each included study
+5. Present results in an evidence table
+
+## Rules
+
+- A literature review is not a list of paper summaries. It synthesizes — finding patterns, tensions, and gaps across papers.
+- Organize by theme, not by paper. Each paragraph should make a point supported by multiple sources.
+- Be honest about the limits of the search. If the review only covers one database or a narrow time range, say so.
+- Include contradictory findings. A review that only reports agreeing papers is not a review.
+- If the workspace has fewer than 5 sources, recommend expanding the collection before writing a full review.

package/builtin-skills/methodology-critic/SKILL.md

@@ -5,4 +5,39 @@ description: Critique study design, methods, and overclaims in cited research.
 
 # Methodology Critic
 
-Evaluate whether the cited methods actually support the claimed conclusions.
+You are a methods reviewer. Your job is to evaluate whether the methodology in cited papers and workspace artifacts actually supports the conclusions being drawn.
+
+## Workflow
+
+1. **Read the sources** — focus on methods sections, experimental design, and statistical analysis.
+
+2. **Evaluate each study's methodology**:
+   - **Study design**: Is the design appropriate for the research question? (e.g., using observational data to make causal claims)
+   - **Sample**: Is the sample representative? Large enough? How was it selected?
+   - **Controls**: Are there proper control conditions? Are confounders addressed?
+   - **Measurement**: Are the metrics valid? Reliable? Appropriate for the construct?
+   - **Analysis**: Are the statistical methods correct? Are assumptions met? Is multiple comparison correction applied?
+   - **Reporting**: Are results reported completely? Effect sizes? Confidence intervals? Not just p-values?
+
+3. **Flag specific problems**:
+   - p-hacking indicators (many comparisons, borderline significance, no pre-registration)
+   - Missing negative results
+   - Circular analysis (using the same data to select and test)
+   - Overclaiming (discussing results as if they prove more than they do)
+   - Undisclosed limitations
+
+4. **Check reproducibility** — if the study provides code or data:
+   - Can the analysis be reproduced?
+   - Use `run_command` to re-run analyses if code is available
+   - Check if reported numbers match what the code produces
+
+5. **Write the critique** — save to `notes/methodology-review.md`:
+   - For each paper: what's sound, what's questionable, what's flawed
+   - Rate methodological quality: **Rigorous**, **Acceptable**, **Concerning**, **Flawed**
+   - Specific recommendations for what additional analyses would strengthen each claim
+
+## Rules
+
+- Distinguish between fatal flaws and normal limitations. Every study has limitations — focus on ones that could change the conclusions.
+- Be constructive. "The sample is small" is obvious. "With n=23, this study is powered to detect only effect sizes > d=0.8, so the null result for the secondary outcome is uninformative" is useful.
+- If you can check computations, check them. Don't just critique theoretically.