zl3311/alpha-mining / .cursor/skills/mining-session
mining-session
VerifiedMaster orchestrator for alpha mining sessions. Entry point for both cloud automation and local manual use. Reads state, selects adaptive strategy, chains other skills. Trigger on: session start, daily automation, mine, alpha mining, start mining, run session.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.7 KB |
SKILL.md
View on GitHub---
name: mining-session
description: >-
Master orchestrator for alpha mining sessions. Entry point for both cloud
automation and local manual use. Reads state, selects adaptive strategy,
chains other skills. Trigger on: session start, daily automation, mine,
alpha mining, start mining, run session.
---
# Mining Session — Master Orchestrator
This is the entry point for every alpha mining session. Read this skill first;
it chains all other skills in the correct order.
## Session Start Protocol
1. Read THIS skill completely before doing anything else.
2. Determine whether this is a **cloud automation** or **local manual** session.
3. **Sync to latest `main` BEFORE branching** (mandatory for cloud, strongly
recommended for local):
```bash
git fetch origin && git checkout main && git pull --ff-only
```
This guarantees the experiment counter, the submitted book (`data/book/`), and
the self-corr baseline are current. Skipping this is what caused duplicate
rediscovery and a frozen experiment counter (every run re-branched from stale
state and re-found the same families). If `pull --ff-only` fails, stop and
surface the conflict rather than proceeding from stale state.
4. Assign a session ID (see format below) — derive `NNN` from the freshly-synced
`data/sessions/` so the counter actually advances.
5. **Create the session directory now** (Phase 0.5, do not defer to recording):
create `data/sessions/YYYYMMDD-NNN/meta.md` with at least `id`, `date`,
`strategy` (best guess, update later), and `trigger`. This guarantees an
audit trail even if the session is interrupted. Append to it as you go.
6. Chain through the workflow in order. The workflow starts with context-gather
(Phase 0), then applies the adaptive strategy selection (next section) to
choose a mode, then continues through signal generation and beyond.
## Adaptive Strategy Selection
After reading context (via `context-gather` skill), select a strategy using this
decision tree evaluated top-to-bottom — first match wins:
```
READ data/knowledge/opportunities/ (ignore type: submit-candidate files —
those are the submission queue, not ideas)
└─ High-priority hypothesis/idea items exist?
YES → HYPOTHESIS mode (test the opportunity)
CHECK: Has the agent run EXPLORE mode in the last 3 sessions?
└─ NO → EXPLORE mode (novel templates and cross-family interactions)
(Book is near saturation; novel structures are the highest-value use
of budget. See data/knowledge/rules/novelty-required.md.)
CHECK multiple gate-passers from different families
└─ 2+ gate-passers from UNEXPLOITED distinct mechanism families?
YES → RECOMBINE mode (crossover blending of novel combos)
QUERY HF server for new gate-passers (via hf-server skill)
└─ New gate-passer from a GENUINELY NEW mechanism family
(not IV-spread, not analyst revision, not fundamental blend)?
YES → EXPLOIT mode (directed mutation of the gate-passer)
CHECK existing gate-passers with BRAIN check failures
└─ Gate-passer exists but fails one or more BRAIN checks?
YES → REFINE mode (targeted fix for the specific failure)
DEFAULT → EXPLORE mode
```
**Key change from prior behavior**: EXPLORE and RECOMBINE now take priority over
EXPLOIT. The book is saturated with known pattern families. EXPLOIT should only
trigger for genuinely novel gate-passers from unexplored mechanism families —
NOT for more IV-spread or fundamental-blend variants.
## Workflow Chain
For every session, regardless of mode, execute these phases in order:
1. **Context Gather** — Read and execute `.cursor/skills/context-gather/SKILL.md`.
This produces a state assessment and confirms the strategy.
2. **Signal Generation** — Read and execute `.cursor/skills/signal-generation/SKILL.md`
with the chosen strategy mode. This produces candidate expressions.
3. **Submit Candidates** — Submit expressions to the HF server:
```bash
uv run python3 scripts/hf_submit.py --expressions "expr1" "expr2" \
--priority 5 --tags <session_tag> <batch_tag>
```
Then poll the batch to completion with the canonical poller (do NOT write
ad-hoc heredoc poll loops):
```bash
uv run python3 scripts/hf_poll.py --tag <session_tag>
```
4. **Result Analysis** — Read and execute `.cursor/skills/result-analysis/SKILL.md`.
This produces verdicts on each candidate AND, for any SAFE/RISKY candidate,
labels it on the BRAIN platform via `scripts/brain_metadata.py` (the HF queue
path leaves alphas unlabeled otherwise) and records a `status: PENDING`
`data/book/<id>.md` entry.
5. **Iterate or Stop** — If a SAFE/RISKY candidate already meets the session's
grade target, STOP and proceed to recording (satisficing — see AGENTS.md).
Otherwise, if budget remains AND the improvement trend continues (at least
one gate-passer in this round OR metrics improved over last round), return to
step 2 with updated context (winners inform the next generation).
6. **Record** — Read and execute `.cursor/skills/experiment-reporting/SKILL.md`.
This creates session files, updates knowledge, and opens a PR.
7. **Cleanup** — After the PR is created, the `experiment-reporting` skill's
Step 6 handles switching back to `main` and restoring any stashed changes.
Verify the repo is on `main` with a clean working tree before ending the session.
## Cloud vs Local Differences
| Aspect | Cloud Automation | Local Manual |
|--------|-----------------|--------------|
| Budget cap | 100 simulations per run | No hard cap (human decides) |
| End-of-session | Auto-PR (draft, never merged) | Human decides when to stop |
| BRAIN submission | NEVER submit — provide platform URLs only | Human may submit via platform URL |
| Self-corr check | Read `self_corr` from server (`hf_query --gate-passers`) | `pnl_correlation.py --vs-book` (direct BRAIN PnL) |
| Job tagging | `daily_YYYYMMDD` + batch tags | Session ID + descriptive tags |
| Trigger | Noon PT daily Cursor Automation | Human invokes skill or starts chat |
| Iteration limit | Max 5 rounds or budget exhausted | No limit |
## Session IDs
Format: `YYYYMMDD-NNN` where NNN is a zero-padded 3-digit counter.
To assign the next ID:
1. List existing directories in `data/sessions/`.
2. Filter for entries matching today's date prefix `YYYYMMDD-`.
3. Take the highest NNN found for today, increment by 1.
4. If none exist for today, start at `001`.
Example: if `data/sessions/20260603-001/` exists, the next is `20260603-002`.
## Stop Conditions
Terminate the session (proceed to recording phase) when ANY of these is true:
- **Viable candidate found** (DEFAULT for autonomous sessions): A SAFE or RISKY
candidate exists that meets the user's grade threshold (e.g., EXCELLENT+). The
session goal is to find ONE viable candidate, not the best possible one. Once
found, proceed immediately to recording/PR. Only continue iterating if the user
explicitly requested multiple candidates or specified a budget to exhaust.
- **Budget exhausted**: simulation count >= budget cap
- **Diminishing returns**: 3 consecutive rounds with zero gate-passers
- **Family blocked**: 3+ variants of the same expression family hit the SAME
BRAIN check failure (e.g. `CONCENTRATED_WEIGHT`). Stop mutating that family
and pivot to a structurally different template — do not keep burning sims on
a structural block. (Lesson from 20260604-001: `group_neutralize(IV spread)`
was EXCELLENT but always failed CONCENTRATED_WEIGHT + SUB_UNIVERSE across all
variants; the `zscore(ts_mean(...))` template broke through.)
- **Exploration complete**: all planned directions have been tested
- **Explicit human stop**: user says to stop (local mode only)
- **Clock limit**: cloud automation has been running > 45 minutes
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |