clarion-thesis-monitor

name	clarion-thesis-monitor
description	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.
metadata	{"author":"cis.zo.computer","category":"External","display-name":"Clarion Thesis Monitor","homepage":"https://github.com/jingerzz/clarion-intelligence-system"}

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

1. 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.)

2. Single-thesis review: if the user asks about one ticker, scope it.

   python ... monitor.py --ticker NVDA
   

3. Quick mode (daily): skip the full health re-scoring; just check kill conditions, refresh prices, recompute Risk Environment.

   python ... monitor.py --quick
   

4. Read-only mode: preview the dashboard without writing back to thesis files.

   python ... monitor.py --no-write
   

5. Pass the dashboard output to the user verbatim. It's already structured (per-thesis action + score, kill alerts at the top).

6. 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

1. Kill conditions are binary. A triggered kill condition forces EXIT — no exceptions, no "well, maybe it's fine." This is enforced in code.
2. 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."
3. 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.)
4. 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.
5. 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.