Us Undervalued Growth Screener

US Undervalued Growth Screener — v3.6 (Claude Code Direct-FMP)

Overview

Run an end-to-end US undervalued-growth/GARP screen from a minimal request. Find companies whose EPS or FCF per share can compound enough to support attractive two- to three-year returns without assuming multiple expansion, while controlling for accounting basis, forecast construction, SBC, dilution, leverage, cyclicality, corporate actions, peer context, source freshness, and evidence quality.

Claude Code is the preferred execution environment. In Claude Code, run the local direct-FMP pipeline once. The Python process performs bulk retrieval, persistent caching, FY1 normalization, liquidity calculation, four-lane discovery, and deterministic broad screening while keeping raw FMP payloads on disk and out of the model context. Claude reads only the compact run summary and selected candidate packets, then completes SEC/IR underwriting and the existing strict evaluation sequence.

Treat a request such as “use this skill to screen for undervalued-growth stocks” as complete. Resolve defaults, collect current data, choose a viable acquisition path, checkpoint the work, repair obtainable blockers, and return the finished result in the same task. Never ask the user to supply a ticker list, API-plan details, output path, or a separate “continue” instruction unless the user explicitly narrows the scope.

Deep-dive budget and lane coverage: The bounded direct-FMP path defaults to max_deep_dive_candidates: 3. Three selected names cannot represent all four research lanes. The default lane targets are core GARP 2, high-growth exception 1, quality near miss 1, and cyclical normalization 1 (five slots total). A three-name run prioritizes candidates across lanes; it does not promise one name per lane. For a five-slot lane-first selection, set max_deep_dive_candidates: 5 in a local copy of assets/claude-code-config.example.json and rerun the bounded pipeline with that config. Eligible candidates and diversification preferences still determine actual lane representation. The separate full-snapshot path requires full_snapshot_deep_dive_candidates: 5. See references/claude-code-execution.md for selection and budget-change details.

Non-Negotiable Runtime Preflight

Before reading or reusing any prior run artifact, verify the installed runtime:

python3 skills/us-undervalued-growth-screener/scripts/run_pipeline.py --version
python3 skills/us-undervalued-growth-screener/scripts/screen_universe.py --version
python3 skills/us-undervalued-growth-screener/scripts/build_discovery_pool.py --version
python3 skills/us-undervalued-growth-screener/scripts/build_provider_prefilter_pool.py --version
python3 skills/us-undervalued-growth-screener/scripts/normalize_estimates.py --version
python3 skills/us-undervalued-growth-screener/scripts/manage_run_state.py --version
python3 skills/us-undervalued-growth-screener/scripts/evaluate_candidates.py --version
python3 skills/us-undervalued-growth-screener/scripts/prepublish_audit.py --version
python3 skills/us-undervalued-growth-screener/scripts/bundle_run_artifacts.py --version

Every command must report the same metadata:

skill_version = 3.6.1
schema_version = 3
contract_revision = 3.5
runtime_fingerprint = ug-v3.6.1-claude-code-direct-fmp-20260830

Discard and regenerate any audit, checkpoint, or snapshot whose runtime metadata differs. Do not mix scripts, assets, or run artifacts from v3.1 through v3.5. A stale or cached same-name skill is a hard execution failure, not a warning.

Autonomous Completion Contract

For a minimal request, perform all of the following without handing control back to the user:

1. Fix analysis_as_of and the latest completed US regular-session close.
2. Collect current market context with field-level source support and freshness checks.
3. In Claude Code, invoke run_pipeline.py instead of issuing bulk FMP MCP calls. Keep provider payloads on disk and expose only compact summaries to the model.
4. Audit the requested NYSE/Nasdaq/NYSE American listing universe through adaptive, exhausted market-cap bands when provider responses saturate.
5. Build a reproducible economic candidate pool. Do not require complete financial statements across the whole market.
6. Distinguish enrichment attempted from enrichment resolved.
7. Apply the deterministic broad-screen script. Do not replace its statuses with ad hoc LLM cutoffs.
8. Select up to three economically plausible deep-dive candidates in Claude Code through deterministic multi-lane sampling: core GARP, high-growth exceptions, quality near misses, and cyclicals requiring normalization. Apply a two-name sector cap when alternatives exist. Growth thresholds remain guidelines, not isolated hard gates.
9. Resolve every row in the chosen candidate pool or record sourced exhaustion evidence.
10. Perform corporate-action preflight and primary-source underwriting for every selected symbol.
11. Save every selected symbol as a verified candidate record, including review_required, screened_out, and excluded outcomes.
12. Assemble the schema-v3 / contract-v3.5 snapshot.
13. Run evaluate_candidates.py --strict --require-final.
14. Apply the final quality eligibility gate; route weak-cash-flow, low-ROIC, overleveraged, heavily dilutive, fragile-low-case, or severe-LOE names to conditional or review_required.
15. Run prepublish_audit.py; repair every obtainable blocker and rerun.
16. Run bundle_run_artifacts.py to produce a self-contained audit ZIP containing every referenced artifact.
17. Present a formal ranking and downloadable bundle only when all gates pass.

An exit code of 2 means continue the same execution: enrich the queue, verify the pool-generation audit, complete selected deep dives, or repair contract failures. It never means “ask the user to say continue.” After attaching the audit, run manage_run_state.py next-action; execute the returned action and every returned symbol. Never ask whether to process two versus five selected names. To change the budget, rerun the broad screen first so omitted names become deferred_by_budget.

Completion Semantics

Final ranking from an audited bounded pool

A reproducibly generated bounded pool may support a scoped final ranking when:

candidate-pool generation audit is valid
candidate_pool_exhausted = true
all_rows_resolved = true
unresolved_count = 0
queue_count = 0
all selected symbols have verified candidate records
strict final evaluation passes

Label the conclusion scope, such as stratified_discovery_pool or provider_prefilter. Do not imply that unexamined market listings were economically screened.

Market-wide “no qualifying candidates”

A market-wide no-candidates conclusion requires all of the above plus full in-scope economic coverage:

conclusion_scope = full_listing_universe
candidate_pool covers every in-scope listing
in_scope_missing_count = 0
at least one row was economically assessable
selected_symbols = []

Bounded-pool “no qualifying candidates”

A bounded pool may conclude only:

no qualifying candidates in the audited bounded pool

It must not claim that the entire US small/mid-cap market has no qualifying company.

Read references/autonomous-execution.md before a live minimal-request run.

When to Use

Use this skill to:

• Discover and rank US-listed undervalued-growth or GARP stocks.
• Screen operating-company common stocks on NYSE, Nasdaq, and NYSE American.
• Test whether EPS or FCF-per-share growth alone supports roughly 30%–50% upside over two to three years.
• Refresh a prior screen after earnings, guidance, filings, corporate actions, or estimate revisions.
• Compare candidates on forward valuation, growth durability, ROIC, standard FCF, SBC, dilution, peers, cycle risk, and sector-specific KPIs.

Do not use it for:

• A generic single-ticker report after a stock is already selected; use us-stock-analysis.
• Pure dividend, momentum, technical-pattern, pre-revenue biotechnology, or merger-arbitrage screening.
• Automatic order placement.

Prerequisites

• Python 3.9 or later.
• requests for the generated direct-FMP client; deterministic evaluation and audit scripts otherwise use the standard library.
• FMP_API_KEY in the environment for Claude Code direct mode. Never commit or print the key.
• Current SEC, company-IR, and macro sources accessible for selected-company underwriting.
• Writable reports/ and .cache/ directories.
• No specific paid FMP plan is assumed. Bulk endpoint failures fall back to bounded per-symbol enrichment and are disclosed in diagnostics.

Default Scope

Unless the user specifies otherwise:

• Exchanges: NYSE, Nasdaq, NYSE American.
• Security type: active operating-company common stock.
• Market-cap focus: USD 500 million–20 billion.
• Minimum price: USD 5.
• Preferred average daily dollar volume: USD 5 million; hard floor USD 1 million.
• Claude Code provider-prefilter pool: target 30 symbols after code-side economics and verified liquidity; bounded per-symbol fallback may inspect up to 80 names without loading their provider payloads into model context.
• Deep-dive budget: three symbols by default on the bounded Claude Code path, selected from four deterministic research lanes; three slots cannot represent all four lanes. Once selected, every symbol must be resolved; lower the budget only by rerunning the broad screen so omitted names become deferred_by_budget.
• Maximum ranked output: ten, though the verified deep-dive set may be smaller.
• Minimum formal constant-multiple upside: 30% over a supported two- or three-year horizon.
• Multiple-contraction stress: current forward multiple reduced by 20%.
• Minimum analysts for a rankable consensus horizon: three, unless a fully sourced independent forecast is constructed.

Immutable request scope and bounded execution

For a minimal request, the user-requested market-cap scope is always USD 500M–20B. Never rewrite the run config so a convenient 3–4B band becomes the requested scope. Record user_requested_scope and executed_scope separately. A narrower executed scope is incomplete unless the user explicitly requested it; context or tool-budget pressure is not authorization. Stream listing pages/bands to JSONL rather than loading every row into the conversation context.

Liquidity evidence

Never calculate ADDV from one session's volume. Candidate generation requires a provider average-dollar-volume measure or price × average_volume with an explicit averaging window of at least 20 trading days and source IDs. Rows lacking valid average-liquidity evidence remain needs_enrichment and cannot enter the discovery pool.

Current forward horizon

A current P/E must be explicitly NTM or FY1 and must reconcile to a positive current forward EPS, price, fiscal-year/period metadata, estimate date, analyst count, and source IDs. Generic outer-year P/E values are invalid. A missing FY1/NTM row, a range crossing zero, or extreme forecast dispersion sends the name to enrichment or unavailable_after_enrichment; it must never appear as a low-P/E selection.

Result-Quality Controls

Deterministic multi-lane candidate discovery

Do not let one global score fill the research budget with a single style or sector. Allocate the default five deep dives across these lanes when qualifying names exist:

• two core GARP names,
• one high-growth exception with Forward P/E up to 30x,
• one quality near miss whose low valuation may compensate for sub-guideline headline growth,
• one cyclical candidate that requires an explicit mid-cycle model.

Backfill unused slots by deterministic priority and limit selections to two per sector when alternatives exist. Report each selected name's selection_lane. The LLM may explain these decisions but may not replace them with ad hoc cutoffs.

Formal eligibility quality gate

A name that passes the upside test is not automatically eligible. Formal ranking also requires:

• final score at least 70,
• SBC-adjusted FCF yield at least 3% or EV/FCF at most 30x,
• ROIC at least 8%,
• Net Debt/EBITDA no more than 3.0x when applicable,
• diluted-share CAGR no more than 5%,
• at least 15% upside under a supported low-consensus case,
• no severe LOE tail loss worse than the configured threshold.

One or two ordinary failures may produce conditional; severe FCF or LOE failures and broader weakness produce review_required. Never label a low-P/E/high-EV-FCF transition story as a formal winner merely because average-consensus EPS implies 30% upside.

Independent forecast-driver evidence

Every ranked year-2/year-3 bridge must use construction_method=independent_driver_model. Each revenue, margin, interest, tax, share-count, FCF, and adjustment driver needs an origin and source IDs. Mark any driver solved backwards from target EPS with target_solved=true; this fails the bridge. A residual adjustment that merely forces the model to consensus is not independent validation.

Publish only self-contained results

The final report is not publishable until prepublish_audit.py verifies all referenced audit files, counts, hashes, scenario arithmetic, candidate statuses, final-three labels, and absence of unfinished-run language. Package the entire run directory with bundle_run_artifacts.py; a ZIP containing only Markdown/JSON summaries is incomplete.

Data Acquisition Strategy

Preferred Claude Code path — direct FMP, compact model context

Run one local command:

python3 skills/us-undervalued-growth-screener/scripts/run_pipeline.py \
  --config skills/us-undervalued-growth-screener/assets/claude-code-config.example.json \
  --output-dir reports/us-undervalued-growth-screener

The generated FMP client reuses the repository's central scripts/fmp_client/ source-of-truth pattern. It writes raw responses and a persistent SQLite cache to disk. Do not paste or read the raw provider trees into the language-model context. Read only run-summary.json, NEXT_ACTION.json, audit/broad-screen-audit.json, and the compact packets under candidate-packets/.

For a market-wide run on a plan without bulk estimates, collect every frozen universe shard first, then screen the verified snapshot:

python3 skills/us-undervalued-growth-screener/scripts/run_pipeline.py \
  --stage collect-estimates --shard-index 0 --shard-count 8 \
  --snapshot-dir .cache/us-garp/snapshot-current \
  --config skills/us-undervalued-growth-screener/assets/claude-code-config.example.json \
  --resume

python3 skills/us-undervalued-growth-screener/scripts/run_pipeline.py \
  --stage screen-full-snapshot \
  --snapshot-dir .cache/us-garp/snapshot-current \
  --config skills/us-undervalued-growth-screener/assets/claude-code-config.example.json \
  --output-dir reports/us-undervalued-growth-screener

Run each shard once without --resume; use --resume only to continue an existing partial shard. Both collection and screening are current-only: collection fixes the estimate-normalization basis, while screening adds exact liquidity and TTM quality evidence. The first collection binds the exhausted listing-enumeration audit into the snapshot manifest. Screening performs a read-only content/freshness preflight before creating provider or run artifacts, carries a digest binding the enumeration proof and every verified shard into downstream audits, backfills liquidity failures until 50 valid names or full eligible exhaustion, and commits five probed deep-dive names. Read references/full-universe-snapshot.md for the full collection and screening contract.

If the provider call budget is exhausted during screen enrichment, the command exits 2 and writes audit/partial-run-diagnostic.json plus audit/enriched-estimates.partial.jsonl. The diagnostic is the last atomic commit marker and records the snapshot ID/digest, stage, deterministic attempted/completed/pending/interrupted symbols, interrupted provider operation, provider counters, and hashes for the partial artifacts. Read a partial artifact only when that marker exists and its recorded hashes and row counts verify; a missing or mismatched marker makes the partial output non-authoritative. screen-full-snapshot has no --resume: rerun the same verified snapshot after restoring the provider budget, allowing new cache/raw records from successful calls and reusing existing cache/raw data without deleting or rewriting it. A packet-stage budget failure also marks broad-screen-audit.json incomplete/diagnostic, clears all nested selection commitment fields, and rewrites all broad-screen rows (including rejected rows) to deferred_by_budget with selection eligibility disabled. The original decision is preserved in prior_decision, and original top-level selection fields in prior_selection; these archives are audit-only, never selection authority, and repeated invalidation retains the first archive. Neither the audit nor any partial output is a final market-wide conclusion. Quality-probe calls_used and actual_eps_calls count FMP provider-budget units: cached or unsent calls cost zero, and consumed retry responses remain counted. Each retry uses a new empty run directory. The CLI adds a unique attempt suffix and keeps raw responses in a sibling attempt directory, while direct callers must not reuse a non-empty output directory.

The direct runner first attempts bulk ratios, key metrics, estimate, and EOD datasets. It falls back to bounded per-symbol enrichment only when bulk access is unavailable; a plan-gated (402/403) bulk endpoint is remembered in the cache for 30 days so later runs do not spend calls re-probing it. On the fallback path the estimate seed is a stratified sector × market-cap sample (√-weighted Hamilton quota, liquidity-ranked within cells, hash tie-break) whose size is derived from the remaining call budget; audit/seed-audit.json states the selection basis. Before pool selection, the top lane candidates receive a key-metrics-ttm quality probe (ROIC, FCF yield, EV/FCF, leverage, SBC) and a probe-resolved row with SBC-adjusted FCF yield below 1% cannot enter any lane except high_growth_exception. Exact 20-day ADDV work is prioritized by the four economic lanes, not by ticker order. Read references/claude-code-execution.md and references/migration-v3.6-to-v3.6.1.md for the full execution contract.

Layer 1 — Listing-Universe Audit

Collect only fields suitable for broad coverage:

• symbol and exchange,
• active/common-stock status,
• price and quote timestamp,
• market capitalization,
• average daily dollar volume or enough data to calculate it,
• sector and industry when available.

Do not substitute a share-volume floor for an ADDV threshold. If an API can filter only by share volume, fetch broadly, calculate price × average volume, and apply the dollar-liquidity rule locally.

Target at least 95% listing-field completeness. Prove enumeration using provider totals and exhausted pagination or exhausted gap-free market-cap bands. Matching only the requested lower and upper market-cap endpoints is not proof of completeness.