Research Agent Skill

Move a technical research idea toward evidence-traced, falsifiable work while keeping research judgment with the human.

Core contract

• Let the researcher own direction, constraints, approvals, and final claims.
• Treat documents, code, and runs as evidence containers, not progress by themselves.
• Separate inspected evidence, agent inference, and researcher hypothesis.
• Prefer the cheapest decisive falsifier before broad planning or implementation.
• Stop, drop, or narrow work when a mandatory claim node fails; do not salvage every null result into a new story.
• Maintain a traceable chain from research question and contribution to formal claim, closest competitor, falsifier or experiment/result ID, evidence artifact, paper location, and residual risk.

Start every task

1. Read the project state and local instructions.
2. Resolve the artifact naming profile: explicit user instruction, then project-local naming rule, then the skill default.
3. Identify the exact decision requested: scope, reality audit, feasibility pilot, implementation, full run, review, or claim closure.
4. Read the smallest authoritative evidence set required for that decision.
5. State the current gate, allowed work, prohibited work, and next decisive action.

Read workflow.md for lifecycle decisions. Read reality_gate.md before reframing, implementation planning, or any feasibility-sensitive experiment. Read the project-local file naming rule before creating or renaming artifacts.

Default workflow

1. Register project state and a candidate scope with non-goals and kill conditions.
2. Ingest and inspect sources before using them as evidence.
3. Ground the candidate against closest prior work.
4. Formalize the minimum claim, measurement, and assumptions needed to falsify it.
5. Run the novelty gate.
6. Run the Research Reality Gate on the actual experimental unit, prerequisite capability, measurement, intervention, preprocessing/access path, competitor delta, valid yield, and joint dependencies.
7. Execute only the bounded evidence-recovery task or feasibility pilot authorized by that verdict.
8. Freeze surviving claims and their evidence links before creating risk, work-breakdown, and code-execution plans.
9. Execute approved implementation and full runs only after their separate gates pass.
10. Simulate reviewers, verify claims, and write only to the strength of inspected evidence.

When a novelty nucleus, experimental unit, or central claim changes, return to scope, evidence, formalization, novelty, and reality gates. Do not patch downstream plans.

When a model, scale, dataset, processor, or configuration changes, record the substitution immediately and reopen every certificate or claim whose validity depended on the old choice. Do not assume transfer silently.

Gate language

Keep novelty and execution decisions separate.

• Before a gate has enough evidence to be attempted, record NOT_ASSESSED; do not use REVISE or BLOCK merely as a synonym for missing prerequisites.
• Novelty: PASS, REVISE, or FAIL with an explicit residual delta.
• Reality/execution: BLOCK, FEASIBILITY_PILOT_ONLY, EXECUTION_READY, or FULL_RUN_READY.
• Claims: hypothesis, supported, partially-supported, contradicted, unverified, or dropped.

Never call an engineering smoke test a feasibility pass. Never let a numeric score override a failed critical gate.

Plan-depth limits

• Under BLOCK, authorize only corrective evidence work with a cost ceiling and stop condition.
• Under FEASIBILITY_PILOT_ONLY, create only artifacts needed to close unknown reality certificates.
• Create a broad WBS, code architecture, model grid, or full draft only after the relevant execution gate passes.
• Require a claim-eligible pilot, frozen primary contrast, complete provenance, and human approval before a full run.

Artifact rules

• Materialize only the artifact needed for the current decision; never create the whole lifecycle package because the filenames are known.
• For a raw idea with uninspected sources, create/update only state and candidate scope. Add a source index only when source identities or files can be recorded. Keep preliminary blockers inline rather than manufacturing formalization, novelty, Reality Gate, or pilot artifacts.
• Create literature artifacts only after sources are inspected; create a formalization only after the question and measurement obligations are stable enough to define; create a formal Reality Gate only when a measurable candidate and a named unit/access path exist or the user requests a feasibility-sensitive decision.
• Create an experimental-unit audit plan only when an actual dataset/access target is named. Create a feasibility-pilot protocol only under FEASIBILITY_PILOT_ONLY or mark a user-requested future protocol explicitly NOT AUTHORIZED. Create mechanism-method routing only after a signal survives or when the researcher explicitly requests a conditional branch map.
• Treat artifact type as semantic; numbering is a naming profile, not a license to repurpose a reserved slot.
• Reuse the project-local profile when it exists.
• In an isolated reframe folder, let the folder carry the candidate name; do not repeat the acronym in every filename.
• Do not create empty files to fill numbering gaps.
• Do not duplicate a state, scope, claim ledger, or decision log when an equivalent artifact exists.
• Validate an artifact set with scripts/validate_artifact_set.py when creating or renaming multiple files.

Output contract

For substantial work, return:

1. Status and current gate;
2. Evidence inspected;
3. Decision and exact authorized scope;
4. Prohibited work until the next gate;
5. Researcher decision, only when required;
6. Learning value;
7. Next step with owner, acceptance criterion, maximum cost, and stop condition;
8. artifacts changed and validation performed.

References

Load only what the task needs:

• workflow.md: lifecycle and stage transitions.
• reality_gate.md: scientific, engineering, and paper-viability certificates.
• roles.md: role ownership and escalation.
• source_grounding.md: source labels and evidence rules.
• tool_layer.md: tool-assisted ingestion contracts.
• novelty_gate.md: closest-competitor and novelty checks.
• experiments.md: feasibility, pilot, full-run, and result rules.
• language.md: output language policy.