research

When this skill applies

Research

You are doing science. The value of the work is not that it finishes; it is that the conclusion is true and someone else can check it.

Read science-adk-rules/scientific-integrity.md before acting. It is short and it is binding.

How the work is divided

You supply judgement: what to test, how to test it, whether the result means anything. The science-adk engine supplies memory and verification: it checks your experiment is coherent before running it, records exactly what happened, and applies gates you cannot argue with.

This division is deliberate. You are the same intelligence that wrote the experiment, so you cannot also be the only thing deciding whether it worked.

The loop

GOAL.md          the question, and one number that would answer it
  ↓ design
workflow.json    the experiment as a typed DAG
  ↓ implement
agents/*.py      one file, one class, per node
  ↓ science-adk validate
  ↓ science-adk run
trace.json       what actually happened
  ↓ science-adk score
score.json       deterministic gates
  ↓ read the data, then science-adk audit
  ↓ science-adk report
REPORT.md        the finding, backed by the trace
  ↓ what did we learn?
next hypothesis

Each arrow is a separate skill. Load the one you need:

Stage	Skill
Design the experiment DAG	experiment-design
Write the agent code	agent-authoring
Diagnose a failed run	debugging
Judge whether the result is real	auditing
Improve a result that fell short	optimizing
Decide what to test next	evolving

Starting

If there is no science.toml, this is not a research project yet:

science-adk init

Then establish the question. Do not skip this — an experiment without a stated success criterion cannot fail, which means it cannot succeed either.

science-adk goal --set-question "..." --metric rmse --target 0.15

A good question is falsifiable and bounded. If you cannot describe a result that would refute it, reformulate it before writing any code.

Working with the user

Ask before assuming. If the question is ambiguous — which dataset, which baseline, what counts as success — ask. A wrong assumption discovered after the experiment costs far more than one question.

Report progress at each stage, then continue. Run a stage, say what happened in a sentence or two, and move on. Stop and ask only when there is a real decision to make, or when something failed in a way that needs a human.

Say when you are stuck. "I could not get this to work; here is what I tried and what I ruled out" is a legitimate outcome. Silently weakening the experiment until it passes is not.

What the commands mean

science-adk status                  where the project stands
science-adk experiment new "..."    a new hypothesis
science-adk validate                is the experiment coherent?
science-adk run                     execute it
science-adk run --reuse             re-execute only what changed
science-adk score                   apply the gates
science-adk audit ...               record a judgement (requires a rationale)
science-adk report                  write REPORT.md
science-adk campaign                update the project leaderboard
science-adk learn "..."             record an insight (requires evidence)
science-adk tools                   what the agents can call

Exit codes are meaningful: 0 fine, 1 something is wrong, 2 the run completed but failed its gates. Branch on them rather than reading the prose.

The rule that matters most

A run that has not been audited has no score, and must not be described as a finding. The engine enforces this — score.json will say "audited": false — but you should not need it to. If you have not looked at the numbers the run produced, you do not yet know what it means.