Clarion thesis monitor
Reads every active thesis from ~/clarion/theses/, scores health, checks kill conditions, and produces an action recommendation per thesis. Updates each file with the new scores and timestamps; appends a History entry when the action changes.
Implements docs/PRINCIPLES.md Principle 2 (Thesis-First, Always) — "a thesis that isn't monitored is just a hope."
When to use
User asks any of:
- "Monitor my theses."
- "Thesis health check."
- "Any kill conditions triggered?"
- "What's the action on NVDA right now?"
- "Run a full health check across the portfolio."
Cadence guidance:
- Daily —
--quick mode (kill condition statuses + price refresh + Risk Environment recompute, no full re-scoring)
- Weekly — full mode (all directly-derivable components recomputed; carries forward LLM-driven components)
- Monthly — full mode + manual review of the LLM-driven components (Business Health, Insider Alignment, Thesis Integrity)
Decision tree
Default invocation: run with no args to process all active theses.
python /home/workspace/clarion-intelligence-system/skills/clarion-thesis-monitor/scripts/monitor.py
Filters to status: active theses; skips draft, watchlist, closed, killed. (draft is the default status of a freshly scaffolded thesis from clarion-thesis-write — the user promotes to active once the prose is filled in.)
Single-thesis review: if the user asks about one ticker, scope it.
python ... monitor.py --ticker NVDA
Quick mode (daily): skip the full health re-scoring; just check kill conditions, refresh prices, recompute Risk Environment.
python ... monitor.py --quick
Read-only mode: preview the dashboard without writing back to thesis files.
python ... monitor.py --no-write
Pass the dashboard output to the user verbatim. It's already structured (per-thesis action + score, kill alerts at the top).
Surface "Action Items" — if any thesis flips to EXIT or REDUCE, raise it explicitly. The user makes the call; the system does not pull triggers automatically. (docs/PRINCIPLES.md Anti-principle 5.)
What gets recomputed
| Component |
Behavior |
Notes |
| Valuation Safety |
If --current-price provided AND a base_case_fair_value is in the thesis metadata, recomputed. Else carried forward. |
Add base_case_fair_value: 480.0 to the thesis metadata block to enable auto-scoring. |
| Business Health |
v2: LLM-scored via /zo/ask (full mode only) |
Reads the whole thesis; scores growth, margins, competitive position, balance sheet |
| Insider Alignment |
v2: LLM-scored via /zo/ask (full mode only) |
Insider transactions, comp structure, share count trends |
| Catalyst Proximity |
If catalyst_date in metadata, recomputed. Else carried forward. |
Add catalyst_date: 2026-08-15 to enable auto-scoring. |
| Thesis Integrity |
v2: LLM-scored via /zo/ask (full mode only) |
Do the core claims still hold, is evidence current, are kill conditions sharp |
| Risk Environment |
Always recomputed |
regime × bucket matrix |
LLM scoring (v2) details:
- Requires
ZO_CLIENT_IDENTITY_TOKEN in the environment (present on Zo). Without it — or on any network / parsing failure — the affected components are carried forward from the previous run, never zero-filled, and a warning is printed to stderr. The system refuses to fabricate health scores.
--quick mode never makes LLM calls — dailies stay fast and free.- One
/zo/ask call per active thesis per full run. Set CLARION_LLM_SCORES_MODEL (e.g. zo:openai/gpt-5.4-mini) to pin a cheap model for this task; unset, the account's default model is used.
How to run
MONITOR=python /home/workspace/clarion-intelligence-system/skills/clarion-thesis-monitor/scripts/monitor.py
$MONITOR # all active theses, full mode
$MONITOR --quick # kill checks + Risk Env only
$MONITOR --ticker NVDA # single thesis
$MONITOR --no-write # preview, don't update files
$MONITOR --ticker NVDA --current-price 142.50 # force re-score Valuation Safety
Voice
Lead with action items (any EXIT or REDUCE), then the dashboard. Don't bury bad news. The whole point of monitoring is the moments when things degrade.
When a kill condition is triggered, surface it explicitly: "NVDA — kill condition triggered (gross margin < 60% per latest 10-Q). Action is EXIT regardless of score. Review within 48 hours per the thesis hard rule."
Hard rules
- Kill conditions are binary. A triggered kill condition forces EXIT — no exceptions, no "well, maybe it's fine." This is enforced in code.
- Never fabricate health scores. If the script can't compute a component (no current price, no base case fair value), it carries forward the previous score and marks "data unavailable."
- Always update the thesis files. The monitor is not read-only by default. It writes back updated scores, dates, and findings. (Use
--no-write to opt out for previews.)
- Regime overrides are conservative. In Danger state, all theses downgrade one action level. Shorts upgrade. This is enforced in
lib/ai_buffett_zo/theses/health.py:adjust_for_regime.
- Show the evidence. Every component score in the output has a one-line rationale traceable to a regime, a price, or a previous-run carry-forward.
On error
THESIS_MONITOR_ERROR: no active theses — ~/clarion/theses/ is empty, or every thesis has status: draft/closed/killed/watchlist. If you have draft theses, finish filling them in and promote the metadata status: draft → status: active. Otherwise run clarion-thesis-write to scaffold a new one.THESIS_MONITOR_ERROR: regime unavailable — yfinance cache empty for SPY/TLT/RSP. Run clarion-regime-check first to seed it.THESIS_MONITOR_ERROR: malformed thesis — a specific thesis file failed to parse. The dashboard still runs for the others; the failed one is listed separately for the user to fix.
1---2name: clarion-thesis-monitor3description: Monitor the health of every active thesis in ~/clarion/theses/. For each one — refresh price, recompute Risk Environment from the current regime, check kill conditions (read from the file's status column), aggregate to an Overall score, recommend an action (EXIT / REDUCE / HOLD / ADD), and write the updated scores + history back to the thesis file. Produces a dashboard surfacing what needs attention. Use when the user asks "monitor my theses", "thesis health check", "any kill conditions triggered?", "what's the action on <TICKER>", or as part of a daily / weekly review. Requires clarion-setup to have been run.4---56# Clarion thesis monitor78Reads every active thesis from `~/clarion/theses/`, scores health, checks kill conditions, and produces an action recommendation per thesis. Updates each file with the new scores and timestamps; appends a History entry when the action changes.910Implements [`docs/PRINCIPLES.md` Principle 2 (Thesis-First, Always)](../../docs/PRINCIPLES.md#2-thesis-first-always) — *"a thesis that isn't monitored is just a hope."*1112## When to use1314User asks any of:15- "Monitor my theses."16- "Thesis health check."17- "Any kill conditions triggered?"18- "What's the action on NVDA right now?"19- "Run a full health check across the portfolio."2021Cadence guidance:22- **Daily** — `--quick` mode (kill condition statuses + price refresh + Risk Environment recompute, no full re-scoring)23- **Weekly** — full mode (all directly-derivable components recomputed; carries forward LLM-driven components)24- **Monthly** — full mode + manual review of the LLM-driven components (Business Health, Insider Alignment, Thesis Integrity)2526## Decision tree27281. **Default invocation:** run with no args to process all active theses.2930 ```bash31 python /home/workspace/clarion-intelligence-system/skills/clarion-thesis-monitor/scripts/monitor.py32 ```3334 Filters to `status: active` theses; skips `draft`, `watchlist`, `closed`, `killed`. (`draft` is the default status of a freshly scaffolded thesis from `clarion-thesis-write` — the user promotes to `active` once the prose is filled in.)35362. **Single-thesis review:** if the user asks about one ticker, scope it.3738 ```bash39 python ... monitor.py --ticker NVDA40 ```41423. **Quick mode (daily):** skip the full health re-scoring; just check kill conditions, refresh prices, recompute Risk Environment.4344 ```bash45 python ... monitor.py --quick46 ```47484. **Read-only mode:** preview the dashboard without writing back to thesis files.4950 ```bash51 python ... monitor.py --no-write52 ```53545. **Pass the dashboard output to the user verbatim.** It's already structured (per-thesis action + score, kill alerts at the top).55566. **Surface "Action Items"** — if any thesis flips to EXIT or REDUCE, raise it explicitly. The user makes the call; the system does not pull triggers automatically. ([`docs/PRINCIPLES.md` Anti-principle 5](../../docs/PRINCIPLES.md#the-anti-principles-what-the-system-refuses-to-be).)5758## What gets recomputed5960| Component | Behavior | Notes |61|---|---|---|62| Valuation Safety | If `--current-price` provided AND a `base_case_fair_value` is in the thesis metadata, recomputed. Else carried forward. | Add `base_case_fair_value: 480.0` to the thesis metadata block to enable auto-scoring. |63| Business Health | **v2: LLM-scored via `/zo/ask`** (full mode only) | Reads the whole thesis; scores growth, margins, competitive position, balance sheet |64| Insider Alignment | **v2: LLM-scored via `/zo/ask`** (full mode only) | Insider transactions, comp structure, share count trends |65| Catalyst Proximity | If `catalyst_date` in metadata, recomputed. Else carried forward. | Add `catalyst_date: 2026-08-15` to enable auto-scoring. |66| Thesis Integrity | **v2: LLM-scored via `/zo/ask`** (full mode only) | Do the core claims still hold, is evidence current, are kill conditions sharp |67| Risk Environment | **Always recomputed** | regime × bucket matrix |6869LLM scoring (v2) details:7071- Requires `ZO_CLIENT_IDENTITY_TOKEN` in the environment (present on Zo). Without it — or on any network / parsing failure — the affected components are **carried forward from the previous run, never zero-filled**, and a warning is printed to stderr. The system refuses to fabricate health scores.72- `--quick` mode never makes LLM calls — dailies stay fast and free.73- One `/zo/ask` call per active thesis per full run. Set `CLARION_LLM_SCORES_MODEL` (e.g. `zo:openai/gpt-5.4-mini`) to pin a cheap model for this task; unset, the account's default model is used.7475## How to run7677```bash78MONITOR=python /home/workspace/clarion-intelligence-system/skills/clarion-thesis-monitor/scripts/monitor.py7980$MONITOR # all active theses, full mode81$MONITOR --quick # kill checks + Risk Env only82$MONITOR --ticker NVDA # single thesis83$MONITOR --no-write # preview, don't update files84$MONITOR --ticker NVDA --current-price 142.50 # force re-score Valuation Safety85```8687## Voice8889Lead with **action items** (any EXIT or REDUCE), then the dashboard. Don't bury bad news. The whole point of monitoring is the moments when things degrade.9091When a kill condition is triggered, surface it explicitly: *"NVDA — kill condition triggered (gross margin < 60% per latest 10-Q). Action is EXIT regardless of score. Review within 48 hours per the thesis hard rule."*9293## Hard rules94951. **Kill conditions are binary.** A triggered kill condition forces EXIT — no exceptions, no "well, maybe it's fine." This is enforced in code.962. **Never fabricate health scores.** If the script can't compute a component (no current price, no base case fair value), it carries forward the previous score and marks "data unavailable."973. **Always update the thesis files.** The monitor is not read-only by default. It writes back updated scores, dates, and findings. (Use `--no-write` to opt out for previews.)984. **Regime overrides are conservative.** In Danger state, all theses downgrade one action level. Shorts upgrade. This is enforced in `lib/ai_buffett_zo/theses/health.py:adjust_for_regime`.995. **Show the evidence.** Every component score in the output has a one-line rationale traceable to a regime, a price, or a previous-run carry-forward.100101## On error102103- **`THESIS_MONITOR_ERROR: no active theses`** — `~/clarion/theses/` is empty, or every thesis has `status: draft/closed/killed/watchlist`. If you have draft theses, finish filling them in and promote the metadata `status: draft` → `status: active`. Otherwise run `clarion-thesis-write` to scaffold a new one.104- **`THESIS_MONITOR_ERROR: regime unavailable`** — yfinance cache empty for SPY/TLT/RSP. Run `clarion-regime-check` first to seed it.105- **`THESIS_MONITOR_ERROR: malformed thesis`** — a specific thesis file failed to parse. The dashboard still runs for the others; the failed one is listed separately for the user to fix.
zocomputer