intake · diff
git:20260816.bac04eb to git:20260822.c9f4a7f
107 added, 229 removed. Audit A to A.
---
name: intake
- description: Phase 1 of the pipeline — collect inputs and scaffold the run. Use at the very start of any optimization. Interviews the user to decide what capability to optimize, which runner/optimizer/algorithm to use, and where the data is; scaffolds .capevolve/project/ (adapter stub, capevolve.yaml, PROJECT.md); and for every NEEDED input that is missing, asks the user (quoting path, how to retrieve it, alternatives) rather than fabricating it.
+ description: Starts a cap-evolve optimization run. Interviews the user to decide what capability to optimize, which runner/optimizer/algorithm to use, and where the tasks and the scoring source live, then scaffolds .capevolve/project/ (adapter stub, capevolve.yaml, PROJECT.md). Use when someone asks to optimize or improve an agent capability against an eval and no project exists yet — "set up a run", "start optimizing X", "make X score higher on this benchmark". This is Phase 1 of the pipeline. For every NEEDED input that is missing it asks the user — quoting the expected path, how to retrieve it, and the alternatives — instead of fabricating it. Not for a project that already exists: when .capevolve/project/ is present, go to implement-and-check or the algorithm loop instead.
component: phase
- argument-hint: "--base .capevolve"
+ argument-hint: "--base .capevolve --workdir ."
allowed-tools: Read, Write, Edit, Bash
provides: [project, tasks]
needs: []
sources: []
---
# intake — collect inputs, scaffold the project
- The first phase. Its job is to turn a vague wish ("make this agent better at X")
- into a concrete, runnable project: a filled `capevolve.yaml`, an adapter ready to
- implement, and **every NEEDED input resolved before any budget is spent**. Intake
- is cheap; a botched intake is not — an unresolved input discovered three phases
- later means a wasted optimization run and a meaningless number.
-
- ## Inputs / outputs (manifest tokens)
- - **needs:** *(nothing)* — intake is the pipeline entry point.
- - **provides:** `project` (the scaffolded `.capevolve/project/`) and `tasks` (the
- evaluation dataset, resolved either to a path or to the adapter's `tasks()`).
-
- Downstream, `implement-and-check` consumes `project`; `baseline` consumes
- `project` + `tasks`. If intake under-delivers either token, the hard gate in
- `implement-and-check` fails loudly rather than silently optimizing against a stub.
-
- ## Step 0 — Inspect before asking
- Before any question, inspect the target so you can PROPOSE defaults instead of asking blind:
- 1. Look at the repo/benchmark/agent: entrypoint, how one eval runs, where traces/scores live.
- 2. Detect candidate metrics (what the scorer emits), a natural train/val/test split, and cost caps.
- 3. Run `gh auth status` to know whether GitHub is available.
+ Turn a vague wish ("make this agent better at X") into a runnable project: a filled
+ `capevolve.yaml`, an adapter ready to implement, and **every NEEDED input resolved
+ before any budget is spent**. Intake is cheap; an unresolved input found three phases
+ later is a wasted run and a meaningless number.
- Then ask the FEWEST questions — present detected metrics/splits/caps as multiple-choice
- defaults with a free-text escape, keeping the ask-user-if-missing discipline for NEEDED
- inputs. The metric / GitHub / stop-condition questions below feed directly into the
- `capevolve.yaml` spec keys, so ask them here (after inspecting, before scaffolding).
+ ## Ask, never fabricate — the core discipline of this phase
- ### Metrics
- - Which metrics should the dashboard show? (detected: `<list>`) — multiple choice + free text → `metrics_display`.
- - Which ONE gates accept/reject? — single choice → `metric_primary`. (This is the only metric the gate uses.)
- - For each shown metric, is higher or lower better? → `metric_directions` (parallel to `metrics_display`).
+ `inputs/INPUTS.md` classifies every input **NEEDED** or **RECOMMENDED**. For each
+ **NEEDED** input that is not already present, do not proceed:
+ - **Interactive / chat mode — ASK THE USER and wait.** Quote all three, they are in
+ `INPUTS.md` per input: (a) the exact path the input is expected at, (b) the command
+ or option that produces it, (c) the alternatives. Say what breaks without it.
+ - **Non-interactive** (`cap-evolve run` / the `orchestrate` skill, nobody to ask) —
+ write `BLOCKED: <input> — why it is needed — how to provide it` into `PROJECT.md`
+ and exit non-zero. A blocked-but-honest stop is correct; a green run on a guessed
+ input is not.
- ### GitHub integration
- - `gh auth status` = authed? Offer: mirror the algorithm's work items as issues + ship winner as PR (`Closes #n`) → `github_integration: true`; else offer `gh auth login` or skip → `false`. WHAT gets mirrored is algorithm-specific (the `algorithm_skill` defines it — e.g. evograph → weaknesses). GitHub is mirror-only; the run dir stays authoritative.
+ A fabricated dataset, scorer, trajectories path or gold answer does not unblock the run
+ — it produces a number that measures nothing and hides that fact. A missing tasks file
+ is a *question for the user*, not a gap for you to paper over.
- ### Orchestration mode
- - Ask: deterministic or agent? → `orchestration_mode` (default `deterministic`).
- - `deterministic` — cap-evolve sequences intake→…→algorithm→finalize; honesty is code-enforced. Best when a deterministic engine exists for the algorithm.
- - `agent` — the coding agent drives the loop itself (reads the algorithm's "Agent-mode loop"), self-policing honesty, and seals via the finalize phase. Required for agent-only algorithms. The purpose-built fully-agentic algorithm is `algorithm_skill: agent-optimize` (free-form loop; it also does a Phase-0 understand-the-benchmark step). In agent mode also collect `stop_condition`.
+ **RECOMMENDED** inputs may take their default, but log every default in `PROJECT.md`
+ with its honesty cost (e.g. "num_trials=1 — single-trial scores, so the significance
+ gate will correctly reject marginal gains"), so the cost is visible at report time.
- ### Stop condition (agent mode)
- - Free-text halt rule re-read each round → `stop_condition`. Deterministic mode leaves it blank and uses budget knobs.
+ ## Step 0 — mine, then inspect, then ask once
+ 1. **Mine the conversation first.** Anything the user already said is an answer you
+ must not re-ask — "optimize my airline policy on the flight-change tasks" already
+ fixed the capability, the artifact and the task subset. Harvest that, and any
+ correction the user made, before asking anything.
+ 2. **Run the miner.** `python scripts/run.py --base .capevolve --workdir <repo-root>`
+ scaffolds and returns `discovered` — task files, capability artifacts, existing
+ adapters. Reuse what it found; never re-author it.
+ 3. **Inspect what `discovered` leaves open**: the entrypoint, how one eval runs, where
+ traces and scores land, candidate metrics, a natural train/val/test split, cost caps.
+ Run `gh auth status`. Fan subagents out over the benchmark repo (entrypoint, scorer,
+ trace dir, task schema) *while* the user answers instead of serializing — come
+ prepared, so the user carries as little of the research as possible.
+ 4. **Then ask the FEWEST questions, as ONE numbered batch**, each with the detected
+ value pre-filled as a default plus a free-text escape — including the ones only a
+ human can answer: which metric gates accept/reject and each shown metric's
+ direction, GitHub mirroring, deterministic vs agent orchestration (plus
+ `stop_condition` in agent mode), splits, trials, budget. `inputs/INPUTS.md` →
+ RECOMMENDED is the authority on each key; SKILL.md only fixes *when* to ask. Define
+ jargon in a clause before using it ("pass^k — how often it succeeds on all k
+ tries"); the user may be a domain expert, not an ML one.
+ 5. **Confirm before scaffolding.** Echo the resolved spec back as one block —
+ capability, optimizer, algorithm, dataset, splits, budget, every RECOMMENDED input
+ you are defaulting — and get a yes. A misread is cheapest to fix here.
## What it does
- 1. **Interview** (driven by this SKILL.md): pick the capability skill (*what* is
- optimized), the optimizer (*which* coding agent proposes edits), the algorithm
- (*the search loop*), the dataset, the splits, and the budget.
- 2. **Scaffold** `.capevolve/project/` from the template (`scripts/run.py`):
- adapter stub, `inputs/`, `capevolve.yaml`, `PROJECT.md`, and the optimizer-prompt
- template `optimizer/INSTRUCTIONS.md` (the whole `templates/project/` tree is
- copytree'd verbatim, so this file is already in place — confirm it exists).
- 3. **Resolve inputs** per `inputs/INPUTS.md` — the contract below.
- 4. **Wire trajectories + scoring into the adapter.** From the *trajectories path*
- and *metric extraction / scoring source* inputs:
- - implement `adapter.trajectories(split)` to RETURN the runner's native trajectory
- directory for the last eval of `split` (any structure/format; it is copied
- verbatim into the optimizer's `./trajectories/`). Return `None` only if there is
- genuinely no separate native store (cap-evolve then falls back to its per-rollout
- JSON) — note that choice in `PROJECT.md`.
- - implement `score()` to extract the OBJECTIVE metric from a rollout, matching the
- benchmark's own scoring source; verify it reproduces the benchmark's number.
- - **Make `score()`'s feedback ARGUMENT-LEVEL — it IS the learning signal.** A
- tool-name-only signal ("action X was wrong") is too coarse for the optimizer to
- localize a fix; it pattern-matches to prose rules and the run plateaus. For EACH
- failing check, the feedback must point at the specific argument/value/step that
- was wrong: name the wrong ARGUMENT key and the **agent's OWN wrong value** (not
- the gold value), name the wrong target id, and for communication/omission misses
- name the value or field the agent failed to state **when it is derivable from the
- agent's own state** (e.g. an un-stated computed total). This is **gold-SAFE**:
- derive everything from the agent's own messages/tool-calls/observed state (and the
- user's own profile/db state the agent saw) — use the gold record ONLY to learn
- WHICH check/argument failed (key names are safe; gold VALUES must never be read or
- printed). When a piece is not safely derivable, fall back to the coarser
- tool-name message. Keep `score()` deterministic (the check gate requires it).
- 5. **Author the optimizer instructions for THIS benchmark — SCOPED TO THE SELECTED
- CAPABILITIES.** Customize the scaffolded `.capevolve/project/optimizer/INSTRUCTIONS.md`.
- Keep the `{{...}}` placeholders intact (`{{FOCUS_SUMMARY}}`, `{{FAILURES}}`,
- `{{CAP_BRIEF}}`, `{{ALGO_BRIEF}}`, `{{BENCH_REPO}}` — the harness fills them per
- iteration). Keep the authored static guidance **short on meta-narration, explicit
- and DEMANDING on iteration depth**, and make it **capability-scoped**: include
- guidance, skill references, and edit-space ONLY for the capabilities actually
- listed in `capevolve.yaml: capabilities`.
- - **DEPTH MANDATE — address ALL failure clusters each iteration.** The authored
- instructions must demand a substantial multi-root-cause pass: diagnose ALL
- clusters and fix as many as possible in ONE candidate, spanning EVERY edit class
- the selected capabilities offer (each capability's SKILL.md enumerates its own).
- Scope each fix to protect passing tasks; do NOT trade breadth for caution. State
- plainly that a single small edit is an under-used iteration. For the concrete
- per-capability wording of this mandate, use the selected capability's own
- optimizer playbook (see the capability-playbook rule below).
- - **State the GOAL up front:** maximize the eval score — make the largest
- improvement you can this iteration, grounded in the trajectories.
- - **The authored INSTRUCTIONS MUST encode all of these (generic, capability-scoped):**
- 1. **STEP-0 reading mandate.** Before diagnosing, the optimizer must READ
- `./guidance/<cap>/SKILL.md` (for EACH selected capability) and the optimizer
- features reference under `./guidance/optimizer/`. State this as an explicit
- first step.
- 2. **Each selected capability's own optimizer playbook.** For EVERY capability in
- `capevolve.yaml: capabilities`, load that capability's playbook from its skill.
- Both path forms matter, each for its own reader: YOU read it in this repo at
- `skills/capabilities/<cap>/references/` (e.g. `tools` →
- [`optimizer-playbook.md`](../../capabilities/tools/references/optimizer-playbook.md)),
- but any path you WRITE INTO the authored INSTRUCTIONS must be the
- runtime-materialized form `./guidance/<cap>/references/` — the repo-relative
- path does not resolve in the optimizer's working dir. Fold its edit-depth
- demands and subagent-fan-out pattern into the authored INSTRUCTIONS. Do NOT
- restate one capability's playbook here — it lives with that capability and
- evolves with it.
- 3. **The NON-OVERFITTING guardrail.** Demand that every prompt/tool edit encode
- a GENERAL rule/policy/validation that generalizes across the whole class of
- inputs — NEVER hardcode a specific task's id/value/date/name/answer. A guard
- must fire on the general condition (e.g. "id not in the user's profile"), not
- match a literal value (NOT `if id == "<TASK_SPECIFIC_ID>"`). A literal special-case that
- only helps one task is forbidden — it overfits, fails the held-out gate, and
- hurts other tasks. Per-task specifics are for understanding the failure CLASS
- only; the fix must be general.
- 4. **EXPLOIT ground-truth/eval present in the trajectories (diagnosis only).**
- Tell the optimizer that when `./trajectories/` include ground-truth /
- expected actions / a reward breakdown, it should USE them during diagnosis to
- localize the exact defect (expected vs actual action/argument/value) — and if
- not present, infer from the traces + feedback. State plainly that ground truth
- informs the failure class only; the resulting edit must still be GENERAL
- (guardrail 3) and never copy a gold value.
- - **Capability-scoping (the key rule):** reference `./guidance/<cap>/SKILL.md`
- and present the editable artifacts **for the selected caps only**. If only
- `tools` is selected, do NOT include any prompt-editing guidance, do NOT
- reference the `system-prompt` skill, and do NOT present the prompt/policy file
- as editable. If only `system-prompt` is selected, do not surface the tools file
- as editable. Each capability's "What you can change here" lives in its
- `./guidance/<cap>/SKILL.md` — point the optimizer there rather than restating it.
- - **Always include (capability-agnostic):** READ the four cross-iteration files in
- the working dir FIRST — `./LEDGER.md` (framework facts: each iteration's outcome +
- tasks broken/fixed), the whole `./JOURNAL.md` (the optimizer's append-only
- handover across the run), and `./RUNMAP.md` + `./prior_iterations/<id>/` (every
- prior iteration's PROCESS.md + capability diff) — and never re-propose an approach
- the journal/ledger shows was rejected *as implemented* (a better-designed version
- may still work — not a permanent ban); READ and USE the diagnose skill
- `./guidance/diagnose/SKILL.md` (incl. its KNOWLEDGE / BEHAVIORAL / CAPABILITY-GAP
- tags), the optimizer features reference `./guidance/optimizer/<name>.md`, this
- step's `./trajectories/`, and any `./guidance/sources/` data-model files. Each
- iteration the optimizer MUST: fill `./PROCESS.md` (the required explainability
- template — ranked issues + tags, every edit + class, verify-the-fix,
- subagents/features used, what to preserve, what was skipped) and APPEND its entry
- to `./JOURNAL.md` below the marker (what was tried / worked / regressed / refuted /
- plateau-signal / focus-next). Ship MULTIPLE edit classes and ADD a new
- code-bearing tool whenever a CAPABILITY-GAP/stall cluster is present.
- 6. **Set the spec keys** in `capevolve.yaml`:
- - `runner_repo_path` — the benchmark/runner source, surfaced read-only to the
- optimizer.
- - `optimizer_instructions_file` — point at the customized template (default
- `optimizer/INSTRUCTIONS.md`).
- - `capability_sources` — the benchmark's data-model / types source files that the
- tools import (resolved relative to the project dir; copied verbatim into the
- optimizer's `./guidance/sources/`), so the optimizer can write correct code
- against the real types. Set this whenever a selected capability's code imports a
- shared types/data-model module; leave the default `[]` when there is none.
- - `target_model` (+ optional `target_profile_file`) — the runtime/CONSUMING LLM the
- agent reads the capabilities with, DISTINCT from `optimizer_model`. A model id or a
- tier (`frontier|strong|mid|weak`); steers the optimizer prompt + capability guidance
- to optimize FOR that reader. Ask which model the agent runs at runtime; leave blank
- (profile-agnostic) if unknown. See `inputs/INPUTS.md` → `target_model`.
-
- ## Ask-the-user-if-missing (mandatory — the core discipline)
- Read `inputs/INPUTS.md`. It classifies every input as **NEEDED** or
- **RECOMMENDED**. For each **NEEDED** input that is not already present:
-
- > **ASK THE USER.** Quote (a) the exact path where it is expected, (b) the
- > command or option that produces it, and (c) any alternatives. Then wait.
-
- **Never invent a NEEDED input.** Fabricating a dataset, a scorer, or a gold
- answer does not unblock the run — it produces a number that measures nothing and
- hides that fact. A missing tasks file is a *question for the user*, not a gap for
- you to paper over. This is the single most important behavior of this phase.
-
- **RECOMMENDED** inputs have sane defaults and may be skipped — but log every skip
- in `PROJECT.md` (e.g. "num_trials defaulted to 1 — scores will be single-trial,
- so the significance gate will correctly reject marginal gains"), so the honesty
- cost of each default is visible at report time.
-
- ### Block on a missing NEEDED input (never fabricate)
- The action when a NEEDED input is absent depends on the run mode:
- - **Interactive / chat mode** — ASK THE USER and wait: quote *what* is needed, *why*
- it is needed (what breaks without it), and *how* to provide it (the exact path /
- command / option / alternatives from `INPUTS.md`). Do not proceed past the missing
- input.
- - **Non-interactive mode** (`cap-evolve run` / orchestrate, no human to ask) — do NOT
- fabricate. WRITE a clearly delimited section into `PROJECT.md`:
- `BLOCKED: <input> — why it is needed — how to provide it`, then STOP with a non-zero
- exit. A blocked-but-honest stop is correct; a green run on a guessed input is not.
-
- This extends the ask-if-missing discipline above — it is the same rule, with an
- explicit non-interactive fallback so a headless run fails loud and recorded instead
- of silently inventing a dataset, scorer, trajectories path, or scoring source.
-
- ### Why a contract, not a guess
- The classic failure mode of "auto-optimize my agent" tooling is to start running
- with whatever it can find and backfill assumptions. That yields a green run and a
- worthless result. Splitting inputs into NEEDED (blocking → ask) vs RECOMMENDED
- (default → log) makes the *only* legitimate way to proceed-without-an-input an
- explicit, recorded default — never a silent fabrication. Treat `INPUTS.md` as the
- spec; this SKILL.md is just the procedure for honoring it.
-
- ## Dual-mode
- This phase runs two ways from the **same** SKILL.md: standalone as the slash command `/cap-evolve:intake` (the `argument-hint` shows its run.py args), and orchestrator-callable — `cap-evolve run` / the `orchestrate` skill invokes the same `scripts/run.py` headlessly and threads the run dir between phases.
+ The interview settles the capability skill (*what* is optimized), the optimizer (*which*
+ coding agent proposes edits), the algorithm (*the search loop*), dataset, splits, budget.
+ 1. **Scaffold** `.capevolve/project/` via `scripts/run.py`: adapter stub, `inputs/`,
+ `capevolve.yaml`, `PROJECT.md`, and `optimizer/INSTRUCTIONS.md`. The whole
+ `templates/project/` tree is copytree'd verbatim — confirm the files landed.
+ 2. **Resolve inputs** per `inputs/INPUTS.md`, honoring the ask-never-fabricate rule.
+ 3. **Record** the resolved trajectories path and the scoring source in `PROJECT.md`, so
+ `implement-and-check` wires `trajectories()` and `score()` against real inputs rather
+ than guesses. `inputs/INPUTS.md` → **scorer** specifies exactly what the feedback must
+ be (argument-level, gold-safe) and that `score()` must be deterministic — follow it
+ literally, that feedback is the learning signal. Note in `PROJECT.md` if you
+ deliberately return `None` from `trajectories()` (cap-evolve then falls back to its
+ own per-rollout JSON).
+ 4. **Customize the scaffolded `optimizer/INSTRUCTIONS.md`** for THIS benchmark. The
+ shipped template already carries the depth mandate, the non-overfitting guardrail,
+ the STEP-0 reading mandate and the cross-iteration file protocol — do not
+ re-author any of them. Your three jobs:
+ a. keep every `{{...}}` placeholder intact (`{{FOCUS_SUMMARY}}`, `{{FAILURES}}`,
+ `{{CAP_BRIEF}}`, `{{ALGO_BRIEF}}`, `{{BENCH_REPO}}` — the harness fills them per
+ iteration; `implement-and-check`'s pipeline self-test fails if one is deleted,
+ and rendering must leave no `{{` behind);
+ b. **scope it to the selected capabilities** — delete the sections for capabilities
+ not listed in `capevolve.yaml: capabilities`, so a run never presents an
+ artifact as editable that this run does not own. Point the optimizer at
+ `./guidance/<cap>/SKILL.md` for each selected capability's own edit space, and
+ at `./guidance/diagnose/SKILL.md` for the failure taxonomy — both are
+ materialized into its working dir. When a selected capability ships one, also
+ point at `./guidance/<cap>/references/optimizer-playbook.md`;
+ c. add the benchmark-specific facts the template cannot know: where the runner
+ writes traces, what the scoring source is, which data-model files the
+ capability's code imports.
+ 5. **Set the spec keys** in `capevolve.yaml` — `runner_repo_path`,
+ `optimizer_instructions_file`, `capability_sources` (the module(s) a selected
+ capability's code imports, copied into the optimizer's `./guidance/sources/`),
+ `target_model`. `inputs/INPUTS.md` defines each one.
+ - **Caution (issue #252):** a *relative* `optimizer_instructions_file` resolves
+ project-relative under `check` but cwd-relative under `run`, which then silently
+ falls back to the generic template. Write it absolute, or verify `run` actually
+ picks up the customized file — intake authors it, so intake is the cheapest place
+ to get it right.
## How to run
```
- python scripts/run.py --base .capevolve # scaffold .capevolve/project
+ python scripts/run.py --base .capevolve --workdir . # mine, then scaffold
```
- The script is purely mechanical: it copies the template and prints the next
- steps. The *judgment* — interviewing, choosing components, and running the
- ask-if-missing loop — is yours, driven by this SKILL.md and `inputs/INPUTS.md`.
-
- Then implement `adapters/adapter.py`, fill `capevolve.yaml`, and proceed to
- `implement-and-check`. Together, **intake → implement-and-check** is the *full
- integration*: scaffold → implement the 3 required adapter methods →
- `cap-evolve check` green, before any budget is spent. The using-agent (e.g. the chosen optimizer) can run
- this whole integration autonomously.
+ The script is purely mechanical; the *judgment* — interviewing, choosing components, the
+ ask-if-missing loop — is yours. Then implement `adapters/adapter.py`, fill
+ `capevolve.yaml`, and hand off to `implement-and-check`: together the two phases are the
+ *full integration* (scaffold → the 3 required adapter methods → `cap-evolve check` green)
+ and no budget is spent until that gate passes.
- > **Worked example (onboard a new benchmark from a prompt):** see `examples/` for
- > an end-to-end onboarding. The intake/onboarding step **installs the benchmark**
- > (clones + installs it) and the **optimizer agent** wires the adapter from the
- > stub until `cap-evolve check` passes, then optimizes the selected capability. The
- > example's `setup.sh` is the executable transcript of that onboarding; `run.sh`
- > runs the full optimization with the live dashboard.
+ > **Onboarding transcript (one example):** `examples/tau2_airline/setup.sh` clones and
+ > installs a benchmark and wires the adapter until `cap-evolve check` is green, and its
+ > `run.sh` runs the optimization. Read it only when onboarding a benchmark you have not
+ > integrated before.
- ## What good vs bad intake looks like
- - **Good:** every NEEDED input resolved to a real path or `"adapter"`; splits and
- budget chosen deliberately; each defaulted RECOMMENDED input logged in
- `PROJECT.md`; `capevolve.yaml` fully filled; the user answered every blocking
- question before the scaffold was declared done.
- - **Bad:** a tasks file that "looked plausible" was synthesized; the scorer leaks
- the gold answer into feedback; test == train with no note; budget left at a
- default that cannot possibly find a gain; the run proceeded past a missing
- NEEDED input "to keep moving".
- - **Bad:** authored INSTRUCTIONS that omit the STEP-0 reading mandate, or that skip a
- selected capability's own optimizer playbook — so an iteration can pass on a
- cosmetic edit that the capability's playbook calls under-used.
+ ## Good vs bad intake
+ - **Good:** every NEEDED input resolved to a real path or `"adapter"`; splits and budget
+ chosen deliberately; each defaulted RECOMMENDED input logged; spec confirmed by the user.
+ - **Bad:** a synthesized tasks file that "looked plausible"; a scorer that leaks the gold
+ answer into feedback; test == train with no note; a budget too small to find a gain;
+ the run proceeded past a missing NEEDED input "to keep moving".
## References
- - `references/concepts.md` — the inputs contract, NEEDED vs RECOMMENDED
- rationale, the 3 required adapter methods, and split/trial/budget guidance with
- sources.
+ - `inputs/INPUTS.md` — the binding contract: every input classified NEEDED vs RECOMMENDED
+ with the path / how-to-retrieve / alternatives you must quote, plus the meaning and
+ default of every spec key. Read it during the interview.
+ - `references/concepts.md` — why the contract is shaped this way, the 3 required adapter
+ methods, split/trial/budget guidance with sources. Read it if this phase is new to you.