# Elegant Researcher Skill

> Orchestrate a complete AI/ML research project from a user's idea to a finished research artifact by coordinating bundled research skills: autoresearch, research-lookup, brainstorming-research-ideas, scientific-critical-thinking, scholar-evaluation, ml-training-recipes, academic-plotting, scientific-visualization, scientific-schematics, imagegen, scientific-writing, ml-paper-writing, systems-paper-writing, and user-interaction. Supports explicit modes, evidence levels, checkpointed user steering, micro-validation, full-experiment handoff, and final response contracts.

- Skill: `ttawdtt/elegant-researcher-skill` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add ttawdtt/elegant-researcher-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ttawdtt/elegant-researcher-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: ttawdtt (https://skillmd.com/u/ttawdtt)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ttawdtt/elegant-researcher-skill

---


# Elegant Researcher Skill

Use this skill when the user wants an end-to-end research project, not a one-off answer. This is a meta-skill: it coordinates other installed or bundled skills by stage.

## Operating Principles

1. Do not stop at a proposal. Produce a concrete research artifact.
2. Use explicit modes to decide how autonomous or user-driven the run should be.
3. Mark every result with an evidence level. Do not present toy or micro results as final evidence.
4. Use checkpoints only at major decision points. Routine decisions are made by the agent.
5. Keep a default path for every checkpoint so the project can continue when the user says "keep going."
6. Prefer a complete, honest cycle over an ambitious unfinished one.
7. Never hallucinate citations. Use verified URLs/DOIs/BibTeX or mark `[CITATION NEEDED]`.

## Modes

Select the mode from the user's wording. If unclear, default to `deep-cycle`.

| Mode | Use When | Completion Target |
|---|---|---|
| `quick-cycle` | User wants a fast first pass or feasibility check | Literature scan, hypotheses, micro-validation if feasible, short research note |
| `deep-cycle` | User asks for a detailed research project without specifying publication readiness | Full first cycle with gap analysis, hypothesis tree, protocols, micro-validation, figures, draft |
| `paper-ready` | User wants a polished paper-like artifact | Deep-cycle plus stronger writing, citation verification plan, reviewer-style self-evaluation |
| `theory-only` | Experiments are infeasible or the topic is conceptual | Literature synthesis, framework/theory, proposed experiments, research note or draft |
| `human-in-loop` | User wants to run full experiments or steer often | Checkpoints wait for user decisions and full-experiment results |

Mode inference:

- "just do it", "do not stop", "finish it yourself" -> `deep-cycle` with autonomous defaults.
- "make it publishable", "paper-ready", "submission" -> `paper-ready`.
- "survey", "theory", "framework", "no experiments" -> `theory-only`.
- "I will run experiments", "ask me at stages" -> `human-in-loop`.
- "quick", "initial", "feasibility" -> `quick-cycle`.

Record the selected mode in `research-state.yaml`.

## Evidence Levels

Attach one evidence level to every important claim, figure, and conclusion.

| Level | Meaning |
|---|---|
| `THEORY_ONLY` | Derived from theory, literature synthesis, or conceptual analysis only |
| `DESIGN_READY` | Protocol and code are prepared, but no run has been performed |
| `MICRO_VALIDATED` | Agent ran a small CPU-feasible toy or subset validation |
| `USER_FULL_RUN` | User supplied full-scale experiment results |
| `REPLICATED` | Result holds across multiple seeds, datasets, or independent checks |
| `PAPER_READY` | Evidence, citations, figures, and limitations are polished enough for a serious draft |

Do not upgrade evidence levels without new evidence.

## Research Workspace

Create this structure unless the project already has one:

```text
research-state.yaml
research-log.md
findings.md
hypothesis-tree.md
HANDOFF.md
literature/
experiments/
src/
data/
figures/
to_human/
paper/
```

## Resume and Stage Selection

When a workspace already exists, read `references/pipeline-state-machine.md` before choosing the next stage. Use it to decide where to resume, how checkpoints behave by mode, and whether evidence can be upgraded.

## Stage Workflow

### Stage 1: Bootstrap

Use `$autoresearch`.

Create the workspace and record:

- mode,
- research question,
- user motivation,
- hypotheses,
- success criteria,
- evidence-level policy,
- next actions.

If recurring continuation is useful, create a heartbeat. Keep notifications minimal. Delete obsolete heartbeats when the cycle completes or when they no longer help.

### Stage 2: Literature and Positioning

Use `$research-lookup`.

Search for:

- foundational papers,
- recent papers,
- adjacent methods,
- evaluation practices,
- counterarguments.

Save concise notes in `literature/`. Write:

- `literature/survey.md`
- `literature/gap-analysis.md`

The gap analysis must include:

1. method evolution timeline,
2. contradiction matrix,
3. implicit assumptions inventory,
4. concrete research gaps.

### Checkpoint 1: Literature Map Confirmation

Use `$user-interaction`.

Present the literature map and gap analysis. Default route:

- `quick-cycle`, `deep-cycle`, `paper-ready`, `theory-only`: continue with the recommended gap.
- `human-in-loop`: wait for user selection unless the user says to keep going.

### Stage 3: Idea Expansion

Use `$brainstorming-research-ideas`.

Generate candidate hypotheses using:

- abstraction ladder,
- tension/contradiction hunting,
- failure/boundary probing,
- simplicity test,
- cross-pollination.

Write `hypothesis-tree.md`. Each hypothesis must include:

- status,
- pitch,
- prediction,
- metric,
- feasibility,
- expected information gain,
- evidence level.

### Checkpoint 2: Hypothesis Selection

Use `$user-interaction`.

Present 2-5 candidate hypotheses with a recommended starting point. Default route:

- autonomous modes: proceed with the recommended hypothesis.
- `human-in-loop`: wait for user choice unless told to keep going.

### Stage 4: Critical Review

Use `$scientific-critical-thinking`.

Before experiments or theory claims, identify:

- confounders,
- weak proxies,
- invalid measurements,
- alternative explanations,
- falsification criteria,
- failure modes.

Write `critical_review.md` and revise the hypothesis tree.

### Stage 5: Experiment Design and Micro-Validation

Use `$ml-training-recipes` for ML/PyTorch experiments.

For each selected experiment:

1. Write `experiments/<slug>/protocol.md`.
2. Implement runnable code in `experiments/<slug>/code/`.
3. Write `experiments/<slug>/results/README.md` describing expected result files and formats.
4. Create `experiments/<slug>/analysis.md` as a template.
5. Update `hypothesis-tree.md` to `TESTING`.

If a git repository exists, commit protocols before results. If not, use timestamps in protocol files.

Run micro-validation when feasible:

- CPU-feasible,
- toy data or a tiny public subset,
- seconds to minutes,
- verifies code and trend direction,
- saves results in `experiments/<slug>/results/micro/`,
- saves figures in `experiments/<slug>/figures/micro/`,
- marks evidence as `MICRO_VALIDATED`.

Do not call micro-validation final benchmark evidence.

Write `HANDOFF.md` when full experiments are needed.

### Checkpoint 3: Experiment Ready

Use `$user-interaction`.

Present protocols, code locations, micro-validation results, and handoff instructions.

Default route depends on mode:

- `quick-cycle`: use micro-validation as proof-of-concept and proceed to writing.
- `deep-cycle`: use micro-validation as proof-of-concept unless user explicitly wants full runs.
- `paper-ready`: prepare handoff and note that full results are required for paper-ready empirical claims.
- `theory-only`: skip experiments and write proposed experiments.
- `human-in-loop`: wait for the user to run full experiments.

This avoids the old failure mode where defaulting to "user will run full experiments" silently stalls autonomous runs.

### Stage 6: Results Integration

Run this stage only when user or external full-scale results exist.

Use `$scientific-critical-thinking`.

For each result set:

1. Check data integrity.
2. Run post-experiment critical review.
3. Evaluate causal attribution.
4. Update evidence level to `USER_FULL_RUN` or `REPLICATED` when justified.
5. Fill `experiments/<slug>/analysis.md`.
6. Update `findings.md`, `research-log.md`, and `hypothesis-tree.md`.

If results are missing, do not invent them. Use `[RESULTS PENDING]` or explicitly frame the artifact as proof-of-concept or theory-only.

### Stage 7: Figures and Visual Synthesis

Use `$academic-plotting` for data-driven figures, `$scientific-visualization` for journal-style plots, `$scientific-schematics` for conceptual diagrams or graphical abstracts, and `$imagegen` for general-purpose generated images when visual assets are needed.

Generate:

- result plots when data exists,
- micro-validation plots when only micro data exists,
- literature/taxonomy/concept diagrams for theory-only work.

Every figure caption must include the evidence level.

### Stage 8: Writing

Use `$scientific-writing` for reports, `$ml-paper-writing` for ML/AI paper drafts, and `$systems-paper-writing` for systems venues such as OSDI, SOSP, ASPLOS, NSDI, and EuroSys.

Writing adapts to available evidence:

- full results: empirical paper/report,
- micro results only: proof-of-concept research note or preliminary draft,
- no experiments: theory/framework/survey draft with proposed experiments,
- paper-ready mode: include citation verification plan and reviewer-style limitations.

Required output:

- at least one user-facing research note or paper-style draft,
- clear statement of evidence levels,
- explicit limitations,
- next-cycle recommendation.

### Checkpoint 4: Draft Review

Use `$user-interaction`.

Present section status and evidence levels. Default route:

- autonomous modes: polish and finalize.
- `human-in-loop`: wait for user review.

### Stage 9: Completion

Use `$scholar-evaluation` before finalizing.

Write a short evaluation covering:

- problem formulation,
- literature positioning,
- methodology,
- evidence strength,
- novelty,
- limitations,
- publication readiness.

Then complete the cycle according to the selected mode.

### Checkpoint 5: Final Confirmation

Use `$user-interaction`.

Present the final artifact, output paths, figure count, reference status, evidence levels, limitations, and recommended next iteration.

Default route:

- autonomous modes: mark first cycle complete and stop obsolete heartbeats.
- `human-in-loop`: wait for user decision.

## Completion Standards

### First Cycle Complete

The project may conclude a first cycle only when all are true:

- `findings.md` contains a coherent story,
- `research-log.md` records key decisions,
- `hypothesis-tree.md` exists and is updated,
- `literature/survey.md` and `literature/gap-analysis.md` exist,
- at least one of these exists:
  - theory contribution,
  - experiment protocol and code,
  - micro-validation result,
  - user full-run result,
- a user-facing artifact exists,
- final response contract is satisfied.

### Paper-Ready Complete

The project may claim paper-ready status only when all are true:

- citations are verified or marked as unresolved,
- figure captions are complete,
- limitations are explicit,
- evidence levels are at least `USER_FULL_RUN` for empirical claims, or clearly theory-only,
- a reviewer-style self-evaluation exists,
- no `[RESULTS PENDING]` placeholders remain unless the artifact is intentionally a proposal.

## Final Response Contract

At the end of every cycle, the final user response must include:

1. Completion status and mode.
2. Key findings in 3-7 bullets.
3. Evidence level for each key finding.
4. User-facing output paths.
5. What is reliable vs. preliminary.
6. Main limitations.
7. Recommended next step.
8. Citation status: verified, URL-only, or placeholders.
9. Automation/heartbeat status if any was used.

Do not simply say "done."

## Default Skill Routing

```text
autoresearch                         workspace + state
research-lookup                      literature + gap synthesis
brainstorming-research-ideas         ideation + hypothesis tree
scientific-critical-thinking         pre/post review
ml-training-recipes                  experiment design + micro-validation
academic-plotting                    data figures
scientific-visualization             conceptual figures
scientific-schematics                 AI-generated schematics and graphical abstracts
imagegen                              general-purpose AI images and visual assets
scholar-evaluation                   quality scoring
scientific-writing                   reports
ml-paper-writing                     ML paper drafts
systems-paper-writing                 systems paper drafts and venue guidance
user-interaction                     checkpoint protocol
```

## Skill Availability and External Dependencies

Before using a skill that is not listed in `bundled_skills` in `skills-manifest.yaml`, check the manifest's `external_dependencies` section.

Use dependency status as follows:

- `installed`: the skill is available in the local agent skill directory. Use it when the task needs its specialized workflow.
- `missing`: the skill is referenced by bundled documentation but is not part of this bundle and is not installed under the expected local name. Use the manifest fallback instead.
- `optional`: use the skill if available; otherwise continue with the fallback without blocking the research cycle.

Never claim that an external dependency is bundled. Never invent outputs from a missing dependency. If an image, citation, template, or web lookup cannot be produced because its dependency or API key is unavailable, write a reproducible specification or mark the item as pending.

## Bundle Maintenance

When editing this bundle, run `python scripts/validate_bundle.py` before syncing or publishing. The validator checks manifest structure, bundled skill paths, SKILL.md frontmatter, route aliases, external dependency fallbacks, and duplicated scripts.

For intentional script duplication, see `references/script-duplication-audit.md`. Do not edit mirrored schematic-generation scripts independently.

## Local Skill Name Mapping

The upstream AI-Research-SKILLs repository often documents skills by category paths such as `08-distributed-training/fsdp/`. Local installations may flatten or rename those skills. Before deciding that a routed skill is missing, check `skills-manifest.yaml` and use the local skill name.

Common mappings:

| Upstream route or old name | Local skill name |
|---|---|
| `0-autoresearch-skill` | `autoresearch` |
| `02-tokenization/hf-tokenizers` | `huggingface-tokenizers` |
| `06-post-training/trl` | `trl-fine-tuning` |
| `04-mechanistic-interpretability/transformerlens` | `transformer-lens` |
| `08-distributed-training/fsdp` | `pytorch-fsdp2` |
| `11-evaluation/lm-eval-harness` | `lm-evaluation-harness` |
| `13-mlops/wandb` | `weights-and-biases` |
| `20-ml-paper-writing` | `ml-paper-writing` |
| `21-research-ideation` | `brainstorming-research-ideas` or `creative-thinking-for-research` |

If a routed skill is absent, use the closest installed alternative instead of blocking.

## Output Expectations

For a complete first cycle, produce:

- `findings.md`
- `research-log.md`
- `hypothesis-tree.md`
- `literature/survey.md`
- `literature/gap-analysis.md`
- experiment protocols and runnable code when applicable
- micro-validation results when feasible
- `HANDOFF.md` when full experiments require user compute
- figures when data or conceptual material exists
- a user-facing research note or paper draft