diff --git a/.github/workflows/insider-scan.yml b/.github/workflows/insider-scan.yml index b89c176..9d319d2 100644 --- a/.github/workflows/insider-scan.yml +++ b/.github/workflows/insider-scan.yml @@ -32,14 +32,14 @@ jobs: enable-cache: true - name: Install dependencies - working-directory: skills/signal-sweep + working-directory: skills/idea-generation run: uv sync --locked - name: Run insider scan env: EDGAR_IDENTITY: ${{ secrets.EDGAR_IDENTITY }} DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }} - working-directory: skills/signal-sweep + working-directory: skills/idea-generation run: | DATE="${{ github.event.inputs.date || 'yesterday' }}" LOOKBACK="${{ github.event.inputs.lookback || '5' }}" @@ -55,5 +55,5 @@ jobs: uses: actions/upload-artifact@v4 with: name: insider-scan-${{ github.run_id }} - path: skills/signal-sweep/signal-sweep-cache/insiders/ + path: skills/idea-generation/idea-cache/insiders/ retention-days: 90 diff --git a/.gitignore b/.gitignore index 59a1395..b392faa 100644 --- a/.gitignore +++ b/.gitignore @@ -6,10 +6,10 @@ __pycache__/ # SEC EDGAR download cache (regenerated on demand) sec-cache/ -# Signal-sweep output cache (regenerated on demand) -signal-sweep-cache/ +# Idea-generation output cache (regenerated on demand) +idea-cache/ -# Transcript cache (market-scout, regenerated on demand) +# Transcript cache (market-data, regenerated on demand) transcript-cache/ # OS cruft diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc index 13d7e2a..787046a 100644 --- a/.markdownlint-cli2.jsonc +++ b/.markdownlint-cli2.jsonc @@ -16,7 +16,7 @@ "**/node_modules/**", ".git", "**/sec-cache/**", - "**/signal-sweep-cache/**", + "**/idea-cache/**", "**/transcript-cache/**" ] } diff --git a/AGENTS.md b/AGENTS.md index d5e1cc0..eeacf04 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,7 +7,7 @@ docs route agents and preserve non-obvious project rationale. - Never commit directly to `main`; work on a branch and open a PR. - Never commit secrets. `EDGAR_IDENTITY` and `DISCORD_WEBHOOK_URL` are supplied via environment / CI secrets, never hard-coded. -- Never commit cache output. `sec-cache/`, `signal-sweep-cache/`, and `transcript-cache/` are regenerated on demand and are git-ignored. +- Never commit cache output. `sec-cache/`, `idea-cache/`, and `transcript-cache/` are regenerated on demand and are git-ignored. - Lint and format must pass before a PR (see `context/CONVENTIONS.md`). CI runs `ruff check`, `ruff format --check`, and `markdownlint-cli2`. - Keep changes scoped; avoid incidental refactors. - Verify behavior with commands before documenting claims. diff --git a/README.md b/README.md index 7755752..db4ee00 100644 --- a/README.md +++ b/README.md @@ -132,7 +132,7 @@ The five skills are documented in [`skills/README.md`](skills/README.md). The pr flow is: ```text -signal-sweep → bottom-up-analyst → sec-edgar-skill / market-scout → pitch-like-lou +idea-generation → due-diligence → sec-filings / market-data → pitch-like-lou ``` ## Development diff --git a/context/CONVENTIONS.md b/context/CONVENTIONS.md index cedb69c..8cdf026 100644 --- a/context/CONVENTIONS.md +++ b/context/CONVENTIONS.md @@ -32,7 +32,10 @@ Terse imperative code rules. No rationale here — rationale lives in ## Markdown / docs -- Keep each `SKILL.md` terse; defer detail to `references/` (progressive disclosure). +- Keep each `SKILL.md` to routes, commands, and pointers; defer detail to `references/` + (progressive disclosure). +- Put a script lesson where the mistake happens: handle it in code, else in the error + message, else in `--help` or report text; use `references/` only for off-script work. - Ensure `AGENTS.md`, `README.md`, and everything in `context/` pass markdownlint. - Append to `context/DECISIONS.md` only when the choice crosses the decision-log bar in `AGENTS.md`. diff --git a/context/DECISIONS.md b/context/DECISIONS.md index 63da46e..eb020db 100644 --- a/context/DECISIONS.md +++ b/context/DECISIONS.md @@ -66,11 +66,11 @@ Tradeoff: Research cannot be split across independent agents, but the full evide model judgement stay together without an extra model-selection or context-budget dependency. Status: active -## 2025-06-21 — market-scout uses agent-browser instead of a direct HTTP client +## 2025-06-21 — market-data uses agent-browser instead of a direct HTTP client Context: Yahoo Finance transcript and market endpoints are unstable and bot-hostile when scraped with a plain HTTP client. -Decision: Drive market-scout's transcript fetching through `agent-browser`. +Decision: Drive market-data's transcript fetching through `agent-browser`. Tradeoff: Adds a Node/`agent-browser` install step (no SEC identity needed but an extra dependency) in exchange for reliable access to dynamic pages. Status: active @@ -79,9 +79,10 @@ Status: active Context: A fixed percentage move (e.g. -20%) is routine for a biotech but exceptional for a utility, so a flat threshold misfires across the universe. -Decision: Tag dip/rip buys by the stock's trailing 30-day return z-score -(default ±1.5σ) rather than a fixed percent move; only Form 4 open-market -purchases (code `P`) are counted. +Decision: Tag dip/rip buys by the z-score of the 22-trading-day return as of the +transaction date against that stock's prior 252 rolling 22-day returns (default +±1.5σ) rather than a fixed percent move; only Form 4 open-market purchases +(code `P`) are counted. Tradeoff: Requires per-stock volatility history and tuning of the z-score threshold; rejects the simpler but universe-blind fixed-percent rule. Status: active diff --git a/context/MAP.md b/context/MAP.md index 5214f7b..a03b069 100644 --- a/context/MAP.md +++ b/context/MAP.md @@ -13,10 +13,10 @@ SYSTEM.md Research-agent identity installed into the isolated profil extensions/ Restores Pi's tool prompt envelope and brands the startup header scripts/bootstrap.mjs Isolated-profile bootstrap skills/ Skill collection and skill-level documentation - signal-sweep/ Discovery — scan the universe, surface tickers - sec-edgar-skill/ Data — SEC EDGAR filings, ownership, 13F holders - market-scout/ Data — price, peers, transcripts (Yahoo Finance) - bottom-up-analyst/ Analysis — one operating company → scoped answer or memo + idea-generation/ Discovery — scan the universe, surface tickers + sec-filings/ Data — SEC EDGAR filings, ownership, 13F holders + market-data/ Data — Yahoo Finance fields and earnings-call transcripts + due-diligence/ Analysis — one operating company → scoped answer or memo pitch-like-lou/ Voice — finished thesis → VIC-style pitch context/ Agent-maintained project documentation ``` @@ -49,39 +49,40 @@ configuration, sessions, and unrelated settings remain profile-local and untouch ## Skill internals -- `skills/signal-sweep/` — `scripts/scan_insiders.py`, `scan_market.py`, +- `skills/idea-generation/` — `scripts/scan_insiders.py`, `scan_market.py`, `scan_conferences.py`, `search_themes.py`; universe config in `screens.json`; shared bootstrap in `scripts/_common.py`. -- `skills/sec-edgar-skill/` — `scripts/fetch_*.py`, `parse_financials.py`, `orient.py`, - `list_headings.py`; filing, financial, ownership, proxy/governance, and holdings guides in - `references/`; shared bootstrap in `scripts/_common.py`. -- `skills/market-scout/` — `scripts/fetch_market_data.py`, `fetch_transcripts.py`, and shared +- `skills/sec-filings/` — `scripts/fetch_*.py`, `parse_financials.py`, `orient.py`, + `test_setup.py`; `references/edgartools.md` (inline API) and `references/ownership.md` + (ownership and governance semantics, shared with `due-diligence`); shared bootstrap in `scripts/_common.py`. -- `skills/bottom-up-analyst/` — valuation `scripts/dcf.py`, `epv.py`; archetypes and guides in - `references/`. +- `skills/market-data/` — `scripts/fetch_market_data.py`, `fetch_transcripts.py`, and shared + `scripts/_common.py`. +- `skills/due-diligence/` — valuation `scripts/dcf.py`, `epv.py`; `references/` + normalization, valuation, archetypes, and memo spine. - `skills/pitch-like-lou/` — reference corpus only, no scripts. ## Data flow ```mermaid flowchart TD - SS[signal-sweep
surfaces tickers] --> BUA[bottom-up-analyst
analysis + optional memo] - BUA --> SEC[sec-edgar-skill
filings] - BUA --> MS[market-scout
price / peers / transcripts] + SS[idea-generation
surfaces tickers] --> BUA[due-diligence
analysis + optional memo] + BUA --> SEC[sec-filings
filings] + BUA --> MS[market-data
price / peers / transcripts] BUA --> PLL[pitch-like-lou
renders pitch] ``` -- `bottom-up-analyst` selects evidence, reasons over it, and produces the requested analysis or +- `due-diligence` selects evidence, reasons over it, and produces the requested analysis or full memo. Retrieval contracts and source semantics remain in the data skills. - The two filing/market data skills know nothing of each other and are swappable. -- `signal-sweep` and SEC-facing `sec-edgar-skill` commands read `EDGAR_IDENTITY` and use +- `idea-generation` and SEC-facing `sec-filings` commands read `EDGAR_IDENTITY` and use on-disk cache contracts defined in their `_common.py` modules. The SEC skill's routine 13F convenience queries use 13f.info and expose underlying SEC periods and identifiers; raw EDGAR remains the deep-field and verification route. ## Production order -For a full thesis: `signal-sweep` → `bottom-up-analyst` → memo → optionally +For a full thesis: `idea-generation` → `due-diligence` → memo → optionally `pitch-like-lou`. For the package installation and isolated-profile workflow, start at the root diff --git a/package.json b/package.json index e65a2eb..aae9810 100644 --- a/package.json +++ b/package.json @@ -12,10 +12,10 @@ "./extensions/startup-header.ts" ], "skills": [ - "./skills/signal-sweep", - "./skills/sec-edgar-skill", - "./skills/market-scout", - "./skills/bottom-up-analyst", + "./skills/idea-generation", + "./skills/sec-filings", + "./skills/market-data", + "./skills/due-diligence", "./skills/pitch-like-lou" ] } diff --git a/pyproject.toml b/pyproject.toml index 095d1f3..f826f73 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -38,7 +38,7 @@ ignore = [ convention = "google" [tool.ruff.lint.isort] -known-first-party = ["bottom-up-analyst", "market-scout", "pitch-like-lou", "sec-edgar-skill", "signal-sweep"] +known-first-party = ["due-diligence", "market-data", "pitch-like-lou", "sec-filings", "idea-generation"] [dependency-groups] dev = [ diff --git a/scripts/bootstrap.mjs b/scripts/bootstrap.mjs index 845c3af..ce4bb15 100644 --- a/scripts/bootstrap.mjs +++ b/scripts/bootstrap.mjs @@ -170,9 +170,9 @@ function mergeSettings() { function ensurePythonEnvironment() { const uv = findUv(); const projects = [ - installedSecStackPath("skills", "signal-sweep"), - installedSecStackPath("skills", "sec-edgar-skill"), - installedSecStackPath("skills", "market-scout"), + installedSecStackPath("skills", "idea-generation"), + installedSecStackPath("skills", "sec-filings"), + installedSecStackPath("skills", "market-data"), ]; for (const project of projects) { const pyproject = join(project, "pyproject.toml"); diff --git a/skills/README.md b/skills/README.md index 5812df3..a417894 100644 --- a/skills/README.md +++ b/skills/README.md @@ -8,52 +8,53 @@ they form a research pipeline. | Layer | Skill | Job | |---|---|---| -| **Discovery** | [`signal-sweep`](signal-sweep/) | Scan SEC filings and market data to surface new investment ideas. | -| **Data** | [`sec-edgar-skill`](sec-edgar-skill/) | Retrieve and extract SEC filings, ownership, and 13F holder data. | -| **Data** | [`market-scout`](market-scout/) | Pull prices, returns, peers, sector screens, and transcripts. | -| **Analysis** | [`bottom-up-analyst`](bottom-up-analyst/) | Turn one operating company into scoped analysis or an auditable investment memo. | +| **Discovery** | [`idea-generation`](idea-generation/) | Surface new tickers from insider buying, 13Ds, screens, filing themes, and investor events. | +| **Data** | [`sec-filings`](sec-filings/) | Retrieve filings, XBRL statements, insider trades, 13F holders, and blockholders. | +| **Data** | [`market-data`](market-data/) | Pull any Yahoo Finance field and earnings-call transcripts. | +| **Analysis** | [`due-diligence`](due-diligence/) | Turn one operating company into a scoped answer or an auditable investment memo. | | **Voice** | [`pitch-like-lou`](pitch-like-lou/) | Render a finished thesis as a VIC-style pitch. | ## Data flow ```text - signal-sweep (surfaces tickers) + idea-generation (surfaces tickers) │ ▼ - bottom-up-analyst (deep dive on one ticker) - ├── sec-edgar-skill (filings and ownership) - ├── market-scout (price, peers, transcripts) + due-diligence (deep dive on one ticker) + ├── sec-filings (filings and ownership) + ├── market-data (price, peers, transcripts) ▼ pitch-like-lou (finished pitch) ``` -`bottom-up-analyst` is the conductor. It decides what to pull, reasons over the evidence, +`due-diligence` is the conductor. It decides what to pull, reasons over the evidence, values the business, and produces the requested analysis or full memo. The data skills supply the underlying evidence. -`signal-sweep` and `sec-edgar-skill` are independent data sources. `market-scout` is also -swappable: the analyst can use a different market-data provider without changing its -reasoning workflow. +`idea-generation` and `sec-filings` are independent data sources. `market-data` is also +swappable: due diligence can use a different market-data provider without changing its +reasoning. The voice skill renders from a finished thesis; it is not an idea generator. -**Production order for a full thesis:** signal-sweep → bottom-up-analyst → memo → optionally +**Production order for a full thesis:** idea-generation → due-diligence → memo → optionally pitch-like-lou. ## Progressive disclosure -Each skill keeps its `SKILL.md` entry point concise. Detailed guidance lives in -`references/`, executable helpers live in `scripts/`, and configuration/assets stay beside -the skill that owns them. Load only the guide or script required for the current task. +Each `SKILL.md` holds routes, commands, and pointers. A script's lessons live in its code, +error messages, `--help`, and report text; off-script detail lives in `references/`, +executable helpers in `scripts/`, and configuration beside the skill that owns it. ## Skill resources -- [`signal-sweep`](signal-sweep/) contains configurable market screens, SEC discovery +- [`idea-generation`](idea-generation/) contains configurable market screens, SEC discovery scanners, conference discovery, and theme search. -- [`sec-edgar-skill`](sec-edgar-skill/) contains filing, financial, ownership, and 13F - retrieval helpers. -- [`market-scout`](market-scout/) contains Yahoo Finance market and transcript helpers. -- [`bottom-up-analyst`](bottom-up-analyst/) contains valuation arithmetic and memo frameworks. +- [`sec-filings`](sec-filings/) contains filing, financial, ownership, and 13F + retrieval helpers plus an inline `edgartools` reference. +- [`market-data`](market-data/) contains Yahoo Finance snapshot and transcript helpers. +- [`due-diligence`](due-diligence/) contains valuation arithmetic, archetypes, and the memo + spine. - [`pitch-like-lou`](pitch-like-lou/) contains the pitch-writing workflow and reference corpus. Each skill's README documents its dependencies and usage. Invoke installed artifact-producing diff --git a/skills/bottom-up-analyst/README.md b/skills/bottom-up-analyst/README.md deleted file mode 100644 index b779437..0000000 --- a/skills/bottom-up-analyst/README.md +++ /dev/null @@ -1,55 +0,0 @@ -# Bottom-Up Analyst - -An [agent skill](SKILL.md) for substantive, long-only fundamental research on one -non-financial operating company. It turns filing, market, industry, and ownership evidence -into a scoped answer or a full, auditable due-diligence memo. - -The framework is designed for companies whose operating economics and cash flows can be -underwritten. It is not the primary framework for banks, insurers, REITs, funds, or -predominantly binary-asset companies. - -## What it does - -- Scales the work to the question instead of forcing every request into a full memo. -- Selects one or more optional analytical lenses: compounder, hypergrowth, cyclical, - turnaround, special situation, or deep value. -- Reconciles reported results to normalized economics without double-counting stock - compensation, leases, working capital, or enterprise-to-equity adjustments. -- Underwrites competitive position, management incentives, ownership, and governance when - they are material to value. -- Chooses valuation methods for the business rather than mechanically running every method. -- Separates verified evidence, estimates, assumptions, and external evidence, with citations. -- Builds the strongest countercase and lets conviction fall when evidence is incomplete. - -## Layout - -- `SKILL.md` — workflow, evidence discipline, resource routing, and script examples. -- `references/memo_template.md` — adaptable full-memo skeleton. -- `references/guide_*.md` — normalization, competition, valuation, and - ownership/governance guidance. -- `references/archetypes/` — optional playbooks for six common thesis shapes. -- `scripts/dcf.py` — forward, explicit-forecast, and reverse enterprise DCF. -- `scripts/epv.py` — no-growth Earnings Power Value arithmetic. - -## Setup - -The valuation scripts use only the Python standard library: - -```bash -python scripts/dcf.py --help -python scripts/epv.py --help -``` - -They require material assumptions explicitly. `dcf.py` accepts free cash flow to the firm -(FCFF), discounts it at WACC, and bridges enterprise value to equity using net claims: debt and -other senior claims less non-operating assets. - -Install and configure [`sec-edgar-skill`](../sec-edgar-skill/) for SEC evidence and -[`market-scout`](../market-scout/) for market data and transcripts. Each data skill owns its -runtime, cache, and source instructions. - -## Scope and judgment - -This skill supports research, not personalized investment advice. Its memo is an auditable -argument rather than a recommendation tailored to a person's circumstances. A human remains -responsible for checking the evidence, assumptions, suitability, and decision. diff --git a/skills/bottom-up-analyst/SKILL.md b/skills/bottom-up-analyst/SKILL.md deleted file mode 100644 index d66ce1c..0000000 --- a/skills/bottom-up-analyst/SKILL.md +++ /dev/null @@ -1,183 +0,0 @@ ---- -name: bottom-up-analyst -description: >- - Conduct substantive, long-only bottom-up research on one non-financial operating company. - Use for an investment thesis, buy/pass/watch decision, valuation, earnings-quality review, - bull/bear assessment, or full due-diligence memo when the user wants analysis rather than a - quote or filing lookup. The framework suits businesses whose operating, asset, or transaction - economics can be underwritten from public evidence, including cash-burning growth companies - with observable unit economics. Do not use it as the primary framework for banks, insurers, - REITs, funds, or clinical-stage and other predominantly binary-asset companies. ---- - -# Bottom-Up Analyst - -Turn evidence about one company into a long-only investment judgment. Scale the work to the -question: answer a scoped valuation or earnings-quality request directly; produce the full memo -only for a deep dive or when the user asks for one. - -This is the analysis layer of SecStack. Use `sec-edgar-skill` for filing evidence and -`market-scout` for market data and transcripts. A finished memo may later feed -`pitch-like-lou`, but this skill owns the research method and does not depend on that voice. - -## Evidence discipline - -Facts, estimates, assumptions, and external evidence must remain distinguishable. Use this -markup on load-bearing claims and tables, not on headings or connective prose: - -- **[V] Verified:** checked against a cited filing, regulator, issuer document, or other - authoritative primary record. Identify the form/document, period, section or accession, and - date where available. -- **[E] Estimate:** calculated or modeled. Show the formula, inputs, units, and source dates. -- **[A] Assumption:** not established by available evidence. State what would validate it and - how the conclusion changes if it is wrong. -- **[W] External evidence:** a web, trade, channel, expert, or secondary source. Name and date - it. `[W]` describes provenance, not truth; assess incentives and corroboration. - -Do not tag an inference `[V]` merely because its premises are verified. State the inference and -cite its premises. An issuer filing verifies what the issuer disclosed, not that management's -interpretation is neutral. Vendor-produced call transcripts are useful records of a call but -can contain transcription errors; verify a load-bearing quotation against issuer materials or -recording when practical. - -Prefer the source authoritative for the claim. SEC filings lead for filed financials, capital -structure, contracts, ownership, and governance. Issuer IR may lead for a release not yet filed; -a regulator or court may lead for a rule or case; industry data may lead for market structure. -Report material conflicts instead of silently choosing one source. - -## Workflow - -### 1. Frame the decision - -Identify the security, listing, as-of date, investor question, and requested depth. Resolve -ambiguous tickers or share classes before research. For a full deep dive, define the current -market expectation you need to test. For a scoped request, investigate only the evidence needed -to answer it and disclose what was not reviewed. - -### 2. Build the evidence set - -Use `sec-edgar-skill` orientation only when the relevant form or accession is unknown. Skip it -when an accession, cached artifact, or non-SEC source is already the precise route. Read the -latest annual filing and subsequent material updates for a full company review; choose narrower -sources for a narrower question. - -Timestamp current market data. Check recent EDGAR and issuer IR for new disclosures, but do not -assume a same-day event has already been filed. Use call transcripts for management statements -and Q&A leads, with speaker attribution and the transcript caveat above. - -Keep large documents on disk and retrieve only relevant sections. Follow each data skill's own -current guide and `--help`; do not guess flags, cache behavior, or field semantics here. - -### 3. Select the analytical lenses - -Choose an archetype only when it sharpens the work. Load the closest playbook from -`references/archetypes/`; use a primary and secondary lens when the economics genuinely span -both. Do not force a company into the taxonomy. If no playbook fits, reason from the business -model and the decision at hand. - -| Lens | Use when the thesis turns on | -| :-- | :-- | -| `compounder.md` | returns on incremental capital and reinvestment runway | -| `hypergrowth.md` | immature profits, unit economics, and a path to positive cash flow | -| `cyclical.md` | normalized cycle earnings, cost position, and balance-sheet survival | -| `turnaround.md` | a specific mechanism changing margins, demand, or capital structure | -| `special_situation.md` | a transaction, legal document, security, or forced flow | -| `deep_value.md` | conservatively realizable assets and a path to realization | - -### 4. Reconstruct the economics - -Reconcile reported earnings to the cash-flow measure appropriate to the valuation. Separate -recurring operations from one-offs, acquisition effects, working-capital timing, stock -compensation, leases, and maintenance versus growth investment without double-counting any -adjustment. Use a multi-period view long enough for the business and cycle. Read -`references/guide_normalization.md`. - -When a material part of value comes from a new stream or future margin structure, build a -bottom-up bridge from operational drivers to revenue, margins, reinvestment, and cash flow. -Treat an unsupported TAM share or margin target as `[A]`, not as a forecast. - -### 5. Underwrite the business and stewards - -Explain how the company makes money, why customers choose it, where industry profits accrue, -and what could change. Select peers by business model and economics rather than accepting an -automated industry list uncritically. Quantify material forces where reliable evidence permits; -otherwise use a bounded range or identify the unresolved variable. Do not invent precision to -fill a template. Read `references/guide_competitive.md`. - -Review management incentives, dilution, capital allocation, controlling holders, related-party -transactions, and governance when they can affect value. Use 13F and Form 4 data as limited, -lagged evidence rather than a verdict. Read `references/guide_ownership_signals.md`. - -### 6. Value the security - -Use the lenses that match the cash-flow and asset economics; triangulation does not mean running -an inapplicable method. Reverse DCF is useful only when a positive base FCFF and the model shape -make implied growth interpretable. EPV is a no-growth operating case, not a guaranteed floor. -Special situations and asset plays usually need scenario payoffs or sum-of-parts work outside -the bundled scripts. - -State the valuation date, cash-flow basis, enterprise-to-equity bridge, diluted share count, -discount rate, terminal assumptions, and scenario logic. Vary the assumptions that actually -drive value, not growth alone by habit. Read `references/guide_valuation.md` before running the -scripts. - -### 7. Try to disprove the thesis - -Write the strongest contrary explanation, run the relevant playbook's disqualifiers, and test -load-bearing assumptions. Distinguish permanent impairment from volatility. Describe what -would falsify the thesis, the expected timing, financing or dilution risk, and any evidence gap -that limits conviction. A pass or watch decision is a valid result. - -### 8. Deliver at the requested depth - -Use `references/memo_template.md` for a full deep dive. Adapt its sections and metrics to the -company and thesis; it is a decision-oriented skeleton, not a form. For a scoped answer, give -the conclusion, decisive evidence, calculations, countercase, missing work, and sources without -padding it into a full memo. - -## Valuation scripts - -Resolve script paths relative to this `SKILL.md` and invoke them by absolute path while keeping -the shell working directory at the user's research workspace. Every material assumption is -explicit; `--help` is the flag reference. - -```bash -# Positive-FCFF forward sensitivity -python "/scripts/dcf.py" forward --fcff0 1200 --growth 8,12,16 \ - --years 10 --terminal-growth 3 --wacc 10 --shares 500 --net-claims 200 --price 75 - -# Explicit annual FCFF, including an initial loss or inflection -python "/scripts/dcf.py" forecast --fcff=-20,10,45,80,110 \ - --terminal-growth 2.5 --wacc 12 --shares 30 --net-claims 66 --price 8 - -# Growth implied by price -python "/scripts/dcf.py" reverse --price 75 --fcff0 1200 --years 10 \ - --terminal-growth 3 --wacc 10 --shares 500 --net-claims 200 - -# No-growth operating earnings case -python "/scripts/epv.py" --ebit 600 --tax 21 --wacc 9 \ - --shares 500 --net-claims 200 --price 10 -``` - -The DCF is an enterprise model: pass normalized **FCFF**, discount at WACC, then subtract -`--net-claims` (debt and other senior claims less non-operating assets). Do not pass -after-interest owner earnings or FCFE and subtract debt again. - -## Resources - -| Resource | Read or run when | -| :-- | :-- | -| `references/memo_template.md` | writing a full due-diligence memo | -| `references/guide_normalization.md` | reconstructing normalized cash economics | -| `references/guide_competitive.md` | underwriting industry and competitive position | -| `references/guide_valuation.md` | choosing and implementing valuation lenses | -| `references/guide_ownership_signals.md` | assessing ownership, insiders, incentives, and governance | -| `references/archetypes/*.md` | one or two lenses materially sharpen the case | -| `scripts/dcf.py`, `scripts/epv.py` | reproducible enterprise-valuation arithmetic | - -## Completion check - -Before answering, ensure the work supports its own confidence: current security and source -periods are clear; material facts are cited; calculations reconcile; assumptions and inferences -are visible; the strongest countercase is addressed; valuation uses a consistent cash-flow -basis; and omitted work is disclosed. Do not manufacture a verdict stronger than the evidence. diff --git a/skills/bottom-up-analyst/references/archetypes/compounder.md b/skills/bottom-up-analyst/references/archetypes/compounder.md deleted file mode 100644 index 462a7f5..0000000 --- a/skills/bottom-up-analyst/references/archetypes/compounder.md +++ /dev/null @@ -1,57 +0,0 @@ -# Archetype: quality compounder - -Use this lens when value depends on a business reinvesting substantial cash at attractive -incremental returns for a long time. The analytical edge is usually duration and reinvestment, -not merely calling the company “high quality.” - -## Establish the shape - -Look for persistent economic returns above the opportunity cost of capital, a demonstrated -ability to reinvest, durable customer value, and room to deploy more capital. Do not use a fixed -ROIC or growth threshold. Adjust accounting and compare through a cycle where relevant. - -Distinguish: - -- average ROIC from return on **incremental** invested capital; -- organic reinvestment from acquisitions and financial leverage; -- pricing power from temporary price/cost timing; -- a long runway from a large but inaccessible TAM; and -- per-share compounding from enterprise growth offset by dilution. - -A useful approximation is sustainable operating growth = reinvestment rate × return on new -capital. It is not an identity for shareholder return or intrinsic-value growth; taxes, -distributions, financing, fade, and valuation still matter. - -## Evidence to pull - -- segment economics, unit growth, pricing, retention, and customer concentration; -- capex, working capital, acquisitions, and other reinvestment by period; -- gross margin, incremental margin, ROIC, and FCFF across enough years to test durability; -- diluted share count, repurchases, stock compensation, and acquisition consideration; -- incentives and capital-allocation record from proxies and filings; and -- peers with similar customers and business models, not merely the same sector label. - -## Valuation - -Connect the explicit forecast to reinvestment capacity and incremental returns. Test what growth -duration and fade the current price implies. A forward enterprise DCF may be useful when FCFF is -positive and predictable; an explicit forecast is better when margins or reinvestment change. -EPV can show how much value comes from future reinvestment but is not a hard downside floor. - -Do not justify a terminal premium by repeating the word “quality.” Normalize returns and -reinvestment in the terminal state. - -## Disqualifiers and counterevidence - -Mark down or reject the case when: - -- reported ROIC is an accounting artifact or omits required assets and obligations; -- incremental returns are falling toward or below the cost of capital; -- growth requires acquisitions or spending that the model excludes; -- the reachable runway is nearly exhausted or competitors can copy the expansion; -- customer concentration, regulation, or a temporary shortage explains the apparent moat; -- buybacks occur above defensible value or only offset dilution; or -- enterprise growth fails to produce per-share value. - -The memo should state the operating measure that will reveal runway or return decay before the -headline growth rate does. diff --git a/skills/bottom-up-analyst/references/archetypes/cyclical.md b/skills/bottom-up-analyst/references/archetypes/cyclical.md deleted file mode 100644 index 59c3bec..0000000 --- a/skills/bottom-up-analyst/references/archetypes/cyclical.md +++ /dev/null @@ -1,49 +0,0 @@ -# Archetype: cyclical - -Use this lens when an external cycle drives material variation in price, volume, credit, -utilization, or margins. The central tasks are estimating normalized economics, locating the -current cycle with humility, and testing whether the balance sheet survives a worse path. - -## Establish the shape - -Identify the actual cycle driver and transmission mechanism. Separate cyclical variation from a -secular change in demand, technology, regulation, or cost position. The latest earnings and -trailing multiple are often poor anchors at both peaks and troughs. - -Study more than one comparable cycle where the history exists. Adjust for changes in capacity, -product mix, geography, accounting, acquisitions, and capital structure before averaging old -results. - -## Evidence to pull - -- price, volume, mix, utilization, backlog, inventory, and capacity across a full cycle; -- fixed and variable costs, incremental and decremental margins, and cash conversion; -- sustaining capex, working-capital swings, and closure or restart costs; -- debt maturities, covenants, liquidity, collateral, and refinancing requirements; -- cost-curve or asset-quality evidence relative to competitors; and -- authoritative industry supply, demand, inventory, and capacity data. - -## Normalization and valuation - -Estimate mid-cycle earnings from operating drivers, not a blind arithmetic average. Show a -trough, normalized, and strong environment with the associated FCFF, liquidity, and share count. -Include any dilution or asset sale needed to survive the trough. - -EPV on defensible mid-cycle operating earnings can be useful, alongside asset or unit values and -historical transaction evidence. A spot P/E or EV/EBITDA on peak results is not evidence of -cheapness. An explicit DCF should model the transition to normalized conditions rather than -assuming a peak or trough persists. - -## Disqualifiers and counterevidence - -Mark down or reject the case when: - -- normalized earnings are anchored to an unusually favorable period; -- the balance sheet, covenants, or liquidity cannot withstand the downside path; -- the company sits high on the cost curve or owns impaired assets; -- new capacity, substitution, or secular decline prevents the prior cycle from returning; -- management adds capacity or leverage near peaks and issues equity near troughs; or -- the thesis requires precise cycle timing unsupported by observable supply and demand. - -The memo should state the cycle indicators, what phase they suggest, alternative explanations, -and what evidence would prove the “mid-cycle” estimate too high. diff --git a/skills/bottom-up-analyst/references/archetypes/deep_value.md b/skills/bottom-up-analyst/references/archetypes/deep_value.md deleted file mode 100644 index da6ef10..0000000 --- a/skills/bottom-up-analyst/references/archetypes/deep_value.md +++ /dev/null @@ -1,60 +0,0 @@ -# Archetype: deep value or asset play - -Use this lens when the case depends on conservatively realizable assets or a sum of parts rather -than forecast growth. A balance-sheet discount is only the start; liabilities, cash burn, -control, tax, timing, and a credible realization path determine whether it becomes a return. - -## Establish the shape - -Identify the exact asset claim per diluted share and why carrying value differs from realizable -value. Distinguish cash available to common shareholders from restricted, regulated, pledged, -subsidiary, or operating cash. Determine who can authorize realization and whether incentives -support it. - -## Evidence to pull - -- balance sheet and footnotes for debt, leases, pensions, guarantees, contingencies, preferred - claims, minority interests, and restrictions; -- asset-level detail for receivables, inventory, property, investments, tax basis, liens, and - disposal costs; -- operating cash flow and commitments to estimate how quickly the asset cushion changes; -- buybacks, tenders, sales, liquidation plans, spin-offs, or other realization actions; -- proxy, 13D/13G, voting rights, related parties, compensation, and insider ownership; and -- market or transaction evidence for asset haircuts and sale timelines. - -## Valuation - -Build a transparent realizable-value bridge: - -```text -cash and investments, adjusted for restrictions -+ recoverable receivables and inventory -+ appraised or transaction-supported asset values -− all debt and senior claims -− operating losses through realization -− tax, transaction, closure, and corporate costs -= value available to common equity -``` - -Use ranges for recovery rates and timing. Value ongoing operations separately with EPV only when -earnings are durable and required maintenance is included. Do not call book value or EPV a hard -floor. - -Model realization outcomes and annualized returns rather than multiplying the headline discount -by probability and dividing by time. Expected value must include the downside payoff, interim -burn or distributions, taxes, and time value. - -## Disqualifiers and counterevidence - -Mark down or reject the case when: - -- restricted cash, senior claims, liens, or contingencies consume the apparent cushion; -- operating losses or required investment erode value before realization; -- receivables, inventory, property, or investments cannot realize the assumed amount; -- a controller can delay or divert value and minority protections are weak; -- annual compensation, related-party leakage, or dilution overwhelms expected convergence; -- tax and transaction costs eliminate the headline discount; or -- no observable path or decision-maker can close the gap within an underwritable period. - -The memo should state who controls realization, what action is required, the expected value under -non-realization, and the monitorable that shows the asset cushion is melting. diff --git a/skills/bottom-up-analyst/references/archetypes/hypergrowth.md b/skills/bottom-up-analyst/references/archetypes/hypergrowth.md deleted file mode 100644 index 5c3e30a..0000000 --- a/skills/bottom-up-analyst/references/archetypes/hypergrowth.md +++ /dev/null @@ -1,59 +0,0 @@ -# Archetype: cash-burning or high-growth operating company - -Use this lens when current profit understates or fails to show the economics management expects -at scale, but the company has observable customers, revenue, and operating drivers. Do not use it -for a predominantly binary clinical, exploration, or legal asset. - -## Establish the shape - -Growth rates alone do not define the archetype. Look for deliberate investment ahead of revenue, -immature margins, evolving product-market fit, meaningful stock compensation or external -financing, and operating metrics that can connect customers or units to cash flow. - -Separate: - -- growth caused by customer value from growth purchased with discounts or uneconomic spend; -- mature-cohort economics from blended company economics; -- organic growth from acquisitions; -- gross retention from expansion revenue; -- addressable demand from management's TAM; and -- company growth from per-share value after dilution. - -Metrics such as retention, CAC payback, LTV/CAC, active users, GMV, ARR, or Rule of 40 apply only -when they match the business model and are defined consistently. Reconcile non-GAAP measures to -reported results and track definition changes. - -## Evidence to pull - -- cohort, retention, pricing, usage, backlog, and contribution-margin disclosures; -- gross margin and sales, marketing, R&D, support, capex, and working capital by period; -- cash, burn, debt, covenants, funding needs, and runway under a downside case; -- stock compensation, grants, issuance, repurchases, and diluted share history; -- early public filings and prior targets, to compare the original model with outcomes; and -- peers or substitutes that reveal acquisition cost, churn, price, and mature margins. - -## Valuation - -Do not grow a negative FCFF base with the constant-growth DCF route. Build explicit annual -revenue, margin, tax, reinvestment, and FCFF scenarios, then use `dcf.py forecast` once the annual -FCFF sequence is defensible. Reconcile the current price to combinations of scale, mature margin, -capital intensity, and dilution rather than presenting one implied growth rate as unique. - -Forward revenue multiples are shorthand for future margin, growth, and reinvestment assumptions; -make that bridge explicit. Include financing and dilution before the company reaches positive -cash flow. - -## Disqualifiers and counterevidence - -Mark down or reject the case when: - -- mature cohorts or units remain uneconomic; -- growth depends on rising incentives, falling price, or worsening acquisition efficiency; -- retention, backlog quality, or metric definitions deteriorate; -- a plausible scale and margin path still cannot reconcile to the price; -- the reachable market is not supported by bottom-up customers or units; -- funding runs out before operating break-even or creates unacceptable dilution; or -- the model assumes costs disappear rather than scale with service obligations. - -The memo should identify the metric that distinguishes temporary investment from structurally -poor unit economics and the date by which evidence should emerge. diff --git a/skills/bottom-up-analyst/references/archetypes/special_situation.md b/skills/bottom-up-analyst/references/archetypes/special_situation.md deleted file mode 100644 index feec365..0000000 --- a/skills/bottom-up-analyst/references/archetypes/special_situation.md +++ /dev/null @@ -1,54 +0,0 @@ -# Archetype: special situation - -Use this lens when a transaction, security term, legal document, reorganization, spin-off, -tender, recapitalization, or forced flow drives value more than ordinary operating growth. The -edge is accurate document reading, a complete capital structure, and scenario arithmetic. - -## Establish the shape - -Identify the binding event or term, the security being valued, conditions and consents, seniority, -timeline, and who controls each decision. Read the operative agreement, plan, indenture, exhibit, -court order, or statute rather than relying on a summary. - -A primary document verifies its text, not the analyst's legal interpretation. Mark uncertain -interpretation as `[A]`, use qualified legal analysis where material, and do not describe an -outcome as inevitable merely because the language appears favorable. - -## Evidence to pull - -- operative transaction and security documents, including definitions, schedules, and exhibits; -- SEC current reports, registration or information statements, tender materials, and amendments; -- court, regulator, exchange, and home-jurisdiction records where applicable; -- voting agreements, financing commitments, termination rights, fees, and outside dates; -- 13D/13G purpose, control relationships, and minority protections; -- the fully diluted pre- and post-event capital structure and claim waterfall; and -- operating information needed to value each residual outcome. - -## Scenario arithmetic - -For each material outcome, show: - -- payoff to the exact security and share class; -- interim distributions, financing, taxes, fees, and dilution; -- probability basis and dependencies; -- expected timing and annualized return; and -- break, delay, or residual value supported independently of the deal price. - -Use sum-of-parts for separable businesses and a waterfall for layered claims. Rebuild the -post-event balance sheet rather than subtracting today's net debt mechanically. Preserve -currency, exchange-ratio, proration, and conversion assumptions. - -## Disqualifiers and counterevidence - -Mark down or reject the case when: - -- a condition, definition, consent, financing out, or senior claim defeats the apparent term; -- minority protections or enforcement are weaker than assumed; -- the timeline is open-ended and carrying costs erase the expected return; -- break value depends on the unaffected price without re-underwriting the business; -- probability is asserted without a base rate or case-specific evidence; -- taxes, fees, proration, dilution, tradability, or liquidity materially change the security payoff; or -- a load-bearing legal interpretation has not been independently checked. - -The memo should separate document facts, legal interpretation, probability judgment, and payoff -calculation so a reader can disagree with one without losing the entire audit trail. diff --git a/skills/bottom-up-analyst/references/archetypes/turnaround.md b/skills/bottom-up-analyst/references/archetypes/turnaround.md deleted file mode 100644 index 91ce218..0000000 --- a/skills/bottom-up-analyst/references/archetypes/turnaround.md +++ /dev/null @@ -1,57 +0,0 @@ -# Archetype: turnaround or inflection - -Use this lens when a specific change may make future economics differ materially from trailing -results: restructuring, new management, pricing, divestiture, product transition, regulation, -demand recovery, or capital-structure repair. Cheapness and management targets are not mechanisms. - -## Establish the shape - -Write the causal bridge: - -```text -identified change -→ operating line affected -→ magnitude and timing -→ cash cost and funding -→ observable evidence so far -→ normalized FCFF if it works -``` - -Separate self-help the company controls from external recovery it does not. Distinguish early -evidence from a target, and identify the old problem that could persist. - -## Evidence to pull - -- recent quarterly and current reports, exhibits, and calls for sequential evidence; -- segment results and cost lines that locate the drag and proposed improvement; -- restructuring charges, cash payments, stranded costs, dis-synergies, and transition capex; -- pricing, volume, backlog, churn, or utilization measures tied to the mechanism; -- management's prior targets and delivery record; -- liquidity, covenants, maturities, and financing needs through the transition; and -- the primary regulatory, contractual, or transaction document when it drives the change. - -## Valuation - -Build explicit annual failure, partial-success, and stronger-success cases. Use -`dcf.py forecast` when FCFF changes sign or margins step through a transition. Do not give the -company its target margin immediately; model implementation cost, timing, taxes, working capital, -reinvestment, financing, and dilution. - -EPV or asset value may provide a comparison for current operations, but neither is a floor when -cash burn, liabilities, or deterioration continue. Value any disposed or retained pieces on the -post-transaction capital structure. - -## Disqualifiers and counterevidence - -Mark down or reject the case when: - -- no specific mechanism connects actions to cash flow; -- reported progress relies on exclusions while cash economics do not improve; -- the balance sheet runs out before evidence should arrive; -- savings are offset by lost revenue, reinvestment, or stranded costs; -- the apparent inflection is an ordinary cycle rebound or temporary comparison; -- management has repeatedly missed similar plans; or -- price already requires successful execution with little downside protection. - -The memo should specify milestones, dates, cash runway, and the evidence that would distinguish a -delay from a broken mechanism. diff --git a/skills/bottom-up-analyst/references/guide_competitive.md b/skills/bottom-up-analyst/references/guide_competitive.md deleted file mode 100644 index 87186d8..0000000 --- a/skills/bottom-up-analyst/references/guide_competitive.md +++ /dev/null @@ -1,115 +0,0 @@ -# Competitive and industry analysis - -Use this guide to determine whether the economics in the model can persist. The goal is not a -list of moat labels or risk factors; it is a causal account of where industry profits come from, -why this company captures its share, and what evidence would show that position changing. - -## Start with the question, then choose sources - -Use the source authoritative for each claim rather than imposing one universal source order. - -- **Issuer filings and exhibits:** reported segments, customer concentration, contracts, - capacity, risk disclosures, and management's explanation of results. They are primary records - of the issuer's disclosure, not independent proof of market position. -- **Peer filings and calls:** competitors' reported demand, pricing, capacity, strategy, and - financial outcomes. Select a few economically relevant peers; an automated industry list is a - candidate set, not ground truth. -- **Regulators, courts, standards bodies, and government data:** rules, licenses, enforcement, - market statistics, and legal status. -- **Customers, suppliers, product documentation, procurement records, and trade data:** buying - criteria, switching friction, price, reliability, channel behavior, and adoption. -- **Independent research and reporting:** useful for discovery and triangulation. Assess source - access, method, date, incentives, and whether the claim can be checked directly. - -Cite and date material evidence. Use `[V]` for facts checked in an authoritative primary record -and `[W]` for external or secondary evidence. When sources disagree, preserve the disagreement -and explain which assumption the valuation uses. - -## Map the industry economics - -Answer the questions that determine profit durability: - -1. **Value chain:** who supplies, distributes, pays, uses, and captures gross profit? -2. **Market definition:** what product, customer, geography, and time period does a share or TAM - figure actually cover? -3. **Structure:** concentration, capacity, entry and exit, substitutes, regulation, bargaining - power, and capital intensity. -4. **Buying decision:** which attributes decide a purchase, who bears switching cost, and how - often a customer can reconsider? -5. **Rate of change:** technology, regulation, supply, customer behavior, and new business - models that could alter the profit pool. - -Avoid top-down market labels that mix unlike products or geographies. Reconcile market-size and -share estimates to company revenue where possible. - -## Select and compare peers - -Choose peers based on the economic question: product overlap, customer set, cost structure, -geography, maturity, or capital intensity. Different questions may need different peer sets. -Document why each peer belongs. - -Compare a multi-period set of relevant measures, which may include organic growth, unit volume, -price/mix, gross margin, incremental margin, retention, capital intensity, ROIC, and customer -concentration. Persistent differences are clues, not automatic proof of a moat. Test alternative -explanations such as accounting policy, mix, geography, underinvestment, leverage, or a temporary -cycle position. - -## Explain advantage as a mechanism - -For each claimed advantage, complete the chain: - -```text -asset, capability, or structural position -→ customer or cost consequence -→ observable operating evidence -→ economic outcome -→ reason competitors cannot quickly copy or neutralize it -``` - -Examples of mechanisms include scale economies, network effects, switching costs, scarce assets, -regulatory position, process advantage, brand, distribution, and counter-positioning. The label -alone does no analytical work. State what would erode the mechanism and which metric would show -that first. - -## Quantify without inventing precision - -Size forces when reliable data permit. Useful forms include: - -- exposure: affected revenue, customers, units, capacity, or gross profit; -- sensitivity: effect of a price, volume, churn, utilization, or cost change; -- trajectory: direction, rate, and time to materiality; and -- scenario range: a bounded impact under explicit assumptions. - -Some risks are discontinuous, legal, behavioral, or poorly disclosed. Do not fabricate a point -estimate merely because a template asks for one. Use a range, break-even calculation, observable -leading indicator, or `[A]` gap. Explain whether the unknown is capable of changing the decision. - -## Separate evidence from inference - -A contract term can be `[V]`; “therefore customers are captive” is an inference. A peer's claim -that it gained share verifies the claim was made, not the share gain. Tie inferences to multiple -observable premises when possible: - -- renewal or churn history; -- realized price versus input cost; -- win/loss or backlog conversion; -- gross-margin and incremental-margin persistence; -- customer concentration and cohort behavior; -- replacement cycle or migration effort; and -- competitor investment and capacity response. - -Treat management tone and analyst questions as leads, not measurements. - -## Output - -Conclude with a compact underwriting view: - -1. market and profit-pool definition; -2. the company's position and relevant peers; -3. two or three mechanisms that matter, with evidence and erosion tests; -4. material threats and their best-supported ranges or indicators; -5. implications for growth, margins, reinvestment, and valuation; and -6. unresolved evidence gaps. - -The section earns its place only if it changes an assumption, probability, risk assessment, or -monitorable in the thesis. diff --git a/skills/bottom-up-analyst/references/guide_normalization.md b/skills/bottom-up-analyst/references/guide_normalization.md deleted file mode 100644 index ecbeb0f..0000000 --- a/skills/bottom-up-analyst/references/guide_normalization.md +++ /dev/null @@ -1,159 +0,0 @@ -# Normalization — reported results to economic cash flow - -Use this guide when reported earnings do not represent the repeatable cash economics relevant -to the thesis. Normalization is a reconciliation, not permission to remove unpleasant costs. -Show each adjustment, source period, rationale, tax treatment, and effect so the reader can -reverse it. - -## Choose the cash-flow basis first - -Do not mix enterprise and equity cash flows. - -### Free cash flow to the firm (FCFF) - -Use FCFF for the bundled DCF and EPV scripts: - -```text -FCFF = EBIT × (1 − normalized cash tax rate) - + D&A and other justified non-cash add-backs - − capital expenditure - − increase in operating working capital -``` - -Do not use “non-cash” alone as justification to add back a recurring economic cost such as stock -compensation. FCFF is before interest and net borrowing. Discount it at WACC to value operations, -then bridge from enterprise value to common equity by adding non-operating assets and subtracting net debt, -preferred stock, minority interests, pension deficits, and other senior claims as appropriate. -Do not hide those items inside a label called net debt; show the bridge in the memo. - -### Owner earnings or free cash flow to equity (FCFE) - -A cash flow starting from net income or cash from operations is after interest under US GAAP and -is generally an equity cash flow. IFRS presentation can classify interest differently, so -reconcile it explicitly. Discount FCFE at the cost of equity and do not subtract debt again. The -bundled DCF does not model FCFE. - -Whichever basis you use, reconcile it to the statements. Label units, currency, fiscal period, -and whether each figure is reported `[V]`, estimated `[E]`, or assumed `[A]`. - -## Recurring versus non-recurring - -Use a multi-period history and ask what a steady owner must expect to recur. - -- Remove a gain or loss only when the underlying event is genuinely non-operating or unlikely - to recur. Repeated restructuring, litigation, acquisition, or “one-time” costs belong in - normalized economics unless the operating mechanism has demonstrably changed. -- Normalize taxes using the expected cash burden, including jurisdiction mix, credits, NOLs, - and expiry. Do not adopt a headline statutory rate by default. -- Separate acquired growth from organic growth and include the acquisition spending required - to sustain a roll-up's apparent growth. -- Distinguish temporary commodity, foreign-exchange, pension, fair-value, and working-capital - effects from a changed run rate. - -Present reported-to-normalized bridges for the periods that matter. A single adjusted year is -usually too easy to cherry-pick. - -## Maintenance and growth investment - -Total capex combines replacement, compliance, capacity, and expansion. Estimate maintenance -capex by triangulating evidence such as: - -- management's disclosed split, treated as an issuer estimate rather than objective fact; -- physical units, replacement cycles, utilization, and current replacement cost; -- capex during periods with little capacity growth; -- depreciation by asset class, useful life, asset age, and inflation; and -- peer asset intensity and sustaining-capex disclosures. - -D&A is a reference point, not a universal floor or ceiling. Old assets and inflation can make -replacement cost exceed depreciation; overbuilt capacity or accelerated depreciation can do the -opposite. If the split is uncertain, use a range and show how valuation changes. - -A growth project is not economically free because it is excluded from “maintenance” capex. -Connect growth investment to incremental revenue, margins, and returns on incremental capital. - -## Working capital and deferred revenue - -Use operating working capital and preserve signs: an increase is a use of cash; a decrease is a -source. Normalize seasonal or event-driven swings with comparable dates and multiple periods. -Investigate receivable growth, inventory aging, payables extension, factoring, and channel -loading before treating a cash release as repeatable. - -Deferred revenue is customer financing and a timing difference, not extra revenue to add back -mechanically. Its change already affects operating cash flow. Analyze billings, remaining -performance obligations, refund obligations, churn, and the future delivery cost; then model the -cash timing consistently without counting the same inflow twice. - -## Stock-based compensation and dilution - -Stock compensation is an economic cost, but common starting points treat it differently: - -- GAAP EBIT and net income already expense it. Do not subtract the same expense again from an - EBIT-based FCFF unless you first added it back. -- Cash from operations adds the non-cash expense back. A CFO-minus-capex measure therefore needs - an explicit treatment: retain the GAAP expense in a reconstructed FCFF, subtract an estimate - of ongoing grants, or model the cash needed to offset dilution. -- Reflect outstanding in-the-money instruments in diluted shares or value them separately. - Model future grants consistently with operating margins. Do not charge the full compensation - expense and an unrelated full dilution penalty without reconciling the overlap. - -Show basic and diluted share-count history, grants, exercises, repurchases, and net issuance. -Repurchases that merely offset compensation are not a return of capital. - -## Leases - -Lease treatment must match the cash flow, capital structure, and comparison metric. - -- If rent remains an operating expense and cash outflow, do not also add the full lease - liability to debt without adjusting the earnings and cash-flow basis. -- If leases are capitalized as financing, add back the financing component consistently, - capitalize the obligation, and use lease-adjusted peer metrics. - -Either convention can be useful; mixing them double-counts the lease burden. - -## A useful operating history - -Choose rows and years for the business rather than forcing a fixed table. A typical operating -company history may include: - -| Period | Revenue | Organic growth | EBIT margin | FCFF | Diluted shares | Net debt | ROIC | -| :-- | --: | --: | --: | --: | --: | --: | --: | -| [FY-2] | | | | | | | | -| [FY-1] | | | | | | | | -| [FY0] | | | | | | | | - -For a cyclical, span a full cycle. For a turnaround, add quarterly bridge metrics. For a unit -model, show mature cohorts or stores. Explain denominator choices for ROIC and compute return on -incremental capital only across periods where the comparison is meaningful. - -## New streams and changed economics - -When a material scenario depends on a stream not represented in trailing results, bridge from -observable drivers rather than applying a TAM percentage: - -```text -addressable units -× adoption or penetration -× price per unit -= revenue -× contribution margin -− incremental fixed cost -− capex and working-capital needs -= incremental FCFF -``` - -Use the actual economic unit: customer, seat, location, device, transaction, capacity unit, or -contract. Source price, volume, churn, utilization, cost to serve, and timing separately. Use -ranges when inputs are sparse. Reconcile the stream to consolidated revenue and costs so shared -expenses and cannibalization are not omitted. - -## Final check - -For each adjustment, ask: - -1. Is it already reflected elsewhere in the cash flow, share count, or enterprise bridge? -2. Does it recur economically even if accounting labels it unusual? -3. Are tax and sign conventions correct? -4. Is the estimate supported by more than management's preferred presentation? -5. Does a conservative alternative materially change the decision? - -An unexplained adjusted number is an assumption, not a fact. diff --git a/skills/bottom-up-analyst/references/guide_ownership_signals.md b/skills/bottom-up-analyst/references/guide_ownership_signals.md deleted file mode 100644 index 9f4539f..0000000 --- a/skills/bottom-up-analyst/references/guide_ownership_signals.md +++ /dev/null @@ -1,115 +0,0 @@ -# Ownership, insider activity, incentives, and governance - -Use ownership evidence when it can change alignment, liquidity, control, dilution, governance, -or the path to value. It is supporting evidence, not a substitute for operating work. Pull the -underlying records through `sec-edgar-skill` and follow that skill's current guides for retrieval -and form semantics. - -## 13F — limited institutional position evidence - -Form 13F is a delayed quarter-end disclosure by qualifying investment managers for reportable -securities over which they exercise investment discretion. It is not a complete cap table or a -record of all institutional trading. - -Before interpreting a result, record: - -- quarter-end date, filing date, and amendments; -- issuer, security class, CUSIP, shares or principal amount, and option indicator; -- whether the same exposure may appear under multiple managers or classes; and -- a period-matched share denominator if calculating ownership percentage. - -Important limits: - -- reports can arrive up to the filing deadline after quarter end; -- short positions and investment rationale are absent; -- non-reportable securities, smaller managers, and some confidential positions are absent; -- a quarter-end comparison does not show when or why a position changed; and -- shares outstanding from a later date can distort an ownership percentage. - -Use manager position history to describe reported quarter-end changes. Do not call a change -“accumulation into weakness” or “distribution” without compatible dates and additional evidence. -A well-known manager's name does not validate the thesis; the position may be hedged, passive, -small within its portfolio, or held for an unknown mandate. - -Potentially useful questions include: - -- Is reported ownership concentrated enough that a holder's exit could affect liquidity? -- Are changes broad across independently selected active holders or driven by passive flows? -- Do amendments, class changes, mergers, splits, or CUSIP changes explain the movement? - -Label computed percentages `[E]` and state the denominator and dates. Never present the sum of -available 13F rows as definitive institutional ownership or float ownership. - -## 13D, 13G, and the proxy — beneficial ownership and control - -Schedules 13D/13G and proxy beneficial-ownership tables answer different questions from 13F. -Use them directly when the thesis concerns a blockholder, activist purpose, voting control, or -insider ownership. - -Check: - -- beneficial owner, group status, class, shares, percentage, and measurement date; -- voting and dispositive power, direct versus indirect ownership, and footnotes; -- amendments and changes in purpose; -- Item 4 plans or proposals in Schedule 13D; and -- dual-class rights, agreements, pledges, and related entities. - -Do not infer activism merely because a manager also appears in a 13F list. Schedule 13G is not a -synonym for passive in every case; use the filing category and disclosed facts. - -## Form 4 — transaction evidence, not mind reading - -Read transaction code, price, shares, direct/indirect ownership, footnotes, derivative table, -10b5-1 indicator, transaction date, filing date, and post-transaction amount together. - -- **P** is an open-market or private purchase and is usually the cleanest voluntary cash signal. -- **S** is a sale, but motive requires context from footnotes, plan disclosure, ownership, size, - history, and compensation. -- **M** is an option exercise, **F** commonly covers tax withholding, **A** is a grant or award, - and **G** is a gift. Do not mix these mechanically into a buy/sell ratio. - -Use the reported 10b5-1 checkbox and adoption date where available. Do not infer plan status -solely from a regular trading cadence. Likewise, timing near an event does not establish intent. -Phrase suspicious patterns as questions or risks unless direct evidence supports more. - -“Remaining shares” is a post-transaction amount for the reported ownership line. It may omit -other direct, indirect, or derivative holdings and should not be treated automatically as the -person's aggregate beneficial ownership. Use the proxy and all relevant ownership rows for an -alignment calculation. - -Useful interpretation compares transaction size with prior holdings, compensation, liquidity, -and the insider's history. Avoid universal dollar thresholds: materiality differs by person and -company. Cluster purchases can be notable, but check whether they were voluntary, independently -decided, and economically meaningful. - -## Incentives and governance - -For a full memo, review the proxy and related filings when these items can change value: - -- performance metrics and whether compensation rewards per-share value, growth at any price, or - a manipulable adjusted measure; -- option and equity grants, dilution, repricing, and share-count history; -- insider ownership, pledging, hedging, and change-of-control arrangements; -- board independence, tenure, relevant expertise, and controller rights; -- related-party transactions and conflicts; -- capital-allocation record versus stated policy; and -- voting structure, proposals, and minority protections. - -Compensation metrics are inputs to an incentive analysis, not proof of behavior. Compare what -management was paid to do with what it actually did and the per-share outcome. - -Foreign private issuers may not file Forms 3/4/5 and may use home-country governance documents. -State the gap and use the relevant regulator or issuer record when material. - -## Memo output - -Include only decision-relevant ownership and governance evidence. A compact section may contain: - -1. control and beneficial ownership; -2. material 13F position changes with period caveats; -3. voluntary insider purchases and material sales with transaction-code context; -4. dilution and incentive alignment; and -5. the resulting implication for liquidity, control, capital allocation, or thesis risk. - -Cite the filings and dates. If the data are unavailable, stale, or ambiguous, say so rather than -turning absence into a positive or negative signal. diff --git a/skills/bottom-up-analyst/references/guide_valuation.md b/skills/bottom-up-analyst/references/guide_valuation.md deleted file mode 100644 index c0f5287..0000000 --- a/skills/bottom-up-analyst/references/guide_valuation.md +++ /dev/null @@ -1,206 +0,0 @@ -# Valuation — match the method to the economics - -Valuation is a set of conditional claims, not a ritual. Choose methods that fit the business, -state what each method assumes, and reconcile them to the same security, date, currency, share -count, and capital structure. Multiple inapplicable methods do not create triangulation. - -The bundled scripts cover enterprise DCF and EPV for non-financial operating companies. They do -not replace a segment model, asset appraisal, transaction waterfall, or probability tree. - -## Build the enterprise-to-equity bridge - -Before comparing per-share values, show the bridge: - -```text -value of operating assets -+ excess cash and non-operating assets -− funded debt -− preferred and minority interests -− pension deficits and other senior claims -− value attributable to outstanding options or similar instruments, if not in shares -= value of common equity -÷ consistent diluted share count -= value per share -``` - -Avoid burying all adjustments in “net debt.” Match the bridge date to the base cash flow and -adjust for material subsequent transactions. Reconcile basic, reported diluted, and modeled -future shares. - -## Enterprise DCF - -### Cash-flow basis - -The DCF script accepts free cash flow to the firm (FCFF): after-tax operating cash flow before -interest and net borrowing. Discount FCFF at WACC to obtain enterprise value, then subtract net -debt and other senior claims. Do not pass owner earnings or FCFE that already includes interest -and then subtract debt again. - -Read `guide_normalization.md` for the reconciliation. A growing terminal state must include the -reinvestment needed to support that growth; terminal FCFF cannot assume growth while silently -removing its capital needs. - -### Choose the route - -Use the script path resolved from the installed skill. - -**Forward growth sensitivity** works for a positive, normalized FCFF base when a constant rate -is a tolerable abstraction: - -```bash -python "/scripts/dcf.py" forward --fcff0 1200 --growth 8,12,16 \ - --years 10 --terminal-growth 3 --wacc 10 --shares 500 --net-claims 200 --price 75 -``` - -Comma-separated growth values vary growth while holding every other input fixed. They are a -sensitivity, not complete bear/base/bull scenarios. Run separate commands when margins, -reinvestment, WACC, dilution, or the capital structure also differ. - -**Explicit forecast** is preferable when FCFF begins negative or changes shape. Forecast each -year from revenue, margin, tax, reinvestment, and working-capital drivers: - -```bash -python "/scripts/dcf.py" forecast --fcff=-20,10,45,80,110 \ - --terminal-growth 2.5 --wacc 12 --shares 30 --net-claims 66 --price 8 -``` - -The final explicit FCFF must be positive because it anchors a Gordon terminal value. Make the -transition to stable economics plausible rather than jumping from an immature margin directly -to perpetuity. - -**Reverse growth DCF** asks which constant positive-FCFF growth rate equates the model to price: - -```bash -python "/scripts/dcf.py" reverse --price 75 --fcff0 1200 --years 10 \ - --terminal-growth 3 --wacc 10 --shares 500 --net-claims 200 -``` - -The answer is conditional on every other input. It is informative only when positive base FCFF -and the model shape represent the business. It does not solve for revenue growth, margin, or -dilution, and it should not be presented as “the market's” unique forecast. For an immature -business, construct an operating model and test combinations of scale, margin, reinvestment, -and dilution that reconcile to price instead. - -### Terminal value - -A terminal state should be economically mature: - -- terminal growth is consistent with the currency and long-run market opportunity; -- return on new capital and reinvestment support the growth rate; -- margins and competitive position have faded or stabilized plausibly; -- capital intensity, taxes, and dilution are normalized; and -- WACC exceeds terminal growth. - -Report the terminal value as a percentage of enterprise value and cross-check its implied -terminal multiple. A high percentage is not automatically wrong, but it identifies where the -model is least anchored by near-term evidence. - -## Earnings Power Value - -EPV capitalizes normalized no-growth operating earnings at WACC. Without the optional -maintenance-capex refinement, it assumes D&A and maintenance capex offset: - -```text -normalized after-tax EBIT = EBIT × (1 − normalized cash tax rate) -operating cash earnings = after-tax EBIT + D&A − maintenance capex -EPV of operations = operating cash earnings ÷ WACC -``` - -Use the D&A refinement only when both D&A and maintenance capex are estimated on a consistent -basis: - -```bash -python "/scripts/epv.py" --ebit 600 --tax 21 --wacc 9 \ - --shares 500 --net-claims 200 --da 100 --maint-capex 85 --price 10 -``` - -EPV is a no-growth operating case, not a guaranteed floor. It can overstate value when earnings -are cyclical, assets are deteriorating, maintenance investment is understated, customers are -leaving, or liabilities sit outside the model. For cyclicals, use defensible mid-cycle earnings -and separately test trough liquidity. - -## Relative and transaction evidence - -Use multiples only when numerator, denominator, growth, accounting, leases, and capital -structure are comparable. Match enterprise multiples with pre-interest measures and equity -multiples with post-interest measures. Explain why a peer deserves the same or a different -multiple; an automated peer table is only a candidate list. - -Useful anchors may include EV/EBIT, EV/FCFF, P/E, P/FCFE, unit value, replacement cost, and -precedent transactions. Sales multiples require an explicit margin and reinvestment bridge. -Historical multiples are evidence about prior expectations and rates, not intrinsic value. - -Asset plays and special situations generally require their own arithmetic: - -- sum-of-parts with segment-specific methods and corporate-cost allocation; -- liquidation or realizable NAV with asset haircuts, liabilities, tax, and timing; -- transaction outcomes with payoff, probability, timing, break value, and interim cash flows; - and -- annualized expected return rather than an unadjusted spread. - -Do not turn uncertain legal interpretation into a precise probability without qualified support. - -## Discount rate - -No fixed WACC or required-return table is timeless or company-specific. Derive a rate from -current inputs, document the date and sources, and sensitize it. - -For an enterprise DCF: - -```text -cost of equity = risk-free rate + beta × equity risk premium -WACC = E/(D+E) × cost of equity + D/(D+E) × pre-tax cost of debt × (1 − tax rate) -``` - -Add country or other risk components only when they are not already captured elsewhere. Use -market-value capital weights where observable. Estimate debt cost from current borrowing terms, -yield, or a defensible default spread rather than the historical coupon. - -A bottom-up beta can be useful: choose operationally comparable firms, unlever their equity -betas using consistent market D/E and tax assumptions, take a robust central estimate, and -re-lever for a defensible current or target capital structure. But beta is a noisy model input, -not a fact. A thin or poor peer set may justify broader industry data, an alternative required -return, or wider sensitivity rather than false precision. - -Using WACC for FCFF and then subtracting debt is not double-counting. WACC discounts operating -cash flow using financing costs; the debt subtraction allocates enterprise value to common -equity. Double-counting occurs when the same expected loss, lease burden, pension contribution, -or distress effect is embedded in both cash flow and an additional adjustment without -reconciliation. - -If leverage or survival changes across scenarios, reflect financing costs, refinancing, -dilution, and default risk explicitly. A single normalized WACC can conceal the path dependency -of a distressed equity. - -The memo should show enough of the derivation for a reader to replace the rate, but it need not -force a ceremonial subsection or peer-beta table when another method is better supported. - -## Scenario design and margin of safety - -Name scenarios for the mechanism that differs, not merely bear/base/bull. At minimum disclose: - -- revenue or unit path; -- operating margin and reinvestment; -- taxes and working capital; -- financing, dilution, and enterprise bridge; -- discount and terminal assumptions; and -- evidence supporting the scenario weight, if probabilities are used. - -Use sensitivity around the two or three variables that dominate value. Report value per share -and the price discount or premium to each relevant outcome. Margin of safety is a conclusion -about downside, uncertainty, and required return; no universal percentage substitutes for the -quality of the inputs. - -## Method selection by thesis shape - -| Thesis shape | Usually useful | Common misuse | -| :-- | :-- | :-- | -| Compounder | operating DCF, reinvestment/runway cases, reverse check | extrapolating current ROIC forever | -| Cash-burning growth | explicit operating forecast, price-reconciliation scenarios | growing a negative FCFF base | -| Cyclical | mid-cycle EPV/DCF, trough balance sheet, asset or unit values | valuing peak earnings at a spot multiple | -| Turnaround | explicit transition cases, failure case, financing path | applying target margins immediately | -| Special situation | payoff tree, waterfall, SOTP, annualized return | DCF obscuring the binding event terms | -| Deep value | realizable NAV/liquidation, burn and timing, EPV where durable | calling EPV or book value a hard floor | - -End with the range supported by the evidence, the assumptions that dominate it, and the -conditions under which the range ceases to be useful. diff --git a/skills/bottom-up-analyst/references/memo_template.md b/skills/bottom-up-analyst/references/memo_template.md deleted file mode 100644 index c4b6990..0000000 --- a/skills/bottom-up-analyst/references/memo_template.md +++ /dev/null @@ -1,158 +0,0 @@ -# Full due-diligence memo - -Use this skeleton for a requested deep dive. It is not a questionnaire: combine, reorder, or omit -sections when that improves the argument, and add a section when the company's economics demand -it. A special situation, cyclical, and compounder should not produce identical memos. - -## Evidence notation - -Use the notation consistently on load-bearing factual and model claims: - -- **[V]** checked against a cited authoritative primary record; -- **[E]** calculated or modeled, with inputs and units; -- **[A]** unresolved assumption, with its decision impact; and -- **[W]** external, trade, channel, expert, or secondary evidence, named and dated. - -The tag does not replace a citation. Do not label an analytical inference `[V]` merely because -its inputs are verified; state that it is an inference. Ordinary connective prose does not need -a tag. - -## Header - -```markdown -# [Company] ([Ticker / share class]) — investment memo -**As of:** [date, time zone where relevant] -**Question:** [decision being evaluated] -**Decision:** [Long / Watch / Pass] -**Conviction:** [plain-language level and why] -``` - -## Decision snapshot - -Select the small set of current metrics that orient this specific case. Do not reproduce a -fixed stat block inherited from another pitch or fill irrelevant cells. Possibilities include: -price and market value, enterprise value, diluted shares, net debt, normalized FCFF, valuation -range, cycle position, unit metric, asset value, liquidity runway, or event spread. Label dates, -periods, currencies, and adjustments. - -Then state in a few sentences: - -- what the market price appears to require; -- the variant view, if one exists; -- the decisive evidence; -- what could make the view wrong; and -- why the current price does or does not compensate for that uncertainty. - -If no differentiated view is established, say so. A clear pass is better than an invented -variant perception. - -## Business and economic model - -Explain in plain language: - -- product or service, customer, payer, and unit of sale; -- segments and where gross profit and cash flow arise; -- pricing, volume, retention, cyclicality, and capital needs; and -- the few operating variables that govern value. - -Name the analytical lens or lenses only if they sharpen the decision. Do not force the company -into an archetype. - -## Reported-to-normalized economics - -Reconcile reported results to the cash-flow basis used in valuation. Include the periods and -metrics that reveal the economics rather than a mandatory table. Show: - -- recurring versus non-recurring items; -- organic versus acquired growth; -- maintenance and growth investment; -- working-capital and deferred-revenue timing; -- stock compensation and diluted shares; -- lease treatment; and -- capital allocation and return on incremental capital where meaningful. - -Use `guide_normalization.md`. If a new stream or future margin structure carries material value, -include a driver bridge from volume and price through costs, reinvestment, and FCFF. - -## Competitive and industry underwriting - -Define the relevant market and profit pool, identify economically comparable peers, and explain -the company's position through mechanisms and evidence. Connect material advantages and threats -to an operating assumption, scenario, or monitorable. - -Quantify where evidence supports it. Where it does not, use a range, break-even calculation, -leading indicator, or explicit `[A]` gap rather than invented precision. Use -`guide_competitive.md`. - -## Management, ownership, and governance - -Include this section when control, incentives, dilution, capital allocation, insider activity, -or holder concentration can affect the outcome. Distinguish: - -- beneficial ownership and voting control from 13F positions; -- voluntary Form 4 purchases and sales from grants, exercises, tax withholding, and gifts; -- reported quarter-end 13F changes from inferred trading intent; and -- compensation design from demonstrated capital-allocation behavior. - -Use `guide_ownership_signals.md`. Keep immaterial holder lists out of the memo. - -## Valuation and expectations - -Use methods that fit the business and reconcile each to common equity. State: - -- valuation date, currency, and current price; -- reported-to-normalized cash-flow bridge; -- enterprise-to-equity bridge and diluted shares; -- explicit operating scenarios and their evidence; -- discount-rate and terminal assumptions; -- value per share or payoff under relevant outcomes; and -- price discount/premium, downside, and required return. - -A reverse DCF is useful only if its positive-FCFF model describes the company. EPV is a no-growth -case, not a hard floor. Growth sensitivity alone is not a bear/base/bull analysis when margins, -capital needs, dilution, or financing also change. Use `guide_valuation.md`. - -Summarize the assumptions that dominate the result and show the sensitivity that matters. Do -not require a ceremonial peer-beta table if another discount-rate method is better supported. - -## Countercase and pre-mortem - -Make the strongest good-faith case against owning the security. Run the relevant archetype -disqualifiers, then answer: - -- Which fact, inference, or assumption is most likely wrong? -- What permanent impairment path exists? -- What financing, dilution, control, or liquidity event could intervene? -- Which downside estimate is genuinely anchored, and which is not? -- If the thesis has failed one year from now, what probably happened? - -Size material effects when the evidence supports it. For discontinuous or poorly disclosed -risks, describe the mechanism, exposure, leading indicator, and decision impact instead of -inventing a probability. - -## Catalysts, falsifiers, and monitorables - -List observable developments that change probability or value. For each, state the expected -time window, source to check, and what outcome confirms or weakens the thesis. A catalyst needs a -mechanism; “re-rating” alone is an outcome. - -Separate a catalyst from a falsifier. The latter is the evidence that should make the investor -exit or revisit the work even if price has not cooperated. - -## Verdict - -Conclude **Long**, **Watch**, or **Pass** at the confidence supported by the research. Tie the -verdict to valuation, the variant view, and the countercase. State unresolved work and the price -or evidence that would change the decision. - -## Sources and calculation notes - -Provide an audit trail for material claims: - -- SEC form, filing date, accession, and item or section; -- issuer, regulator, court, or industry document title and date; -- external URL, publisher, publication date, and access date where relevant; and -- calculation inputs, units, periods, and formulas. - -Do not dump every document opened. Include the sources on which the argument actually relies and -preserve conflicting evidence. diff --git a/skills/bottom-up-analyst/.gitignore b/skills/due-diligence/.gitignore similarity index 71% rename from skills/bottom-up-analyst/.gitignore rename to skills/due-diligence/.gitignore index 6c13274..89e0362 100644 --- a/skills/bottom-up-analyst/.gitignore +++ b/skills/due-diligence/.gitignore @@ -6,5 +6,5 @@ __pycache__/ # SEC cache (regenerated on demand by the data layer when the stack runs here) sec-cache/ -# Transcript cache (regenerated on demand by market-scout) +# Transcript cache (regenerated on demand by market-data) transcript-cache/ diff --git a/skills/due-diligence/README.md b/skills/due-diligence/README.md new file mode 100644 index 0000000..b7d0f34 --- /dev/null +++ b/skills/due-diligence/README.md @@ -0,0 +1,34 @@ +# Due Diligence + +An [agent skill](SKILL.md) for long-only due diligence on one US-listed operating company. It +turns filing, market, industry, and ownership evidence into a scoped answer or a full, +auditable memo. Banks, insurers, REITs, funds, and binary-asset companies need other +frameworks. + +## What it does + +- Sizes the work to the question; a full memo only for a deep dive or explicit request. +- Tags evidence as verified, estimated, assumed, or external, with citations. +- Reconciles reported results to one cash-flow basis without double-counting stock + compensation, leases, working capital, or bridge items. +- Underwrites competitive advantage as a causal chain, not a label. +- Chooses valuation methods that fit the cash flows, and lets conviction fall to the weakest + load-bearing link. + +## Layout + +- `SKILL.md` — evidence discipline, the moves of the work, completion bar. +- `references/normalization.md` — reported-to-cash bridge and where adjustments go wrong. +- `references/valuation.md` — enterprise bridge, script usage, valuation traps. +- `references/archetypes.md` — edge, traps, valuation route, and tell for six thesis shapes. +- `references/memo.md` — full-memo spine. +- `scripts/dcf.py`, `scripts/epv.py` — standard-library FCFF DCF (forward, forecast, + reverse) and Earnings Power Value. Python 3.10+. + +Install and configure [`sec-filings`](../sec-filings/) for SEC evidence and +[`market-data`](../market-data/) for market data and transcripts. + +## Scope and judgment + +This skill supports research, not personalized investment advice. A human remains responsible +for checking the evidence, assumptions, suitability, and decision. diff --git a/skills/due-diligence/SKILL.md b/skills/due-diligence/SKILL.md new file mode 100644 index 0000000..c3e9015 --- /dev/null +++ b/skills/due-diligence/SKILL.md @@ -0,0 +1,86 @@ +--- +name: due-diligence +description: >- + Long-only due diligence on one US-listed operating company: investment thesis, valuation, + earnings quality, bull/bear case, buy/watch/pass, or a full memo. Built for businesses whose + economics can be underwritten from public evidence, including cash-burning growers with + visible unit economics. Banks, insurers, REITs, funds, and binary-asset companies need other + frameworks. +--- + +# Due diligence + +Decide whether the price compensates for what can go wrong, using evidence a skeptical reader +can audit. *Pass* and *watch* are full answers. Size the work to the question: a scoped +question gets a scoped answer, and the full memo is for a deep dive or an explicit request. + +## Evidence + +Tag load-bearing claims and table rows (not prose): + +- **[V]** checked against an authoritative primary record, cited by form, period, + section or accession, and date; +- **[E]** calculated, with formula, inputs, units, and dates; +- **[A]** assumed, with what would confirm it and what changes if it is wrong; +- **[W]** web, trade, expert, or secondary, with source and date; `[W]` records where a claim + came from, not whether it is true. + +An inference from verified premises is an inference: cite the premises, then state it. An issuer +filing verifies what the issuer said, not that its framing is neutral. Use the source that is +authoritative for each claim (filings for filed numbers, IR for an unfiled release, the +regulator for a rule), and when sources conflict, report the conflict. + +Use `sec-filings` for filings and `market-data` for prices and transcripts. Timestamp market +data. For a full review, read the latest 10-K and the material filings since. + +## The work + +These are moves, not a form. Skip what the question does not need, and disclose what you +skipped. + +1. **Frame.** Pin down the security, share class, as-of date, and the question. Write down what + the current price requires to be true: that is the expectation you are testing. +2. **Reconstruct the economics.** Bridge reported earnings to the cash flow the valuation uses, + following `references/normalization.md`. When value rests on something that is not yet in + the numbers, build it from operating drivers; an unsupported TAM share or margin target is + `[A]`. +3. **Underwrite the business.** Explain where industry profit pools and why this company keeps + its share. Write each claimed advantage as a chain: *asset or position → customer or cost + consequence → operating evidence → economic result → why rivals can't copy it*. A label + ("moat", "network effect") without the chain does no work. Choose peers by economics, not by + sector code. Size threats where the evidence allows; otherwise give a range or name the + leading indicator. +4. **Judge the stewards** when they can move value: incentives, dilution, capital allocation, + control, related parties. 13F and Form 4 data are lagged clues; the + `sec-filings` skill's `references/ownership.md` before interpreting them. +5. **Value it** with methods that fit the cash flows, following `references/valuation.md`. +6. **Try to kill it.** Make the strongest honest case against owning it, run the archetype's + disqualifiers, and run a pre-mortem: a year from now this failed; what happened? Separate + permanent impairment from volatility, and name the falsifiers and the date by which evidence + should arrive. +7. **Deliver.** For a full memo, use `references/memo.md`. Otherwise give the conclusion, the + decisive evidence, the arithmetic, the countercase, the open gaps, and the sources. + +## Archetypes + +When one or two archetypes sharpen the case, read their sections in `references/archetypes.md`. +Each section names the archetype's edge, its traps, its valuation route, and the indicator that +breaks first. If none fits, reason from the business directly. + +| Archetype | The thesis turns on | +| :-- | :-- | +| compounder | incremental returns on capital and reinvestment runway | +| hypergrowth | immature margins, unit economics, path to positive cash flow | +| cyclical | normalized earnings, cost position, surviving the trough | +| turnaround | one specific mechanism changing margins, demand, or capital structure | +| special situation | a transaction, legal term, security, or forced flow | +| deep value | realizable assets and a path to realizing them | + +## Done when + +- the security, share class, and every source period are unambiguous; +- every load-bearing number is cited or tagged; +- the arithmetic reconciles: one cash-flow basis, an enterprise-to-equity bridge, diluted + shares, and price as of a stated date; +- the strongest countercase has an answer; and +- conviction matches the weakest load-bearing link, and omitted work is disclosed. diff --git a/skills/due-diligence/references/archetypes.md b/skills/due-diligence/references/archetypes.md new file mode 100644 index 0000000..10e0edc --- /dev/null +++ b/skills/due-diligence/references/archetypes.md @@ -0,0 +1,85 @@ +# Archetypes + +Read only the section or two that fit. Each one names the edge, the traps that should cut or +kill the case, the valuation route, and the *tell*: the indicator that shows the thesis +breaking before the headline numbers do. + +## Compounder + +**Edge:** duration and reinvestment, not a "quality" label. Sustainable growth ≈ reinvestment +rate × return on *incremental* capital, after dilution and acquisitions. +**Traps:** ROIC is an accounting artifact or omits required assets; incremental returns are +sliding toward the cost of capital; growth relies on M&A or spending the model excludes; the +runway is used up or copyable; the moat is really concentration, regulation, or a temporary +shortage; buybacks above value or merely offsetting dilution; enterprise growth that never +reaches per-share value. +**Value:** a forecast tied to reinvestment capacity and returns; a reverse check of the duration +the price implies. A terminal premium needs normalized reinvestment, not adjectives. +**Tell:** the operating metric where runway or return decay appears first. + +## Hypergrowth (cash-burning, observable unit economics) + +**Edge:** profit understates mature economics. Separate earned growth from purchased growth, +mature cohorts from the blended average, gross retention from expansion, and reachable demand +from TAM. +**Traps:** mature cohorts are still uneconomic; growth requires rising incentives or falling +prices; metric definitions drift; no plausible scale-and-margin path reconciles to the price; +funding runs out before break-even, or dilution swamps the outcome; costs are modeled to vanish +rather than scale. +**Value:** `dcf.py forecast` built from explicit revenue, margin, reinvestment, and dilution, +including financing until the company is cash-positive. Do not grow a negative base. +**Tell:** the metric that separates investment from bad unit economics, and the date by which it +should show. + +## Cyclical + +**Edge:** pricing on normalized rather than spot earnings, with a balance sheet that survives the +trough. Identify the real cycle driver and separate it from secular change. +**Traps:** "mid-cycle" anchored to a favorable stretch; liquidity or covenants fail in the +downside path; a high position on the cost curve; new capacity or substitution keeps the old +cycle from returning; management adds capacity at peaks and issues equity at troughs; the thesis +needs timing precision the evidence lacks. +**Value:** trough, normal, and strong cases with FCFF, liquidity, and dilution for each; +mid-cycle EPV or DCF; asset and replacement values. A spot multiple on peak earnings is not +evidence. +**Tell:** the supply, inventory, or utilization indicator that would prove mid-cycle too high. + +## Turnaround or inflection + +**Edge:** one identified change → the operating line it hits → size and timing → cash cost → +evidence so far → FCFF if it works. Separate self-help from external recovery. +**Traps:** no mechanism, only cheapness or targets; progress visible only in adjusted figures; +the runway ends before evidence arrives; savings offset by lost revenue or stranded costs; an +ordinary cyclical rebound passed off as an inflection; management has missed similar plans +before; a price that already assumes success. +**Value:** failure, partial, and success cases through `dcf.py forecast`, with implementation +cost, timing, and financing. Never award the target margin on day one. +**Tell:** dated milestones and the cash runway that separate "delayed" from "broken". + +## Special situation + +**Edge:** reading the operative document precisely and getting the capital structure complete. +Read the agreement, indenture, plan, or order itself, not a summary of it. A document verifies +its text, not your legal reading of it; mark the interpretation `[A]`. +**Traps:** a condition, definition, consent, financing out, or senior claim defeats the apparent +term; minority protections are weak; an open-ended timeline lets carry costs eat the return; +break value is pegged to the unaffected price without re-underwriting the business; +probabilities have no base rate; taxes, fees, proration, or liquidity change the payoff to the +exact security. +**Value:** a payoff for each outcome to the exact class, with interim cash, probability basis, +timing, and annualized return; rebuild the post-event balance sheet. +**Tell:** the next document or decision date that resolves the binding term. + +## Deep value or asset play + +**Edge:** conservatively realizable value per diluted share, plus someone able and willing to +realize it. +**Traps:** restricted cash, liens, senior claims, or contingencies consume the cushion; burn +erodes it before realization; assets won't realize at the assumed value; a controller can +delay or divert value; pay, related-party leakage, or dilution eats the discount; taxes and +transaction costs erase it; there is no decision-maker and no path. +**Value:** a realizable-value bridge (adjusted cash, recoverable working capital, appraised +assets, minus every claim, burn through realization, and tax and transaction costs), with +ranges for recovery and timing. Model the outcomes; do not multiply the discount by a +probability. +**Tell:** the rate at which the asset cushion is melting, and who controls realization. diff --git a/skills/due-diligence/references/memo.md b/skills/due-diligence/references/memo.md new file mode 100644 index 0000000..259e99e --- /dev/null +++ b/skills/due-diligence/references/memo.md @@ -0,0 +1,37 @@ +# Memo + +A full memo is a decision document whose evidence a reader can audit. The spine below is the +default order. Merge, drop, or add sections whenever the company's economics call for it: a +special situation, a cyclical, and a compounder should not read alike. + +```markdown +# [Company] ([Ticker / class]) — investment memo +**As of:** [date] · **Question:** [decision] · **Decision:** Long / Watch / Pass +**Conviction:** [level, and the weakest load-bearing link] +``` + +1. **Decision snapshot.** Give the few figures that orient *this* case (not a stock header), + with dates and units. Then: what the price requires, the variant view if there is one, the + decisive evidence, what would make you wrong, and why the price does or does not pay for + that. With no variant view, say so. +2. **Business and economics.** Who pays, for what unit, and where gross profit and cash arise; + the few variables that govern value. +3. **Reported to normalized.** The bridge that feeds the valuation, plus any driver bridge for a + new stream. +4. **Competitive position.** The profit pool, economic peers, and two or three advantage chains + with erosion tests. Include it only if it changes an assumption, probability, or monitorable. +5. **Stewards.** Include when control, incentives, dilution, or capital allocation can change the + outcome. Keep lists of immaterial holders out. +6. **Valuation.** Methods, bridge, scenarios named by mechanism, dominant assumptions, + sensitivity, and value per share against price. +7. **Countercase and pre-mortem.** The strongest case against owning it; the assumption most + likely wrong; the permanent-impairment path; financing or control events; which downside + figure is anchored and which is not. +8. **Catalysts, falsifiers, monitorables.** For each: the mechanism, time window, source to + check, and the result that confirms or weakens the thesis. "Re-rating" is an outcome, not a + catalyst. A falsifier means exit or rework, whatever the price does. +9. **Verdict.** Long, Watch, or Pass, tied to valuation and the countercase; the price or + evidence that would change it; the work still open. +10. **Sources and calculations.** Only the sources the argument relies on: form, filing date, + accession, and section; document titles and dates; URLs with access dates; calculation + inputs and formulas. Preserve conflicting evidence. diff --git a/skills/due-diligence/references/normalization.md b/skills/due-diligence/references/normalization.md new file mode 100644 index 0000000..f017747 --- /dev/null +++ b/skills/due-diligence/references/normalization.md @@ -0,0 +1,54 @@ +# Normalization + +Bridge reported results to the repeatable cash economics the valuation uses. Show every +adjustment with its source period, rationale, tax effect, and size, so a reader can undo it. +Use several periods, because a single adjusted year is easy to cherry-pick. A cyclical needs a +whole cycle. + +## Pick the basis first + +```text +FCFF = EBIT × (1 − normalized cash tax rate) + D&A − capex − Δ operating working capital +``` + +FCFF comes before interest, is discounted at WACC, and is what the bundled scripts take. Cash +flow built from net income or CFO is after interest under US GAAP, which makes it an equity +cash flow (FCFE), discounted at cost of equity with no debt subtracted afterwards. IFRS can put +interest in other cash-flow sections, so reconcile. Mixing the two bases is the most common +silent error. + +## Where adjustments go wrong + +- **"One-time" items.** Restructuring, litigation, and acquisition costs that keep recurring + are operating costs. Remove an item only if its mechanism has demonstrably ended. +- **Taxes.** Use the expected cash burden (jurisdiction mix, NOLs and their expiry, credits), + not the statutory rate. +- **Stock compensation.** EBIT already expenses it, while CFO adds it back. Charge it exactly + once: keep the expense in EBIT-based FCFF, *or* model the cash needed to offset dilution, but + not both. Buybacks that only absorb grants are not returns of capital. Show the history of + basic and diluted share counts. +- **Maintenance capex.** Triangulate from management's split (an issuer estimate), capex in + low-growth years, replacement cost against D&A (old assets plus inflation push maintenance + above D&A), and peers. Give a range when it is uncertain. Growth capex is not free; tie it to + the revenue and returns it buys. +- **Working capital.** An increase uses cash. Before calling a release repeatable, rule out + factoring, payables stretch, inventory aging, and channel loading. Deferred revenue is timing, + not extra cash to add back, because CFO already counts it. +- **Leases.** Pick one convention and carry it through earnings, cash flow, debt, and peer + multiples. Expensing rent *and* adding the lease liability to debt double-counts. +- **Acquisitions.** Separate organic growth from acquired growth. A roll-up's acquisition + spend is part of its reinvestment. +- **Non-GAAP.** Reconcile management's metrics to GAAP and track changes in their definitions. + +## New streams + +When value depends on revenue not yet in the numbers, build it in the business's actual unit +(customer, seat, store, device, contract): + +```text +units × adoption × price = revenue +revenue × contribution margin − incremental fixed cost − capex − working capital = incremental FCFF +``` + +Source each input separately, use ranges when inputs are sparse, and reconcile to consolidated +results so shared costs and cannibalization show up. diff --git a/skills/due-diligence/references/valuation.md b/skills/due-diligence/references/valuation.md new file mode 100644 index 0000000..5687735 --- /dev/null +++ b/skills/due-diligence/references/valuation.md @@ -0,0 +1,83 @@ +# Valuation + +Pick the methods the cash flows support. Running a method that does not fit adds no +triangulation. Every method has to land on the same security, date, currency, share count, and +capital structure. + +## Enterprise to equity + +```text +operating value + excess cash and non-operating assets +− debt − preferred − minorities − pension deficit − other senior claims +− options and similar claims not already in the share count += common equity ÷ diluted shares (same date) = value per share +``` + +Show the whole bridge instead of folding it into "net debt", and date it to match the base +cash flow. The scripts take everything below operating value as one `--net-claims` figure +(negative when non-operating assets exceed the claims). + +## Scripts + +Run them with `python "/scripts/…"`. Inputs are FCFF (see `normalization.md`) in one +monetary unit, shares in the matching count unit, and rates in percent. Pass `--price` to print +the discount or premium. + +```bash +# constant-growth sensitivity; needs a positive base FCFF; add --growth2/--years2 for a second stage +dcf.py forward --fcff0 1200 --growth 8,12,16 --years 10 --terminal-growth 3 --wacc 10 \ + --shares 500 --net-claims 200 --price 75 +# explicit annual FCFF; use this for losses or inflections; the final year must be positive +dcf.py forecast --fcff=-20,10,45,80,110 --terminal-growth 2.5 --wacc 12 --shares 30 \ + --net-claims 66 --price 8 +# growth implied by the price +dcf.py reverse --price 75 --fcff0 1200 --years 10 --terminal-growth 3 --wacc 10 \ + --shares 500 --net-claims 200 +# no-growth earnings power; --da and --maint-capex go together +epv.py --ebit 600 --tax 21 --wacc 9 --shares 500 --net-claims 200 [--da 100 --maint-capex 85] +``` + +Discounting FCFF at WACC and then subtracting debt is not double-counting. Double-counting +happens when one burden (leases, pensions, distress) sits in both the cash flow and the bridge. + +## Traps + +- **Growth sensitivity is not a set of scenarios.** Comma-separated growth rates vary one input. + When margins, reinvestment, dilution, or financing also change, run each scenario as its own + command, named for the mechanism that differs. +- **Reverse DCF** reads only when a positive base FCFF and constant growth describe the business. + For an immature company, find which combinations of scale, margin, reinvestment, and dilution + reconcile to the price instead. +- **Terminal value** assumes a mature state: growth funded by reinvestment (g = reinvestment + rate × return on new capital), margins faded to defensible levels, WACC above g. Report the + terminal value as a share of EV (the scripts print it) and its implied multiple (compute it), because that is where the model is + least anchored. +- **EPV is not a floor.** It assumes steady-state working capital and overstates value when earnings are at a cyclical peak, assets are + decaying, maintenance is understated, or liabilities sit outside the model. Use mid-cycle + earnings for cyclicals. +- **Multiples** compare only when numerator, denominator, accounting, leases, and capital + structure match: enterprise multiples over pre-interest measures, equity multiples over + post-interest. A revenue multiple is a margin and reinvestment assumption in disguise; make + the bridge explicit. +- **Discount rate.** Derive it from current inputs (the risk-free rate from `^TNX` via + `market-data`, today's debt cost rather than the historical coupon) and sensitize it. Beta is + noisy; a thin peer set argues for a wider range, not false precision. Distressed equity needs + financing, dilution, and default modeled per scenario, not one blended WACC. +- **Asset plays and special situations** need their own arithmetic: sum of the parts with + corporate costs allocated, realizable NAV after haircuts, taxes, and time, or a payoff tree + with probabilities, timing, interim cash, and break value. Compare annualized returns, not raw + spreads. + +## Method by thesis shape + +| Shape | Usually useful | Common misuse | +| :-- | :-- | :-- | +| Compounder | operating DCF, runway cases, reverse check | extrapolating today's ROIC forever | +| Cash-burning growth | explicit forecast, price-reconciliation scenarios | growing a negative FCFF base | +| Cyclical | mid-cycle EPV/DCF, trough balance sheet, asset values | spot multiple on peak earnings | +| Turnaround | explicit transition cases incl. failure, financing path | target margins applied immediately | +| Special situation | payoff tree, waterfall, SOTP, annualized return | a DCF obscuring the binding terms | +| Deep value | realizable NAV, burn and timing, EPV if durable | book value or EPV as a hard floor | + +Finish with the range the evidence supports, the two or three assumptions that dominate it, and +the conditions under which the range stops being useful. diff --git a/skills/bottom-up-analyst/scripts/dcf.py b/skills/due-diligence/scripts/dcf.py similarity index 100% rename from skills/bottom-up-analyst/scripts/dcf.py rename to skills/due-diligence/scripts/dcf.py diff --git a/skills/bottom-up-analyst/scripts/epv.py b/skills/due-diligence/scripts/epv.py similarity index 100% rename from skills/bottom-up-analyst/scripts/epv.py rename to skills/due-diligence/scripts/epv.py diff --git a/skills/idea-generation/.gitignore b/skills/idea-generation/.gitignore new file mode 100644 index 0000000..2101ea7 --- /dev/null +++ b/skills/idea-generation/.gitignore @@ -0,0 +1,3 @@ +__pycache__/ +*.pyc +idea-cache/ diff --git a/skills/signal-sweep/README.md b/skills/idea-generation/README.md similarity index 85% rename from skills/signal-sweep/README.md rename to skills/idea-generation/README.md index e7c339b..cb3cab7 100644 --- a/skills/signal-sweep/README.md +++ b/skills/idea-generation/README.md @@ -1,4 +1,4 @@ -# Signal Sweep +# Idea Generation An [agent skill](SKILL.md) that discovers equity-research candidates from SEC filings and Yahoo Finance market data. It emits shortlists with source links and coverage notes; every match still @@ -14,7 +14,7 @@ requires company-level diligence. | Investor-event discovery across relevant 8-K disclosures | `scan_conferences.py` | Within [SecStack](../README.md), the skill sits upstream of -[`bottom-up-analyst`](../bottom-up-analyst/): it proposes tickers; the analyst investigates them. +[`due-diligence`](../due-diligence/): it proposes tickers; due diligence investigates them. ## Setup @@ -32,13 +32,13 @@ Set `EDGAR_IDENTITY` for insider, theme, and investor-event scans (see [profile setup](../../README.md#one-time-runtime-setup)). Market screens use Yahoo Finance only. Keep the research workspace as the current directory and invoke installed scripts by resolved -absolute path. This keeps `signal-sweep-cache/` with the research rather than the installed skill. +absolute path. This keeps `idea-cache/` with the research rather than the installed skill. See [SKILL.md](SKILL.md) for routes, semantics, and output contracts. ## Screen customization Definitions and universe bounds live in [`screens.json`](screens.json). See -[`references/guide_screens.md`](references/guide_screens.md) when adding or changing a screen; the +[`references/screens.md`](references/screens.md) when adding or changing a screen; the guide uses runtime `yfinance` discovery because provider fields can change. ## Daily workflow diff --git a/skills/idea-generation/SKILL.md b/skills/idea-generation/SKILL.md new file mode 100644 index 0000000..446660b --- /dev/null +++ b/skills/idea-generation/SKILL.md @@ -0,0 +1,29 @@ +--- +name: idea-generation +description: >- + Idea generation for US-listed equities: find new tickers worth researching from insider + buying, 13D blockholders, market screens, SEC full-text themes, investor events, or any other + filing- or price-based hunt. Use when the user wants candidates, not work on a known company. +--- + +# Idea generation + +The output is a shortlist of leads with sources; a match is a lead, not a thesis. + +Run `python "/scripts/