Clarion Single Stock Eval

Clarion single-stock evaluation

Pulls structured data + filing snippets for a ticker, then helps you compose a Buffett-style evaluation.

When to use

User asks any of:

• "Evaluate NVDA."
• "Is KO still a long-term hold?"
• "Buffett take on AAPL."
• "What's NVDA's moat?"
• "How does AMD's management allocate capital?"
• "What are the biggest risks for INTC?"

Decision tree

1. Check indexing. Run clarion-sec-research status <TICKER> and read the Eval readiness line. The indexer processes high-signal filings first (annual report → quarterly → proxy → everything else), so you do not need to wait for the whole queue to drain. As soon as status shows "Ready to evaluate" (the annual report is indexed), proceed — even if 8-Ks or Form 4s are still queued. If it's "Not eval-ready yet", tell the user to run clarion-sec-research index <TICKER> and wait for the annual report (typically 1–5 minutes), then come back. The eval itself also prints a coverage note: a loud "Partial coverage" warning if the annual report is missing, or a quiet line naming any still-queued gaps.
2. Run eval.py <TICKER>. If the user mentioned a 1Y T-bill yield or risk-free rate, pass --rf-rate-pct X.X. The script prints market context, a quality snapshot, and four dimensions of filing snippets.
3. Read the brief end-to-end. Then synthesize an evaluation using the references/buffett-question-bank.md (load it on demand) — answer the four (or five, if hurdle was supplied) numbered questions in the script's "Reading guide" section, in order, citing the filing on every claim drawn from filings.
4. Conclude with one of three verdicts:
   • Add — clear thesis; expected return likely clears the regime hurdle; ready to size a position
   • Watchlist — promising but waiting for {a better price / a specific catalyst / a clearer signal}
   • Skip — material issue (no durable moat / impaired financials / unaligned management / risk profile too severe)
5. If the verdict is Add and the user wants to act on it, suggest clarion-thesis-write to formalize the position into a thesis file.

How to run

EVAL=python /home/workspace/clarion-intelligence-system/skills/clarion-single-stock-eval/scripts/eval.py

$EVAL NVDA                       # default — pulls all four dimensions
$EVAL NVDA --rf-rate-pct 4.5     # adds equity hurdle to market context
$EVAL NVDA --no-regime           # skip regime/hurdle if user just wants the lens
$EVAL NVDA --timing              # also print a per-stage latency summary to stderr

Diagnosing slow evals. If an evaluation feels slow, re-run with --timing. It prints a per-stage breakdown to stderr (SEC status / yfinance snapshot / regime check / Buffett lens search / render) so you can see where the time goes — without polluting the markdown the agent reasons over. Pairs with the sec-indexer per-filing timing … log lines for the indexing side. See issue #42.

Voice

Conservative and direct. Show your math (numbers from the snippets and the quality table). Lead with what the filings actually say; surface uncertainty where the snippets are vague.

Always cite the filing on every claim drawn from filings. Each snippet's citation line is canonical (NVDA 10-K filed 2026-02-21 → risk_factors). Do not paraphrase the citation — copy it.

Don't fabricate. If a snippet doesn't directly support a claim you'd like to make, say so explicitly — "the indexed sections don't address customer concentration" beats inventing.

The yfinance quality table is point-in-time and occasionally wrong (ticker remappings, delistings, foreign listings). For high-conviction calls, suggest the user verify against the latest filing.

On error

• No filings indexed — run clarion-sec-research index <TICKER>, wait for completion, retry.
• EVAL_ERROR: failed to fetch fundamentals — yfinance hiccup. Retry in a minute. The lens still works without fundamentals; consider running with --no-regime and noting the gap.