strategy-discovery

# Strategy Discovery

## Purpose

Strategy Discovery is the single entry point for two questions: **what strategies exist**, and **what state are they in**. It fronts the Alpha Zoo registry and the SDM strategy store with one facade and answers with computed evidence instead of labels, and it reports the freshness of that evidence on every returned row.

It supersedes the earlier closed-registry attempt. That design attached boolean scenario tags (works in bear markets: yes/no) to a curated list. This skill replaces tags with **per-regime evidence rows**: every claim that a strategy works in a regime must come from a computed, reproducible backtest stored as evidence, never from curation or inference.

The three query tools are read-only: they never register, mutate, or delete strategies. To add or change strategies, use the `strategy-dev-manager` and `alpha-zoo` workflows — Strategy Discovery only reports what those workflows have produced. The fourth tool, `refresh_strategy_evidence`, is the single write in the surface: it rebuilds ONLY the disposable evidence cache from local backtest run artifacts (see Populating & Refreshing Evidence and Composition Guarantee).

## When to Use

Decision tree for routing user requests:

- User asks **what strategies exist** / "list available strategies" → `list_strategies(limit=..., offset=..., source=...)`
- User asks **which strategy fits a regime or threshold** ("what works in bear markets?", "anything with Sharpe above 1?") → `query_strategies(regime=..., min_sharpe=..., ...)`
- User asks for **the evidence behind one specific strategy** → `get_strategy_evidence(strategy_id=..., regime=...)`
- User asks to **populate or refresh the evidence cache** ("turn my backtest runs into evidence", "the evidence is stale, refresh it") → `refresh_strategy_evidence(manifest_path=...)` — this rebuilds the disposable cache from run artifacts; it is NOT strategy creation or registration
- User asks to **create, backtest, or register** a strategy → this is NOT this skill; route to `strategy-generate` / `strategy-dev-manager` / `alpha-zoo`

The access path is the three read tools (`list_strategies`, `query_strategies`, `get_strategy_evidence`) plus one cache-refresh tool (`refresh_strategy_evidence`), available through the agent registry and the MCP server under the same names. The only CLI surface is `vibe-trading strategy-evidence refresh --manifest <path>`, which runs the same refresh as the tool; queries stay with the agent tools. Do not invent flags or subcommands beyond that.

## Tools

### list_strategies

Browse the catalogue.

| Parameter | Type | Default | Meaning |
|-----------|------|---------|---------|
| `limit` | integer | 20 | Maximum number of rows to return |
| `offset` | integer | 0 | Pagination offset |
| `source` | string | none | Optional filter: `alpha_zoo \| sdm`; omit for both |

Returns identification metadata plus evidence status. This is a catalogue listing, not a ranking — use `query_strategies` for filtered, evidence-ranked results.

### query_strategies

Evidence-gated query.

| Parameter | Type | Default | Meaning |
|-----------|------|---------|---------|
| `regime` | string | none | `bear_market`, `bull_market`, or `structural`; omit for all regimes |
| `min_sharpe` | number | none | Minimum Sharpe on the evidence rows |
| `min_evidence_quality` | string | `adequate` | `adequate` \| `marginal` \| `insufficient` \| `any`. `any` only removes the quality floor — rows must still pass the other filters (`min_trades`, `cost_feasible`, `min_sharpe`) to be kept |
| `min_trades` | integer | 10 | Minimum executed-trade count for evidence to count |
| `cost_feasible` | boolean | true | Keep only rows that clear the cost screen. Fail-closed: rows whose breakeven is unverifiable (`null`, see Multi-position caveat) are excluded; set `false` to inspect them with their warnings |
| `include_stale` | boolean | false | Keep rows whose evidence is stale (see Decay & Freshness Contract). They are surfaced with their `stale-evidence:` warnings, sorted after non-stale rows; the flag relaxes the staleness gate only, never any other gate |
| `limit` | integer | 10 | Maximum number of rows to return |

### get_strategy_evidence

Per-regime evidence detail for one strategy.

| Parameter | Type | Default | Meaning |
|-----------|------|---------|---------|
| `strategy_id` | string | — | Required. Identifier from `list_strategies` / `query_strategies` |
| `regime` | string | none | Optional regime filter (same values as `query_strategies`) |

Returns the per-regime evidence rows: trade count, coverage window, Sharpe, cost breakeven, the decay fields, and the resulting evidence-quality flag. This is an inspection surface — it returns ALL rows for the strategy and never filters.

### refresh_strategy_evidence

Rebuild the disposable evidence cache from local backtest run artifacts. This is the surface's only write; it touches only the facade-owned cache (see Composition Guarantee).

| Parameter | Type | Default | Meaning |
|-----------|------|---------|---------|
| `manifest_path` | string | none | Path to a JSON manifest: an object `{"runs": [...]}` or a bare JSON array of run specs |
| `runs` | array | none | Inline run specs, same shape as the manifest's `runs` array |

Exactly one of `manifest_path` or `runs` is required — supplying both or neither is an error. Each spec is `{strategy_id, run_dir, position_size?}`: a non-empty `strategy_id` (the catalogue identity the evidence belongs to), the `run_dir` of a reproducible backtest run, and an optional `position_size` passed through to the harness. Every entry is hard-gated and path-contained (see Populating & Refreshing Evidence); failing entries are skipped with a stable reason — `hard-gate:*` or `path-outside-allowed-roots:` — while the rest still process. The envelope reports `{status, runs, strategies, rows, skipped}`.

## Evidence Row Contract

Every row is self-describing — the metadata travels with