elegant-researcher-skill

name

elegant-researcher-skill

description

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.

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:

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

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