clarion-single-stock-eval

Files (3)

• SKILL.md
• buffett-question-bank.md · references/
• eval.py · scripts/

SKILL.md (first lines)

# 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

```bash
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.

From SillyHippy/zo-skills, MIT.

More from SillyHippy/zo-skills