📖 How It Works — Stock Watch Guide

Plain-language guide to the research pipeline, scoring logic, and what every pick means

← Back to Reports
Pipeline Discovery Scoring Technicals Macro Pick Types Email Guide Risk Rules Architecture WatchlistseToro Glossary
🗺️

The Big Picture — What Happens Every Hour

Three skills run in sequence every hour across 8 phases. Think of it as a three-stage funnel: cast wide, score everything, deliver the best.

Skill 1
🔍 Discovery
Find candidates
▶
Skill 2
📊 Research & Score
Rank candidates
▶
Skill 3
📬 Publish Report
Email + GitHub + Log
PhaseSkill / SectionWhat it doesFrequency
1 — INITSTEP 0ALoad watchlist.json + etoro-instruments.json from GitHub; fetch eToro live prices via Chrome MCPEvery run
2 — GEOSTEP 0A-GEO3 searches → Geopolitical Briefing above Macro SnapshotEvery run
3 — DISCOVERasx-global-discoveryHomepage scrapes + keyword searches → candidate poolEvery run
4 — PRICE DATASTEP 0, 0B, 0CLive prices, AUD/USD, BTC/VIX risk signal, RSI/SMAEvery run
5 — ENRICHSTEP 0B-ii, 0B-iii, 0FFundamentals, advanced technicals, global news — daily cacheOnce/day (cached)
5 — FEEDSSTEP 0D (tiered T1/T2/T3)T1 always · T2 if pool thin · T3 if pool very thinEvery run
6 — SCORESTEP 0E + 0IScore all candidates → ranked ASX + Global poolsEvery run
7 — PICK + REPORTSTEP 1, 2, 3Select 3 ASX + 3 Global picks, write reportEvery run
8 — PUBLISHpublish-report skillemail-builder.py → Gmail → GitHub Pages → watchlist-status.jsonEvery run
30+ sources scanned
All markets, all signals
▼
~20–30 candidates found
Signal-triggered only
▼
Scored & ranked
0–7+ weighted model
▼
6 picks selected
3 ASX · 3 Global
🔍

Skill 1 — Discovery: Finding Candidates

Before picking anything, the system casts a wide net across 30+ sources. It never searches for specific companies — it searches for signals and lets candidates emerge. This prevents confirmation bias.

📰 ASX News
StockheadSmall CapsMotley Fool AUDiscovery Alert
🩳 Short Interest
shorted.com.aufintel.ioCBOE AU (daily)
⚡ Breakout Scanners
SwingTradeBot ASXMarketIndex breakoutsRSI oversold scans
📊 Analyst Upgrades
BenzingaMarketBeatTipRanksGoldman / MS / UBS
🗣️ Community
HotCopper (ASX forum)Reddit r/ASXbetsReddit r/stocks
🌏 US / Global
Yahoo Finance gainersBenzinga upgradesfinviz.com news
🔒 Pro Signals (daily)
Unusual Whales (options)OpenInsider (cluster buys)Capitol Trades (Congress)
📡 RSS Feeds
Stockhead feedMotley Fool AU feedReuters Business
Why no company names in search queries? Searching for a stock you already know only confirms what you already believe. Signal-first discovery finds what you don't know yet — the stocks about to move before you heard about them.
Tiered news feeds (T1 / T2 / T3): The 32 news feeds now run in priority order. T1 (Stockhead, SDU, Discovery Alert, ASX Announcements) always runs. T2 runs only if the candidate pool is thin (<10 ASX or <4 Global). T3 runs only if the pool is very thin. This skips unnecessary fetches on busy market days.
📊

Skill 2 — The Scoring Model (0 to 7+)

Every candidate gets a Base Score (1–5) based on catalyst strength, then Bonuses and Penalties adjust it. Minimum score of 3.5 required to become a pick.

Base Score — Catalyst Strength

5
Major catalyst TODAY — stock hasn't moved yet
Best entry: ASX announcement just filed, deal signed this morning, upgrade just published. Market hasn't priced it in.
4
Strong catalyst — upgrade, deal, or earnings beat
Fresh analyst upgrade, new contract announced, earnings above expectations. Confirmed, not speculative.
3
Volume-backed move with supporting news
Unusual volume spike AND a reason for it — sector news, macro tailwind, small ANN. Both signals together.
2
News only — no volume confirmation
Interesting catalyst but nobody is buying yet. Wait for volume to confirm before entering.
1
Volume only — no catalyst found
Something is happening but we can't explain it. Possible pre-announcement leak. Flag as ❓ INVESTIGATE.

✅ Bonuses (up to +2.0 total)

+1.0
ASX announcement today and price not yet moved 5%+
+1.0
Analyst upgrade or initiation published today
+0.5
Earnings within 5 days with bullish prior history
+0.5
Mentioned in 3+ independent sources in 24h
+0.5
Tier-1 bank upgrade (Goldman, MS, UBS)
+0.5
Unusual options sweep (bullish — big bets placed)
+0.5
Director / insider confirmed buying on market
+0.5
Above both SMA50 and SMA200 (healthy uptrend)
+0.5
5-day RSI rising + price above SMA50
+0.5
Sector commodity rising (iron ore, copper, gold…)

❌ Penalties

−1.0
Already up >15% today — chasing is dangerous
−1.0
Analyst downgrade or profit warning issued
−0.5
RSI >70 AND still rising — overbought
−0.5
RSI falling + price below SMA50 — deteriorating
−0.5
Supertrend signal = DOWN
−0.5
Analyst target already achieved — thesis is stale
−0.5
VIX >25 — broad market fear, reduce conviction
📈

Technical Indicators — Plain Language

RSI (Relative Strength Index)
Measures momentum on a 0–100 scale. Think of it as a speedometer — how fast is the stock moving?
40–65 rising ✓ >70 overbought <30 falling
SMA 50 (50-day Average)
The average share price over the past 50 days. Being above it means the medium-term trend is up.
Price above ✓ Price below ✗
SMA 200 (200-day Average)
The long-term average. Above = confirmed uptrend. Below = bear territory. The "golden cross" (SMA50 crossing SMA200 upward) is a major bull signal.
Above = uptrend ✓ Below = bear zone
Supertrend
A single UP or DOWN signal based on price + volatility bands. Simpler than RSI — it just tells you the trend direction.
UP + ADX>25 ✓ DOWN = avoid
ADX (Average Directional Index)
Measures trend strength, not direction. A weak trend in either direction means choppy trading — hard to profit from.
>25 strong trend <20 = no trend
Volume Ratio
Today's volume vs the 20-day average. 3× means 3 times the normal amount of shares are changing hands — something is happening.
>3× unusual ✓ <0.5× quiet

How Entry / Target / Stop are set

FieldHow it's calculatedWhy it matters
Entry ZoneCurrent price ±1–2% (limit order range)Set a limit order — never chase with a market order
TargetAnalyst consensus price target or next resistanceWhere to sell when right
Stop LossBelow key support (recent swing low or SMA50)Where to exit when wrong — non-negotiable
R:R Ratio(Target − Entry) ÷ (Entry − Stop)Must be ≥1.5 to qualify as a pick. 2.0 = risk $1 to make $2.
🌍

Macro Layer — What Shapes Every Run

Before individual stocks are scored, the system reads the macro environment. Commodity prices, sector ETFs, and geopolitical signals all feed into score bonuses and penalties.

⛔ BTC Risk-Off Signal

  • BTC drops >3% in 24h →
  • RISK-OFF banner fires
  • Reduce all positions 25–30%
  • Tighten stops to entry
  • Avoid crypto-correlated names
  • Prefer gold, healthcare, defensives

🏭 Commodity Basket (checked every run)

  • Iron ore >$120/t → BHP, RIO, FMG ↑
  • Copper >$9,500/t → copper miners ↑
  • Gold >$3,500/oz → EVN, NST, NCM ↑
  • Oil >$75/bbl → WDS, STO ↑
  • Uranium >$85/lb → PDN, BOE, LOT ↑

📉 ASX Sector ETFs

  • XMJ — Materials (iron ore, copper)
  • XEJ — Energy (oil, LNG, coal)
  • XFJ — Financials (rate sensitive)
  • XHJ — Healthcare (approvals)
  • XTEK — Technology (AI/cloud)
Rising sector → +0.3 bonus to all stocks in it. Falling sector → −0.3 penalty.

🌐 Geopolitical & Policy

  • China tension ↑ → AUD, iron ore risk
  • RBA rate cut → REITs, financials ↑
  • US Fed hawkish → AUD falls, risk-off
  • AUKUS deal → EOS, MEI, DRO ↑
  • Trade tariffs → supply chain exposure
⚡ Daily API cache: Alpha Vantage (25 calls/day), Mediastack (100 calls/month), and Twelve Data (800 credits/month) are called once per day only. The first run writes results to /tmp/daily-cache-YYYY-MM-DD.json. All subsequent hourly runs read from cache — no wasted quota.
🎯

The Three Pick Timeframes

⚡
DAY Pick
Same session or next open
Fast-moving catalyst: short squeeze, gap-and-go, pre-market announcement. Set a tight stop. Exit by end of session if not at target.
📅
WEEK Pick
1–5 trading days
Analyst upgrade, upcoming earnings, deal announced but not fully priced yet. Hold through the week and re-assess Friday.
📈
LONG Pick
Weeks to months
Structural thesis: sector rotation, undervalued vs analyst consensus, AI/commodity megatrend. Patient entry, wider stop, hold through noise.

Pick badge meanings

🆕 NEW First time this ticker appears as a pick
HOLD Was a pick last run — thesis still intact
⚠️ Runner-up Promoted due to diversity rule — lower conviction
⛔ RISK-OFF BTC triggered — reduce size 25–30%
PRE-MOVE Catalyst today, market hasn't priced it yet — best entry
SHORT-SQUEEZE High short interest + catalyst = potential sharp move
FMP+Vol Confirmed by FMP screener AND volume leaders — double signal
The Diversity Rule: The same ticker can never appear more than once across the 3 ASX or 3 Global slots. If the top scorer would fill all three slots, the runner-up is promoted and labelled accordingly. Concentration in a single name kills returns.
📬

Reading the Email Report

The same locked template is filled in every single run — the layout never changes.

⚠️

Risk Management — Built In

RuleTriggerAction
BTC Risk-OffBTC drops >3% in 24hReduce all position sizes 25–30%, tighten stops, avoid crypto-correlated names
VIX SpikeVIX >25Reduce all conviction scores by 0.5 — fewer picks qualify
Anti-ChaseStock already up >15% today−1.0 score penalty — almost always excluded
Stale CatalystCatalyst >7 days oldScore reduced — old news doesn't move markets
Target AchievedStock already at analyst PTMarked stale — upside exhausted, not selected
Diversity RuleSame ticker in 2+ slotsRunner-up promoted — forces diversification
Source Quality<10 live sources in a runPicks labelled with ⚠️ — treat entry zones as wider

Source health indicator (in the log)

  ✅ = Live data fetched this run
  ⚠️ = Fallback used (cached or web search)
  ❌ = Source unavailable — not used this run

15+ ✅ = high quality run. Below 10 ✅ = more fallback data — use wider entry zones.

🔧

Under the Hood — Skill Architecture

The system uses four modular skills. Each handles a distinct phase of the pipeline and can be run or re-run independently.

🔍 asx-global-discovery
Phase 3 — Discover: 15 homepage scrapes + 35 keyword searches → candidate pool. Always runs first. Outputs ranked table + sector heat map that feeds directly into scoring. ~245 lines.
📊 hourly-global-stock-picks
Phases 2, 4, 5, 6, 7: Geopolitical briefing → price data (EODHD + Finnhub + smallcaps) → enrichment (AV/Mediastack/Twelve Data — daily cache) → tiered news feeds → scoring → pick selection → report writing. ~1,735 lines · report structure in report-template.md.
📬 publish-report
Phase 8 — Publish: Reads /tmp/email-data.json → email-builder.py fills email-template.html → Gmail draft → publish-report.py pushes HTML to GitHub Pages → writes watchlist-status.json → SMS (paused). Can be re-run independently to retry a failed send. ~148 lines.
👁️ watchlist-monitor
Anytime — Quick check: Fetches live prices, RSI, SMA position, volume, and last-researched tier for every ticker in watchlist.json + etoro-watchlist.json. No pick generation. Runs in under 3 minutes. Use when you say "how is my watchlist doing?" ~178 lines.
📲 etoro-watchlist-sync-skill — once per day, scheduled
Scheduled Claude skill — runs automatically once per day. Uses Chrome MCP JS fetch to bypass the sandbox HTTPS proxy and call the eToro API with auth headers natively.

Writes two files to GitHub:
  • etoro-instruments.json — instrument IDs only (no prices); read by hourly skill to batch-fetch live rates
  • etoro-watchlist.json — full positions with prices; displayed on GitHub Pages
Does not modify SKILL.md or any skill file — ever.
Supporting files:  email-template.html (locked layout) · report-template.md (report structure, on GitHub) · email-builder.py (fills template from JSON) · publish-report.py (pushes to GitHub) · etoro-watchlist-sync-skill.md (daily scheduled skill) · watchlist.json (monitoring tickers, GitHub) · etoro-instruments.json (eToro IDs — no prices) · etoro-watchlist.json (eToro positions + prices) · watchlist-status.json (per-ticker tier/score, written each run)
Why email-builder.py? Every run that writes its own HTML produces a different layout — breaking formatting for recipients. One locked template, substituted each run via JSON data. The structure is physically impossible to drift between runs.
📋

Watchlists — Three Layers Explained

The system uses three separate watchlist layers. They serve different purposes and are fetched in different ways — none of them automatically override the signal-first discovery process.

1️⃣
Fixed Monitoring List — checked every run
watchlist.json on GitHub · EODHD + Finnhub + smallcaps.com.au

A curated list of tickers stored in watchlist.json in the Stock-Soup GitHub repo — no hardcoded tickers in the skill file. Every run, the system fetches live prices, RSI/SMA technicals, and recent news for each. They enter the scoring pool on equal footing with newly discovered candidates — no automatic pick priority. The watchlist is loaded fresh each run so adding/removing tickers takes effect immediately without editing the skill.

VTMPDNIELTLXEOSNTUDYLDROA2MSGHWTCPLTR
What's fetched each run
✅ Live price via EODHD batch API
✅ RSI + SMA50/200 via Yahoo Finance chart API
✅ Recent news via EODHD news API
✅ Smallcaps.com.au page (RSI, volume, narrative)
✅ SimplyWallSt discount % (daily)
How they become picks
They compete on score — same 0–7+ model as every other candidate.

A watchlist stock with no catalyst scores ~2/5 and won't be picked.
A watchlist stock with a fresh upgrade scores 4.5+ and wins a slot.
To add a ticker to the fixed list: edit watchlist.json in the Stock-Soup GitHub repo. The next hourly run will pick it up automatically — no skill file changes needed.
2️⃣
eToro Integration — daily sync + live hourly prices
etoro-instruments.json + etoro-watchlist.json on GitHub · automatic scheduled sync

The eToro integration runs in two separate stages — a daily ID sync and a live price fetch every hourly run.

⏱ Stage 1 — Daily Sync (scheduled task)
What it does
1. Calls eToro API → fetch all watchlists
2. Compare vs current JSON → log changes
3. Write etoro-instruments.json (IDs only)
4. Write etoro-watchlist.json (+ prices)
5. Push both files to GitHub
Why two files?
etoro-instruments.json has IDs only — no prices. The hourly skill reads this to know which instruments to fetch.

etoro-watchlist.json has full data + prices — shown on GitHub Pages watchlist view.
Chrome MCP required — here's why: eToro's API requires custom auth headers (x-api-key, x-user-key). Python/curl can't send them through the sandbox proxy. Chrome's JS fetch() sends them natively — no proxy involved.
🔄 Stage 2 — Live Prices Every Hourly Run
1. Read etoro-instruments.json from GitHub
2. Batch IDs (20 per call — eToro API limit)
3. Fetch live rates via Chrome MCP JS fetch
4. Pass as ETORO_LIVE_PRICES to email-builder.py
5. Auto-injected into External Watchlists section
In the report
Appears as EXTERNAL WATCHLISTS section (below Watchlist Notables). Shows all 62 instruments grouped by watchlist, with live price column. Read-only — not editable in reports. Prices show "—" if eToro API is unreachable.
To update after adding/removing eToro positions: the daily scheduled sync handles this automatically. If you need an immediate update, ask Claude to "run the eToro watchlist sync" — it will invoke etoro-watchlist-sync-skill.md.
3️⃣
Browser Watchlist — personal reminder layer
Saved in browser localStorage · visible on the archive page · not read by Claude

The chip UI on the archive page lets you save tickers locally in your browser. Chips are colour-coded by the tier assigned in the last hourly run (watchlist-status.json written by publish-report.py). These are stored in localStorage — they persist across refreshes but are not read by Claude.

What it does
✅ Visual reminder of tickers you're watching
✅ Survives browser refresh and app restart
✅ Colour-coded by exchange (ASX / US / Global)
✅ Add / remove instantly, no login needed
What it doesn't do
❌ Not sent to Claude automatically
❌ Not fetched for prices or news
❌ Not synced across devices or browsers
❌ Won't influence pick selection
To get Claude to actually research a ticker, use the Request Ticker for Research Queue form — that creates a GitHub issue and gets the ticker added to the Layer 1 fixed list in SKILL.md.

Summary

LayerWhere storedFetched by Claude?Influences picks?How to update
1 — Fixed listwatchlist.json (GitHub)✅ Every run✅ Competes equallyEdit watchlist.json in GitHub repo
2 — eToro syncetoro-instruments.json + etoro-watchlist.json (GitHub)✅ IDs loaded Phase 1; live prices fetched hourly✅ If catalyst exists + shown in External WatchlistsAutomatic daily scheduled task (or ask Claude to run sync)
3 — Browser chipsBrowser localStorage❌ Not read❌ NoAdd/remove on archive page
📚

Glossary

ASX
Australian Securities Exchange — where Australian shares trade (opens 10am AEST Mon–Fri)
NYSE / NASDAQ
US stock exchanges — NYSE is traditional blue-chips, NASDAQ is tech-heavy
RSI
Relative Strength Index — 0–100 momentum gauge. Think of it as a speedometer. 70+ = too fast (overbought), 30− = too slow (oversold)
SMA 50 / 200
Simple Moving Average — average price over 50 or 200 days. Being above your SMA50 is like running faster than your usual pace — positive momentum
Short interest
% of shares borrowed and sold by people betting the price will fall. High short interest = many bears. When they're wrong, they all rush to buy at once — that's a squeeze
Short squeeze
When a stock unexpectedly rises — short sellers must buy to close their positions, which pushes the price even higher, fast
Catalyst
The specific event that causes a stock to move: earnings beat, new contract, analyst upgrade, FDA approval, regulatory clearance, insider buy
PRE-MOVE
A catalyst just fired but the stock price hasn't reacted yet. Best entry window — market is slow to price in new information
R:R (Risk:Reward)
How much you could make vs how much you risk. 2.0 = risk $1 to potentially make $2. System requires minimum 1.5 to qualify as a pick
Entry zone
The price range to buy at. Always set as a limit order — never chase with a market order above the zone
Stop loss
The price to exit if wrong. Non-negotiable — set it at the moment you enter the trade
Day pick ⚡
Trade designed to be entered and exited within the same ASX or US session
Week pick 📅
Hold for 1–5 trading days — re-assess at end of week
Long pick 📈
Structural thesis — hold for weeks to months through normal volatility
RISK-OFF ⛔
Market mood where investors sell risky assets and move to cash/gold. BTC dropping 3%+ is the system's trigger
VIX
The "fear index" — measures expected market volatility. Above 25 = fear. Below 15 = calm
AUD/USD
Exchange rate: how many US dollars one Australian dollar buys. Higher AUD = good for importing; lower = good for ASX export stocks
EODHD
End of Day Historical Data — the primary API for live ASX prices and AUD/USD each run
Finnhub
API for US/global stock quotes, analyst consensus ratings, and BTC price (risk-off signal)
FMP
Financial Modeling Prep — provides analyst grades, stock screener, and the economic calendar (run mandatory every session)
Supertrend
A technical indicator that gives a simple UP or DOWN direction signal based on price and volatility bands. Combined with ADX for trend strength
ADX
Average Directional Index — measures trend strength (not direction). Above 25 = strong trend. Below 20 = choppy market, hard to trade
etoro-instruments.json
The single source of truth for your eToro instrument IDs — written by the daily sync task, read by the hourly skill to batch-fetch live prices. No prices stored here (they're fetched fresh each run)
etoro-watchlist.json
Your full eToro positions including last-synced prices — pushed to GitHub and displayed on the GitHub Pages watchlist view
External Watchlists
Section in every report showing all your eToro positions with live prices, grouped by watchlist. Read-only — populated automatically by email-builder.py from etoro-instruments.json + live eToro rates
Win rate
Tracked by win-rate.py — the % of past picks that hit their price target vs were stopped out. Visible in Section 15B of every report
ASX + Global Stock Watch · Auto-generated market research · Not financial advice · Updated June 2026 · eToro integration: daily sync → etoro-instruments.json + live hourly prices via Chrome MCP