Ds Baseline

---
name: ds-baseline
description: Use when a quest needs to attach, import, reproduce, repair, verify, compare, or publish a baseline and its metrics.
skill_role: stage
license: MIT
metadata:
  author: ResearAI/DeepScientist
  version: "1.0.0"
---

# Baseline

This skill establishes the reference system the quest will compare against.
The target is one trustworthy baseline line, not an endless reproduction diary.

## Interaction discipline

- Follow the shared interaction contract injected by the system prompt.
- Keep ordinary setup and debugging updates concise.
- Use richer milestone updates only when the baseline becomes trusted, caveated, blocked, waived, or route-changing.
- Hard execution rule: every terminal command in this stage must go through `bash_exec`; do not use any other terminal path for setup, reproduction, monitoring, verification, Git, Python, package-manager, or file-inspection commands.
- Prefer `bash_exec` for setup, reproduction, monitoring, and verification commands so the baseline line stays durable and auditable.

## Tool discipline

- **Do not use native `shell_command` / `command_execution` in this skill.**
- **All shell, CLI, Python, bash, node, git, npm, uv, and environment work must go through `bash_exec(...)`.**
- **For git work inside the current quest repository or worktree, prefer `artifact.git(...)` before raw shell git commands.**
- **If a generic git smoke test is needed outside the quest repo, use `bash_exec(...)` in an isolated scratch repository.**

## Non-negotiable rules

- no fabricated metrics, logs, run status, or success claims
- do not skip baseline steps or silently simplify the route when that would change trust or comparability
- do not claim a baseline is ready before verification is complete
- do not infer missing commands, scripts, or parameters when the uncertainty could change the result
- any unavoidable guess must be written down explicitly with expected impact
- use web search for discovering papers or repos, but use `artifact.arxiv(paper_id=..., full_text=False)` for actually reading a source arXiv paper when it exists
- set `full_text=True` only when the short form is insufficient
- for Python baselines, environment setup should be standardized around `uv`

## Stage purpose

The baseline stage should produce a usable reference point through one of four routes:

1. attach an existing reusable baseline
2. import a reusable baseline package
3. reproduce a baseline from source
4. repair a broken or stale baseline

Keep the classic control flow:

1. analysis
2. setup
3. execution
4. verification

These are control gates, not paperwork walls.

## Quick workflow

1. Read the source paper and source repo first, or record exactly what is missing and why.
2. Choose the lightest trustworthy route: attach, import, reproduce, or repair.
3. Start with the fast path whenever the current baseline object, command path, and acceptance target are already clear enough to validate cheaply.
4. Before substantial baseline setup, code edits, or a real baseline run, create `PLAN.md` and `CHECKLIST.md`; short-form files are enough for simple fast-path work.
5. Keep one dominant phase visible: analysis -> setup -> execution -> verification.
6. Prefer one clean implementation pass, one smoke test, and then one normal baseline run.
7. Retry only when smoke, verification, or runtime evidence shows a concrete failure or incompatibility.
8. Close the stage by confirming or waiving the gate, then hand off with a concise `1-2` sentence summary of trust status and next anchor.

## Fast-path first

Default to the lightest baseline path that can still establish a trustworthy comparison.
Default to a fast path when it can establish trust with less work.

Fast path is the default when any of the following is true:

- `requested_baseline_ref` or `confirmed_baseline_ref` already points to the active baseline object
- the route is clearly `attach` or `import`
- the repo entrypoint, dataset or split, and metric contract are already concrete enough to validate cheaply
- reproduction requires no meaningful code changes and the main uncertainty is only whether the command still runs

Fast path means:

- do not restart broad baseline discovery by default
- do not front-load a full codebase audit when the entrypoint is already concrete
- use a minimal `PLAN.md`, a minimal `CHECKLIST.md`, one bounded smoke test when needed, and then one real validation or run
- default to reuse-and-verify when runtime already attached a concrete baseline

Escalate from fast path to fuller audit only when:

- the paper and repo disagree materially
- the real run or eval entrypoint is unclear
- code changes are likely required
- the contract spans multiple metrics, datasets, subtasks, or splits that still need interpretation
- the same failure class reappears after one documented autonomous fix
- the quest is trying to publish a reusable global baseline rather than only clear the current gate

## Use when

- no credible baseline exists yet
- the current baseline is unverified or stale
- the user already has a baseline package that should be attached or imported
- a reproduction failed earlier and now needs repair
- the quest resumed and the baseline trust state is unclear

## Do not use when

- the quest already has a verified active baseline and the next move is ideation or execution
- the user explicitly waived the baseline gate and that waiver is durably recorded

## Stage gate

Do not proceed to comparison-heavy downstream work unless one of the following is durably true:

- a baseline has been attached and accepted
- a baseline has been imported and accepted
- a baseline reproduction has completed and been verified
- an explicit waiver decision exists with a clear reason

Operationally:

- call `artifact.confirm_baseline(...)` once the accepted baseline root and trusted comparison contract are clear
- call `artifact.waive_baseline(...)` when the quest must continue without a baseline
- attach, import, or publish alone do not open the downstream gate

## Required plan and checklist

Before substantial baseline setup, code edits, or a real baseline run, create a quest-visible `PLAN.md` and `CHECKLIST.md`.

- Use `references/baseline-plan-template.md` as the canonical structure for `PLAN.md`.
- Use `references/baseline-checklist-template.md` as the canonical structure for `CHECKLIST.md`.
- `analysis_plan.md` and `REPRO_CHECKLIST.md` remain acceptable compatibility alias files when an older quest already depends on them.
- For fast-path attach/import/prebound validation or a simple reproduce path with no expected code changes, short-form `PLAN.md` and `CHECKLIST.md` are enough.
- The plan should put the user's explicit requirements and non-negotiable constraints first.
- Then record the chosen route, source identity, command path, expected outputs, acceptance condition, safe efficiency levers, main risks, and fallback.
- If the route, commands, source package, fallback path, or trust judgment changes materially, revise `PLAN.md` before continuing.
- Once the route is concrete, stop reshaping code and commands speculatively.

Default retry discipline:

- do not rerun the same unchanged smoke command just to reconfirm the same fact
- treat one autonomous retry for the same failure class as the normal upper bound
- if the same failure class appears again, switch explicitly into `repair`, record `blocked`, or route through `decision`

## Required durable outputs

The baseline stage should usually leave behind:

- a baseline directory under `baselines/local/` or `baselines/imported/`
- `PLAN.md` and `CHECKLIST.md`
- a verification note or report
- command, config, environment, and metrics pointers
- a baseline artifact
- a confirmed baseline gate via `artifact.confirm_baseline(...)`, or an explicit waiver via `artifact.waive_baseline(...)`
- an optional registry publication if the baseline is reusable beyond this quest

For simple attach/import flows or a straightforward reproduce flow, do not stall just to precreate every optional note file.

Useful optional notes:

- `setup.md`
- `execution.md`
- `verification.md`
- `STRUCTURE.md` when the layout is non-obvious

## File-by-file contract

- `PLAN.md` or compatibility alias `analysis_plan.md` is the required route contract before substantial setup, code edits, or a real run; it should state the route, source identity, command path, expected outputs, acceptance condition, main risks, and fallback.
- `CHECKLIST.md` or compatibility alias `REPRO_CHECKLIST.md` is the required living state tracker; it should show whether the baseline object, smoke decision, real run decision, and final accept / block / waive outcome are explicit.
- `setup.md` is optional unless environment or layout choices are non-trivial; if used, record the working directory, environment route, important config paths, source revision, and notable setup deviations.
- `execution.md` is optional unless the run is long, multi-step, or rerun-heavy; if used, record the launched commands, durable log paths, checkpoints, exit state, and any reruns or repairs.
- `verification.md` is optional as a filename but required in substance before acceptance or blocked closeout; either this file or an equivalent report should record trusted metrics, expected-versus-observed comparison, caveats, canonical output paths, and the next anchor.
- `STRUCTURE.md` becomes required when the workspace layout, mounts, symlinks, or generated outputs are non-obvious or meant for reuse; it should map the important directories and say which paths are canonical.
- `attachment.yaml` is required for attached or imported baselines under `baselines/imported/`; preserve source identity, selected variant when relevant, and attachment provenance there.
- `<baseline_root>/json/metric_contract.json` is the canonical accepted comparison contract; once the baseline is accepted, do not leave the authoritative metric surface only in chat, memory, or prose.
- `Result/metric.md` is scratch-only; it may help during execution, but it is never the final source of truth.

Minimum stability rules:

- before the first real run, leave one durable note with the chosen route, expected command path, target outputs, and main risks
- after each smoke test or real run, record what actually happened and whether the route still looks viable
- before acceptance, leave a clear verification note and baseline gate decision
- every accepted baseline should leave one accepted baseline artifact
- every blocked baseline line should leave one blocked report and one next-step decision
- if one rolling note is enough for a simple baseline line, use it

## Durable path contract

Use the real runtime paths consistently.

Quest-local paths:

- reproduced baseline root: `<quest_root>/baselines/local/<baseline_id>/`
- attached or imported baseline root: `<quest_root>/baselines/imported/<baseline_id>/`
- attachment record: `<quest_root>/baselines/imported/<baseline_id>/attachment.yaml`
- canonical baseline metric contract JSON: `<baseline_root>/json/metric_contract.json`
- baseline artifact record: `<quest_root>/artifacts/baselines/<artifact_id>.json`
- baseline reports: `<quest_root>/artifacts/reports/<artifact_id>.json`
- confirmed baseline reference: `quest.yaml -> confirmed_baseline_ref`

Global reusable registry paths:

- baseline registry index: `~/DeepScientist/config/baselines/index.jsonl`
- canonical baseline entry: `~/DeepScientist/config/baselines/entries/<baseline_id>.yaml`

## Baseline id and variant rules

- `baseline_id` should be short, stable, and filesystem-safe
- use letters, digits, `.`, `_`, or `-`
- do not use spaces, `/`, `\\`, or `..`
- if one codebase contains multiple comparable baselines, prefer one `baseline_id` with structured variants instead of inventing many near-duplicate entries
- when variants exist, keep `default_variant_id`, `baseline_variants`, and per-variant metric summaries stable enough that later `experiment` and `write` stages can cite them directly

Do not invent parallel durable locations when these runtime contracts already exist.
Do not leave the authoritative metric contract only in chat, memory, or prose once the baseline is accepted.

If a baseline is reproduced only because an analysis campaign needs an extra comparator:

- still place it under the normal baseline roots
- treat it as a supplementary analysis baseline unless the quest explicitly promotes it into the canonical gate
- do not call `artifact.confirm_baseline(...)` for that supplementary case unless the quest truly intends to replace the canonical baseline

## Multi-baseline policy

One quest may legitimately need more than one baseline.

- explicitly mark which baseline is the primary downstream comparator
- distinguish primary comparison baselines from fallback or infrastructure baselines
- if several baselines are credible, record why the chosen primary baseline is the fairest paper-facing comparator
- do not leave later stages guessing which baseline is authoritative

## Route order

Prefer this order:

1. attach
2. import
3. reproduce
4. repair

Prefer reuse over redundant reproduction.

## Workflow

### Phase 1. Analysis

Before running anything substantial, determine:

- exact task
- dataset and split contract
- metric contract
- source baseline identity
- source code path
- expected run command or evaluation path
- expected paper or repo numbers when they exist
- local resource constraints

Default analysis discipline:

- read the source paper and source repo first
- if runtime already exposes a matching `requested_baseline_ref` or `confirmed_baseline_ref`, validate that concrete object before restarting broad discovery
- identify the real run or evaluation entrypoint
- identify the dataset or split and metric contract
- identify likely environment blockers
- define the cheapest credible smoke test

Escalate to a fuller audit only when the command path is unclear, the repo is large or confusing, repair mode is active, or custom code changes look likely.

When the fuller audit is necessary, capture only what later stages truly need:

- major entry scripts, configs, and modules
- end-to-end data flow
- evaluation path and metric computation path
- obvious environment assumptions
- obvious bottlenecks or incompatibilities

If the source paper is available, record:

- the core algorithm in compact, implementation-faithful form
- the main reported numbers
- the main weaknesses or bottlenecks likely to matter for this quest

You may inspect local feasibility with shell-based checks for OS, GPU, CPU, RAM, disk, Python version, and whether `uv` is available.

The analysis phase should leave behind a concrete plan rather than only conversational intent.

## Phase 2. Setup

Prepare the selected route:

- attach: validate the selected baseline id and variant
- import: place the imported baseline metadata under the quest and confirm the package is readable
- reproduce: prepare the baseline work directory, commands, config pointers, and environment notes
- repair: identify the precise broken point before rerunning blindly

For Python baselines, standardize environment setup around `uv`.

### Python environment rule: use `uv`

- if the repo already contains `uv.lock` or a solid `pyproject.toml`, use `uv sync`
- otherwise create a local virtual environment with `uv venv`
- install dependencies with `uv pip install ...`
- run setup, smoke tests, and real commands through `uv run ...`

Practical rules:

- prefer a quest-local or baseline-local `.venv`
- prefer `uv run python ...` or `uv run bash ...` over relying on shell activation state
- if a specific interpreter is required, make it explicit with `uv venv --python 3.11` or `uv run --python 3.11 ...`
- if CUDA, PyTorch, JAX, or custom wheels require a special index URL, keep that install under `uv pip`
- only accept a non-`uv` route when there is a concrete blocker that cannot be resolved locally

Common `uv` patterns:

- `uv sync`
- `uv venv --python 3.11`
- `uv pip install -r requirements.txt`
- `uv run python scripts/smoke_test.py`
- `uv run python train.py --config ...`

Setup should record:

- baseline id and source identity
- working directory
- config files
- command template
- expected outputs
- known deviations from paper or source
- the chosen `uv` route and Python version

Fallbacks:

- if Hugging Face access is blocked, record and try an approved local mirror such as ModelScope when that does not change the comparison meaning
- if a quest already depends on `analysis_plan.md` or `REPRO_CHECKLIST.md`, keep the compatibility alias explicit rather than splitting truth across two active plans

## Phase 3. Execution

Run only the work required to establish the baseline credibly.

Execution rules:

- keep commands auditable
- keep logs durable
- avoid uncontrolled side experiments during baseline establishment
- checkpoint only explainable, minimal code changes
- prefer equivalence-preserving efficiency gains such as larger safe batch size, cache reuse, checkpoint resume, and parallel downloads or workers
- do not use an efficiency lever if it changes accepted baseline meaning, effective evaluation contract, or trust judgment

Long-running execution discipline:

- run one bounded smoke test before a substantial baseline reproduction
- once the smoke test passes, launch the real baseline reproduction with `bash_exec(mode='detach', ...)`
- monitor by forward progress instead of by short-window completion anxiety
- do not report final success until the command actually finished and the expected result files exist
- if you need to recover ids or inspect session state, use `bash_exec(mode='history')` or `bash_exec(mode='list')`
- `bash_exec(mode='read', id=...)` returns the full saved log when it is `2000 lines or fewer`; for longer logs, inspect omitted middle windows with `start` and `tail`
- during monitoring, prefer `bash_exec(mode='read', id=..., tail_limit=..., order='desc')`, and after the first read prefer incremental checks with `after_seq=last_seen_seq`
- use `silent_seconds`, `progress_age_seconds`, `signal_age_seconds`, and `watchdog_overdue` as the default staleness clues
- if a run is clearly invalid, wedged, or superseded, stop it with `bash_exec(mode='kill', id=..., wait=true, timeout_seconds=...)`, document why, and relaunch cleanly
- do not let more than the `30-minute visibility bound` pass without a real inspection and a `next expected update time`
- when the baseline code is under your control, prefer a throttled `tqdm` progress reporter and periodic `__DS_PROGRESS__` markers when feasible

Keep retries bounded:

- one smoke test is the default
- one autonomous fix-and-retry for the same failure class is the normal upper bound
- if the same failure class returns, stop looping

## Phase 4. Verification

Verification is mandatory before baseline acceptance.

Verify:

- the run actually finished
- the reported metrics came from the intended dataset and split
- the metric definitions match the quest contract
- the result is comparable to the paper, source repo, or selected target
- any deviations are explicitly stated

Classify the outcome as one of:

- `verified_match`
- `verified_close`
- `verified_diverged`
- `broken`

Verification must explicitly separate:

- likely implementation mismatch
- environment mismatch
- data or split mismatch
- expected stochastic variance
- unexplained divergence

Verification should answer:

- whether the baseline is trustworthy enough for downstream comparison
- whether the result is reusable beyond this quest
- whether another repair or rerun is justified
- whether the line should stop here and hand off

A verification report should be self-contained enough that a later stage can answer:

- what was used
- how it was obtained: attach, import, reproduce, or repair
- what commands and configs were used
- what metrics are trusted
- what caveats remain
- whether the result is reusable beyond this quest

## Baseline comparability contract

The baseline stage is not complete just because something ran.
It is complete when later stages can compare against it fairly.

Before declaring a baseline usable, make the comparability contract explicit:

- task identity
- dataset identity and version
- split contract
- preprocessing boundary
- evaluation script or evaluation path
- required metric keys
- metric directions
- seed policy when relevant
- source commit or source package identity
- known deviations from the source reference

Unless the user explicitly specifies otherwise, treat the original paper's evaluation protocol as the canonical baseline contract.
If any of these fields are still materially unknown, do not pretend the baseline is a clean downstream reference.
For the fuller checklist and verdict meanings, read `references/comparability-contract.md`.

## Feasibility and trust classes

Before acceptance, classify feasibility as one of:

- `full_reproducible`
- `degraded_but_acceptable`
- `blocked`

And classify downstream trust as one of:

- `verified`
- `partially_verified`
- `operational_but_incomparable`
- `failed`

Do not silently upgrade a degraded or merely operational result into a normal trusted baseline.

## Minimum baseline artifact content

The accepted baseline artifact should include at least:

- `baseline_id`
- `baseline_kind`
- `path`
- `task`
- `dataset`
- `primary_metric`
- `metrics_summary`
- `environment`
- `source`
- `summary`

If variants exist, also include:

- `default_variant_id`
- `baseline_variants`

Metric-contract rules:

- if the accepted baseline contract includes multiple metrics, datasets, subtasks, or splits, record all of them in `<baseline_root>/json/metric_contract.json`
- keep `primary_metric` as the headline metric only; do not let it erase the rest of the comparison surface
- when confirming a baseline, submit the canonical `metrics_summary` as a flat top-level dictionary keyed by the paper-facing metric ids
- every canonical baseline metric entry should include `description`, either `derivation` or `origin_path`, and `source_ref`
- if the paper reports both aggregate and per-dataset or per-task results, preserve both whenever feasible through `metrics_summary` plus structured rows rather than one cherry-picked scalar
- if the source package already has a richer leaderboard table, structured result file, or `json/metric_contract.json`, reuse that richer contract instead of hand-writing a thinner one that keeps only one averaged scalar
- `Result/metric.md` is optional temporary scratch memory only; reconcile against it before calling `artifact.confirm_baseline(...)`, but do not treat it as a required durable file

## Publication and reuse

Use the registry deliberately, not as an afterthought.

If the result is reusable beyond the current quest:

- publish it through `artifact.publish_baseline(...)`
- ensure the payload includes identity, provenance, trusted metrics, and any variant structure
- set `publish_global: true` only when verification is complete and reuse is justified

If the current quest should reuse an existing baseline:

- attach it through `artifact.attach_baseline(...)`
- preserve the selected `baseline_id`
- preserve the selected `variant_id` when one is used
- keep the attachment durable under `baselines/imported/`

If runtime state already includes `requested_baseline_ref` or a matching `confirmed_baseline_ref`:

- default to reuse-and-verify, not rediscovery
- treat a creation-time pre-bound baseline as the active starting point unless you find a concrete incompatibility
- do not rerun broad baseline scouting or full reproduction just because the stage name is `baseline`

For a clearer attach/import/reproduce/repair rubric, read `references/route-selection.md`.
For reusable-package expectations, read `references/publishable-baseline-package.md`.

## Workspace and branch rules

- treat the baseline workspace as a system-managed reproduction surface, not an unrelated sandbox
- avoid creating a nested authoritative Git lifecycle inside the baseline workspace
- use the quest branch unless isolation is genuinely needed
- if baseline setup is risky or intrusive, prepare an isolated branch or worktree first and record why
- do not proliferate branches without a reason

## Memory rules

Stage-start requirement:

- by default, begin every baseline pass with `memory.list_recent(scope='quest', limit=5)`
- then run at least one baseline-relevant `memory.search(...)` before new baseline analysis, repair, or rerun work
- fast-path exception: if the quest already exposes a clear `requested_baseline_ref` or `confirmed_baseline_ref` and the immediate task is only to validate or reattach that concrete baseline, you may skip broad retrieval

Write memory only for reusable lessons such as:

- paper-to-code mismatch notes
- environment incidents
- dataset quirks
- verification caveats
- attach vs import vs reproduce vs repair rationale

When calling `memory.write(...)`, pass `tags` as an array like `["stage:baseline", "baseline:<baseline_id>", "type:repro-lesson"]`, not as one comma-joined string.

Stage-end requirement:

- if baseline work produced a durable reproduction lesson, verification caveat, environment incident, or route rationale, write at least one `memory.write(...)` before leaving the stage

## Artifact rules

Typical artifact sequence:

- `progress` for long-running setup or execution checkpoints
- `report` for analysis notes or verification notes
- `decision` for route choice, blocked routing, or accept/reject/rerun/repair calls
- `baseline` only for an accepted baseline record

For stable field shapes, read `references/artifact-payload-examples.md`.

The baseline handoff should make these items obvious:

- `baseline_id`
- `baseline_variant_id` when relevant
- route used: attach, import, reproduce, or repair
- trusted metrics
- canonical metric contract JSON path
- verification outcome
- reusable or quest-local only
- canonical output paths
- main caveats
- recommended next anchor

If this packet is not obvious from the accepted artifact plus verification note, the baseline line is not stable enough yet.

## Failure and blocked handling

Do not hide failures.

If blocked, record the class explicitly:

- `missing_source`
- `missing_code`
- `missing_metric_contract`
- `environment_infeasible`
- `command_unknown`
- `run_failed`
- `verification_failed`

A blocked result must state:

- what failed
- what was tried
- which paths or logs show the issue
- whether the next best move is attach, import, retry, repair, reset, or ask the user

Reasonable autonomous fixes before escalation:

- missing module or dependency
- wrong dataset path
- permission errors on scripts
- reasonable batch-size reductions for OOM
- obvious environment activation mistakes

If a fix would change confirmed scope, metrics, permissions, or resource assumptions, stop and return to analysis rather than applying it silently.

## Exit criteria

Exit the baseline stage once one of the following is durably true:

- a baseline is attached and accepted
- an imported baseline is accepted
- a reproduced baseline is verified and accepted
- a broken route has been declared blocked and a next decision is recorded

Typical next anchors:

- `idea`
- `experiment` in tightly scoped follow-on cases
- `decision` if the baseline line remains contested