Stockbee Setup Fluency Trainer

Build and maintain a model book for Stockbee-style Momentum Burst setups. This skill turns daily screener candidates into structured study records, updates them after the 3-day and 5-day windows mature, and summarizes which setup features are working or failing.

When to Use

• User wants to study Stockbee Momentum Burst setups systematically
• User asks to build a model book from stockbee-momentum-burst-screener output
• User wants to review failed candidates, missed trades, or A/B setup quality
• User wants 3-day / 5-day forward returns, MFE, MAE, and stop-hit outcomes
• User wants to improve setup recognition before increasing position size
• User asks which Stockbee tags should be promoted, downgraded, or filtered

Prerequisites

• Python 3.10+
• A stockbee-momentum-burst-screener JSON report, or compatible candidate JSON
• Optional: FMP API key for outcome updates when offline OHLCV JSON is not supplied
• Recommended local state path: state/stockbee/model_book.jsonl

Workflow

Step 1: Ingest Momentum Burst Candidates

Run after the Stockbee Momentum Burst screener has produced a JSON report.

python3 skills/stockbee-setup-fluency-trainer/scripts/build_model_book.py ingest \
  --screener-json reports/stockbee_momentum_burst_YYYY-MM-DD_HHMMSS.json \
  --model-book state/stockbee/model_book.jsonl \
  --output-dir reports/

Use --include-rejects when intentionally building a negative-example set. Otherwise rejected candidates are skipped.

Step 2: Update 3-Day and 5-Day Outcomes

Use FMP:

python3 skills/stockbee-setup-fluency-trainer/scripts/build_model_book.py update \
  --model-book state/stockbee/model_book.jsonl \
  --horizons 3,5 \
  --output-dir reports/

Use offline OHLCV JSON:

python3 skills/stockbee-setup-fluency-trainer/scripts/build_model_book.py update \
  --model-book state/stockbee/model_book.jsonl \
  --prices-json data/daily_ohlcv.json \
  --horizons 3,5 \
  --output-dir reports/

The update step records:

• Forward close return for each horizon
• MFE and MAE over each horizon
• Stop-hit status and first stop-hit date
• Outcome tags such as STRONG_WINNER, WORKED, FAILED_STOP, FAILED_FADE, CHOPPY_FAILURE, or NEUTRAL

Step 3: Summarize Cohorts

python3 skills/stockbee-setup-fluency-trainer/scripts/build_model_book.py summarize \
  --model-book state/stockbee/model_book.jsonl \
  --group-by rating,primary_trigger,setup_tags \
  --min-sample 5 \
  --output-dir reports/

Review the generated Markdown and JSON reports. Treat rule_candidates as evidence prompts, not automatic rule changes.

Step 4: Convert Evidence Into Practice

For cohorts with enough examples:

• Promote tags with high win rate, positive 5-day expectancy, and acceptable average MAE
• Downgrade or filter tags with weak 5-day expectancy, frequent stop hits, or repeated fade failures
• Inspect representative charts manually before changing trade rules
• Log accepted lessons in trader-memory-core or the monthly review process

Model Book Fields

Each JSONL record includes:

• record_id, symbol, setup_date, primary_trigger
• rating, setup_score, setup_tags
• entry_reference, stop_reference, risk_pct_to_stop
• human_label, human_decision, human_notes
• outcomes.3d and outcomes.5d
• overall_outcome, matured, raw_candidate

Interpretation Rules

• STRONG_WINNER: 5-day close return >= 8% or MFE >= 12%, with no stop hit
• WORKED: 5-day close return >= 4% or MFE >= 6%, with no stop hit
• FAILED_STOP: Stop was touched within the horizon
• FAILED_FADE: Forward return <= -2% without a recorded stop hit
• CHOPPY_FAILURE: Adverse excursion was large and forward progress was poor
• NEUTRAL: No decisive follow-through or failure
• PENDING: Not enough future bars yet

Output

• state/stockbee/model_book.jsonl - Durable setup model book
• stockbee_setup_fluency_ingest_YYYY-MM-DD_HHMMSS.json/md
• stockbee_setup_fluency_update_YYYY-MM-DD_HHMMSS.json/md
• stockbee_setup_fluency_summary_YYYY-MM-DD_HHMMSS.json/md

Resources

• references/model_book_schema.md - JSONL schema and lifecycle states
• references/outcome_tags.md - Outcome classification and tag definitions
• references/review_workflow.md - Daily, 3-day, 5-day, and monthly review routine

Shared FMP client

Live FMP access uses the bundled generated scripts/fmp_client.py, loaded only when an FMP run starts, so offline modes still work without requests. CLI key/environment precedence, the API-call budget and successful output shapes are preserved. Requests use stable endpoints only; a denied, empty or failed stable request does not fall back to retired v3 URLs. The shared client masks raw and URL-encoded key echoes, retries malformed JSON once, and retries a 429 at most once, after a 60-second wait, before stopping on a repeated rate limit.

If every requested symbol fails at the transport level, update exits 1 and leaves the model book unchanged instead of stamping each record missing_prices.