--- name: factor-mining description: Creates, validates, backtests, continues, retrieves, or summarizes one Quandora Factor and reads owned Factor families or history. Use when the user asks for Factor Mining authoring or reuse. Do not use for the Strategy eligible-factor pool or deep result diagnosis. --- # Quandora Factor Mining Follow [Connection and Security](../../references/connection-and-security.md) for automatic recovery and the once-per-session release check; preserve existing update authority. After a failed mutating call, follow [Failed mutations](../../references/failed-mutations.md). Follow [Research intent and evidence](../../references/research-workflows.md) for backtest/forward scope, capability-aware conclusions and authorization-preserving handoffs. Follow [Research notebook](../../references/research-notebook.md) to read prior research before deciding, write the hypothesis with each decision and record a conclusion after each result. This skill owns Factor Mining research creation, caller-owned Factor family/history reads, Factor backtests, and Factor Result Bundle delivery through the authenticated `quandora` connection. Route bare available/eligible/selectable Factor requests to `$strategy-building`; it calls only `list_eligible_strategy_factors`. Route deep diagnosis, comparison, or optimization of an existing Factor result to `$factor-analysis`; carry its chosen controlled experiment back here for creation and submission within the research goal. For named objects, follow [Name discovery](../../references/object-discovery.md) to resolve exact identities. Use [Research playbooks](../../references/research-playbooks.md) for goal-based call orders and similarity decisions. ## Tools Use only the minimum relevant subset: - Entry and discovery: `get_factor_mining_status`, `list_factor_mining_tasks`. - Reusable Factor reads: `list_owned_factor_families`, `get_factor_family_history`. - Research notebook: `get_research_context`, `list_research_notes`, `get_research_note`, `record_research_conclusion`. - Authoring and submission: `get_factor_plugin_contract`, then `submit_factor_research`, which creates the session, checks the contract, reads duplicate context, validates and submits. - Existing step sessions only: `create_factor_task_session`, `create_custom_factor_session`, `validate_factor_plugin`, `get_factor_dedup_context`, `submit_factor_backtest` finish a session created before this workflow; never start new research with them. - Run lifecycle: `continue_factor_backtest`, `wait_for_runs`. - Another horizon for an existing version: `run_factor_version`. - Existing reversal relationships (read only): `get_factor_reversal`. - Result delivery: `download_result_bundle` with `kind: "factor"` and the terminal job ID. - Approved semantics/diagnostics: `get_quandora_guidance`, `check_quandora_plugin_version`. Tool names in this Skill are canonical actions on the configured `quandora` MCP dependency. Let the host resolve its required server-qualified form. If an action is absent, do not invent an alias or use another service path. Use `check_quandora_plugin_version` only for a requested version diagnostic or a plausible package/server mismatch; never as a mandatory entry probe. ## Load Supporting Material Selectively - After routing to new Factor construction, load [Factor Plugin Authoring](references/plugin-authoring.md). - After obtaining the scoped contract for source construction, load [86-Field Research Contract Consumption](references/binance-intraday-contract.md). It explains how to consume the live per-field semantics and reviewed cross-field guidance without copying either registry into the Skill. - After submission, continuation, or an export request, load [Factor Run and Result Delivery](references/run-and-result-delivery.md). Do not load Result Bundle transport rules for a list/history-only request. ## Route First - Bare requests for available, eligible, or selectable factors in the Strategy factor pool exit to `$strategy-building` without calling a Factor Mining status or inventory action. - Caller-owned Factor Mining families, branches, versions, history, or prior Factor runs remain here. - New public-task or custom-factor work remains here. - Testing an existing owned Factor at another forward horizon remains here and follows [Test Another Horizon](#test-another-horizon), not authoring. For a normal creation workflow, call `get_factor_mining_status` once after routing. Do not call it for a completed list/history-only request when the relevant read is already available. ## Reuse and History Call `list_owned_factor_families` for caller-owned reusable Factor families; it is not the Strategy eligible pool. Use a supplied name or keyword as `query` and exact public status, availability, or task identity as `filters`; omit them only for a browse request. Show one bounded page and never hydrate every row. A failed list is not an empty inventory and does not authorize a history fallback. Choose one exact returned `factor_family_id` from the research context and candidates, then call `get_factor_family_history` with it. Record the reason in the decision's `research_note`: `hypothesis` for a new direction, `change_summary` otherwise. To narrow the `versions` or `runs` view to one immutable Factor, also pass that row's `factor_id`. Every history row names the Family `factor_family_id`, the immutable Factor `factor_id`, and a run `factor_run_id` (equal to its `job_id`). Default to `summary`; request only the needed `branches`, `versions`, or `runs` view. Preserve opaque IDs and page tokens exactly. Never substitute a job, run, plugin, session, Strategy admission, or cached identifier. History is read-only and does not authorize source editing or resubmission. A continuation keeps the same query, filters, archive mode, and page size and copies the returned opaque page token byte-for-byte. When controlled history/result semantics are needed, use `get_quandora_guidance` only with the known guide `operation.factor.history.read` or `operation.result.read` and only supported sections. Use `metric.backtest.grade` only for its capability semantics. Guidance never creates a tool input or mutation authority. ## Create and Backtest Read `get_research_context` with `stage: "factor"` first and decide whether this work improves an existing thread (exact parent `factor_version`) or starts a new direction. Write the note in the user's language and begin `hypothesis` with a one-sentence topic of at most 60 characters. Always include `references`: exact runs/versions used from context, history or similarity reads, including an existing Factor used to distinguish the new idea. Empty is valid only with no Quandora evidence; an uncovered idea does not make the evidence list empty. For public work, call `list_factor_mining_tasks`, show only exact returned task name and category, and keep `task_id` internal. Choose from the research context and returned candidates, and record why in the decision's `research_note` (`hypothesis` for a new direction, `change_summary` otherwise). Treat the selected public Task's returned research fields as one live research thesis for mechanism, feature, regime, risk, and target-behavior choices; do not reduce construction to name/category or copy those fields into this Skill. Submit with the exact selected task. For custom work, classification and construction follow [Factor Plugin Authoring](references/plugin-authoring.md). The public input is the canonical flat custom-session payload; never send a hand-built `task_payload`. After the contract exists: 1. author one complete inline `plugin.py` without local execution; 2. call `submit_factor_research` once with the task or custom fields, `source`, `filename`, the contract `schema_version` you authored against as `contract_version`, and a `research_note`; 3. when it returns `failed_step`, repair only that step's safe structured diagnostics and submit the corrected source again; report its returned duplicate evidence instead of resubmitting a near variant. A timeout or ambiguous mutation response is not proof of failure. Follow the returned `recovery_action` when present, otherwise [Failed mutations](../../references/failed-mutations.md). Never silently change the user's task, category, thesis, data, horizon, or source. A different horizon is a deliberate, recorded run of the same version. ## Test Another Horizon The forward horizon (`fwd_period`) is a run condition, not part of the Factor version. To test another horizon, read `get_research_context` with `stage: "factor"`, resolve the exact owned `factor_id` through [Reuse and History](#reuse-and-history), then call `run_factor_version` with that `factor_id`, the positive integer `fwd_period` and a `research_note` (no `relation` or `parent`): `hypothesis` says why that horizon should change the result, and `references` name the version's run being compared. It creates a new run of the same version. On an error follow its `recovery_action` ([Run and Result Delivery](references/run-and-result-delivery.md)); without one, follow Failed mutations: an identical call inside ten minutes returns the same run. Wait for `run.factor_run_id` and read it like any Factor run. Never upload the same source as an `improvement` to change only the horizon: the server rejects that upload and tells you to rerun the version. If `run_factor_version` is not in the tool list, tell the user that testing an existing version at another horizon is not available yet and stop; never upload source or submit another backtest instead. If it rejects the horizon, report that rejection. ## Reversal Requests QuantAI evaluates every Factor in the direction that made money in-sample, so a reversed Factor's card would match the original apart from the sign of IC, and Strategies use that evaluated direction automatically; reversal is retired, so never call a reversal command, even one the server still lists or the user authorizes. Submit a hand-negated plugin only as a genuinely new idea through the ordinary authoring workflow. `get_factor_reversal` with the immutable Factor ID only reads a relationship created earlier. ## Continue and Deliver `continue_factor_backtest` re-drives one exact known non-terminal run; it is not a read-only fetch. Use `wait_for_runs` to wait without re-driving, for example for several runs at once. Use the bounded continuation and Result Bundle rules in [Factor Run and Result Delivery](references/run-and-result-delivery.md). The canonical completed local output is `Quandora result/factor/.zip`. For authored factors, derive the slug from the exact accepted matching `FACTOR_TYPE` literals. For an existing reversed Factor, use the exact server-returned Factor type from history; if absent, use the safe returned bundle filename. When naming the export, never silently fall back to a generic `factor` slug. Never save the Factor ZIP in a Strategy directory. ## Final Response State the Factor name, safe run state, safe failure diagnostics if applicable, bundle state, and the exact verified local ZIP path when saved. After a terminal run, record a one- or two-sentence conclusion on that `factor_run` before answering; the server files it under the version with `run_id`. State the run's horizon, and report its nearest Factor and absolute value correlation, or the measured empty result or unavailable comparison. For a partial snapshot, state the exact omissions and their reasons. If the host cannot write, say that no verified ZIP was saved. Never expose task IDs in public task lists. Include a job/run handle only when it supports the requested continuation, recovery, export, or handoff. Never include tickets, download URLs, base64, or full plugin source in a general summary. Use the user's language for the answer while preserving tool names, schema fields, and returned identifiers exactly. ## Library Favorites For Factor/Strategy stars and folder-independent metadata, follow [Library Favorites](../../references/library-favorites.md).