# skills.md — Speculation Research System v1.0 System architecture, workflows, update cycles and limitations. Repo path: `D:\ClaudeProjects\bill-organiser\Speculations_Investing` Published at: `https://thejzl.com/Speculations_Investing/` Last reviewed: 28 July 2026 --- ## 1. What this system is A multi-agent research pipeline that runs once per day, scans public sources for speculative opportunities across ASX small/microcaps, US small/microcaps and alternative assets, then writes its findings into a static HTML page and an append-only history log. It produces **educational analysis with opinions**. It does not produce personalised financial advice and never states what should be bought or sold. --- ## 2. Sub-agent architecture The agents below are logical roles in a single daily workflow, not separate processes. Each has a defined input, output and failure mode. ### 2.1 Planning Agent - **Input:** the task, the current state of the repo, yesterday's history entries. - **Does:** decomposes the run into ordered steps, decides which sources are worth hitting today, sets the completeness bar for the run. - **Output:** an ordered task list with dependencies. - **Failure mode:** scope creep — scanning everything and finishing nothing. Mitigated by a fixed per-run budget of source queries. ### 2.2 Research Agent - **Input:** the day's source plan. - **Does:** searches news, forums, filings and trend trackers; extracts candidate opportunities; captures the specific catalyst and a citable source URL for each. - **Output:** candidate list with raw evidence and links. - **Failure mode:** citing promotional content as research. Mitigated by the source-tier rules in §5. ### 2.3 Sentiment Agent - **Input:** candidate list. - **Does:** assesses community tone across forums and social sources; separates *volume* of discussion from *direction* of tone; flags divergence between sentiment and price. - **Output:** a sentiment reading per candidate on a five-point scale (Fearful → Cautious → Neutral → Excited → Euphoric) plus a divergence flag. - **Failure mode:** mistaking loud minorities for consensus, and mistaking a ticker's own forum (structurally all holders) for the market. Mitigated by requiring at least two independent venues. ### 2.4 Narrative Agent - **Input:** candidate list plus the running narrative register. - **Does:** maps each candidate to a named narrative, places that narrative on the five-stage lifecycle (Latent → Emergent → Acceleration → Saturation → Decay), and tracks stage changes week over week. - **Output:** narrative register with stage, direction of travel, and first-logged date. - **Failure mode:** inventing a narrative to fit a stock. A narrative must be observable in at least three unrelated sources before it is registered. ### 2.5 Risk-Tiering Agent - **Input:** candidate plus liquidity, disclosure and structure data. - **Does:** assigns one of four tiers. - **Tier 1 — High risk, grounded narrative.** Real revenue or a real asset, verifiable disclosure, adequate liquidity. Can still halve. - **Tier 2 — Very high risk, hype-driven.** Listed and liquid but valued on a story about the future. Pre-revenue or thin revenue. 30–50% drawdowns are routine. - **Tier 3 — Extreme risk, low liquidity.** Microcaps, thin order books, serial dilution, wide spreads. Exit price is not the screen price. - **Tier 4 — Meme-level speculation.** The asset is attention itself. No cash flow, no asset, no disclosure obligation. Assume zero. - **Output:** tier plus the single reason it sits there. - **Failure mode:** tier drift — rating something Tier 2 because it is popular rather than because its structure improved. Tiers are set by structure, never by price performance. ### 2.6 Scoring Agent - **Input:** all of the above. - **Does:** scores each opportunity out of 100 across seven weighted dimensions. | Dimension | Weight | What a high score means | |---|---:|---| | Narrative strength | 20 | Coherent, externally driven, not company-manufactured | | Catalyst strength | 20 | Specific, dated, material, verifiable | | Sentiment | 15 | Constructive and building — not yet euphoric | | Risk tier | 15 | Lower tier scores higher (Tier 1 = 15 → Tier 4 = 0) | | Liquidity | 10 | Can be entered and exited at a sane spread | | Hype-cycle position | 10 | Early (Emergent) scores highest; Saturation scores near zero | | Information availability | 10 | Filings, disclosure and independent coverage exist | - **Output:** a 0–100 score and per-dimension breakdown. - **Important:** the score ranks *research interest*, not expected return, and explicitly does not constitute a recommendation. A high score on a Tier 4 asset still means "assume zero." - **Failure mode:** false precision. Scores are reported in bands of 5 and compared over time rather than treated as exact. ### 2.7 Repo Agent - **Input:** the assembled analysis. - **Does:** writes and updates `index.html`, `plan.md`, `skills.md`, `spec.md`, `history.md`; keeps the site header/nav consistent with the rest of thejzl.com; validates HTML structure; checks that every source link is well-formed and that internal links resolve to real files. - **Output:** committed files. - **Failure mode:** silent formatting drift. Mitigated by the integrity checklist in §7. ### 2.8 Daily Update Agent - **Input:** the schedule trigger. - **Does:** runs the full pipeline once per day — scan, extract, tier, score, write, log, and retire stale entries. - **Output:** an updated page with a new timestamp and new history rows. - **Retirement rules:** an opportunity leaves the active watchlist when its catalyst has passed, its narrative reaches Decay, its score falls more than 20 points from its logged entry score, or it has sat with no new information for 45 days. Retired entries stay in `history.md` forever. ### 2.9 Self-Evaluation Agent - **Input:** the finished run. - **Does:** checks the run against the brief — were all required sections updated, is every claim sourced, is the disclaimer present, are tiers justified, did anything get written without evidence. Revises before finishing. - **Output:** pass/fail per check; failures trigger a revision pass rather than a note. --- ## 3. Daily workflow ``` 06:30 AWST Trigger │ ├─ 1. Planning Agent → today's source plan ├─ 2. Research Agent → candidates + evidence + links ├─ 3. Narrative Agent → map to narratives, update lifecycle stages ├─ 4. Sentiment Agent → tone reading + divergence flags ├─ 5. Risk-Tiering Agent → Tier 1–4 with justification ├─ 6. Scoring Agent → 0–100 + breakdown ├─ 7. Repo Agent → rewrite index.html, append history.md ├─ 8. Self-Eval Agent → integrity checks, revise if failed └─ 9. Publish → publish.py --push → live on thejzl.com ``` Publishing runs only after every integrity check passes. A failed check is fixed and re-checked, never published with a note attached. Run budget: roughly 12–20 source queries, targeting 3–8 new or materially changed opportunities per day. A day with nothing new is a valid outcome and is logged as such — manufacturing opportunities to fill a page is the single most damaging thing this system could do. --- ## 4. Source coverage **ASX small/microcaps** ASX company announcements, HotCopper (sentiment only, never evidence), r/ASX_Bets and r/ASX, Stockhead, Proactive Investors, Livewire, Small Caps, broker note summaries. **US small/microcaps** SEC EDGAR filings (8-K, S-1, 424B), r/wallstreetbets and r/stocks mention trackers, Benzinga, options-flow commentary, IPO and lock-up calendars. **Alternative assets** Prediction-market volume data (Kalshi, Polymarket), collectibles indices and auction results, graded-card population reports, pre-IPO secondary commentary, emerging-market flow notes. **Cross-cutting** Macro and policy announcements that create narratives — export controls, subsidy programs, defence budgets, rate decisions, regulatory rulings. --- ## 5. Source tiering Not all sources carry equal weight. Each claim inherits the tier of its weakest supporting source. - **Tier A — Primary.** Filings, exchange announcements, regulator publications, exchange volume data. Can support a factual claim on its own. - **Tier B — Reputable secondary.** Established financial media, named analysts with disclosed positions, research houses. Can support a factual claim with attribution. - **Tier C — Sentiment only.** Forums, social platforms, anonymous commentary. **Never used as evidence for a fact** — only as evidence of what people are saying. - **Tier D — Excluded.** Sponsored coverage, paid research, promotional newsletters, anonymous price targets. Logged and ignored; presence of Tier D activity around an asset is itself a negative signal and is noted. --- ## 6. Output formats | File | Format | Update cadence | Purpose | |---|---|---|---| | `index.html` | Static HTML, site-matched theme | Daily | Guide + live watchlist | | `plan.md` | Markdown | On material change | Beginner's plan | | `skills.md` | Markdown | On architecture change | This document | | `spec.md` | Markdown | Weekly review | Category deep dive + frameworks | | `history.md` | Markdown, append-only | Daily | Permanent record of every flagged idea | | `publish.py` | Python 3, stdlib only | Infrastructure | Scoped commit + push to GitHub Pages | `index.html` is deliberately dependency-free: no build step, no framework, no external data calls. It is a static file so that it renders identically from GitHub Pages, from disk, or from a phone with a bad connection. ### Publishing The site is served by GitHub Pages from `main` at `clint-zn/bill-organiser`, with the `CNAME` at the repo root pointing `thejzl.com` at it. Pushing to `main` deploys; there is no build step. ``` python3 publish.py # dry run — prints what would be committed python3 publish.py --push # git add + commit + push ``` `publish.py` deliberately does four things beyond a bare `git push`: 1. **Scopes the commit to `Speculations_Investing/` only.** Unrelated work elsewhere in the repo is never swept into a daily commit. 2. **Clears stale `*.lock` files** older than an hour. On 2026-07-28 a crashed process left `.git/index.lock` and `.git/HEAD.lock` behind and silently blocked every subsequent commit for half a day. Locks younger than an hour are left alone so a genuinely running git process is never disturbed. 3. **Verifies the five content files exist and are non-empty** before staging anything. 4. **Exits cleanly when nothing changed**, so a no-news day doesn't produce an empty commit. It resolves the repo root from its own file location rather than a hardcoded path, because the sandbox mount prefix changes between sessions. If a push fails the commit is already saved locally. Resolve the cause and re-run `git push` — do not amend, reset or force-push a published history. --- ## 7. Repo integrity checklist Run before any task is considered finished: - [ ] All five files present and non-empty - [ ] `index.html` parses; tags balanced; no unclosed tables or divs - [ ] Every internal link (`plan.md`, `skills.md`, `spec.md`, `history.md`) resolves to a real file - [ ] Every external source link is well-formed and attributed to a named publisher - [ ] Every watchlist row has: narrative, catalyst, tier, sentiment, hype stage, score, source - [ ] Disclaimer present in the header of every file and visible on the page - [ ] No personalised advice language anywhere ("you should buy", "this will go up") - [ ] Timestamp updated; stale entries retired per §2.8 - [ ] Site header/nav matches the rest of thejzl.com - [ ] `history.md` appended, never rewritten - [ ] `python3 publish.py --push` run and the commit confirmed in `git log` --- ## 8. Sandbox mode The page includes simulated scenarios for teaching. These are labelled **SIMULATED** wherever they appear and never mixed into the live watchlist. They model: - narrative evolution through the five lifecycle stages - hype-cycle formation and the saturation tell - catalyst emergence and the "sell the news" response - sentiment shifts and price/tone divergence - risk-tier changes as structure changes (dilution, liquidity collapse, revenue arrival) Purpose: let a beginner see a full cycle compressed into minutes, rather than learning the shape of one by losing money over six months. --- ## 9. Limitations — read this part 1. **No live market data.** No prices, no market caps, no volumes are fetched. The system reasons about narratives, catalysts and sentiment. Anything price-related must be verified independently. 2. **Sentiment is qualitative.** It is read from public commentary, not computed from a scored corpus. It is directional, not measurable. 3. **Recency and coverage bias.** The scan sees what is being written about. Genuinely latent narratives — the most valuable stage — are the ones it is least likely to catch. 4. **No backtesting.** Scores have not been validated against forward returns. They rank research interest, not expected profit. 5. **Forums are adversarial.** Some of what is scanned is written specifically to be scanned. Tier C sourcing and the Tier D exclusion reduce but do not eliminate this. 6. **Point-in-time.** Everything on the page is true as at its timestamp and may be wrong hours later. Speculative situations change faster than a daily cadence. 7. **Not personalised.** The system knows nothing about your finances, tax position, timeframe or risk capacity, and cannot account for them. --- ## 10. Change log - **v1.0 — 28 July 2026** — Initial build. Nine sub-agents, four risk tiers, seven-dimension scoring, daily scan across ASX small/microcaps, US small/microcaps and alternative assets. --- *Educational guidance, not personalised financial advice.*