diff --git a/AGENTS.md b/AGENTS.md index 552a494..d5e1cc0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,66 +1,64 @@ # AGENTS.md -Universal entry point for agents working in this repo. Read this first. +Agent-maintained docs are for durable context only. Code is the source of truth; +docs route agents and preserve non-obvious project rationale. -## Guiding principle +## Guardrails -Only document what an agent **cannot quickly recover by reading the code**. Code -is the source of truth for *what the code does*. Docs exist for *where things -live* (`context/MAP.md`) and *why the tradeoffs were made* (`context/DECISIONS.md`). -Everything else rots — do not write it. +- 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. +- 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. -## Hard guardrails +## Read routing -- **Never commit to `main` directly.** Always 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. -- **Lint and format must pass** before a PR (see `context/CONVENTIONS.md`). CI - runs `ruff check`, `ruff format --check`, and `markdownlint-cli2`. +- Read `context/MAP.md` before changing module layout, ownership, or data flow. +- Read `context/DECISIONS.md` before changing a recorded tradeoff. +- Read `context/CONVENTIONS.md` while writing or editing code. +- Run `todo list` at task start; `todo claim ` before editing orchestrated + todos. -## Read routing +## Write triggers -Do not read everything by default. Read on demand: +- `context/MAP.md`: files/modules added, removed, moved, or data flow changed. +- `context/DECISIONS.md`: only choices that pass the decision-log bar below. +- `context/CONVENTIONS.md`: new repeatable coding/testing rule. +- `README.md`: user-facing setup or usage changed. -- Touching module structure or data flow → read `context/MAP.md` first. -- Changing or re-litigating a tradeoff → read `context/DECISIONS.md` first. -- Writing code → read `context/CONVENTIONS.md`. -- Starting any task → run `todo list` for open items, then `todo claim` before - execution so parallel sessions do not collide. +## Decision-log bar -## Write triggers (event-based) +`context/DECISIONS.md` is a curated ADR file, not a worklog. Append only when a +choice changes architecture, public behavior, data shape, dependency ownership, +or an expensive migration path **and** future agents need non-obvious rationale +to avoid re-litigating it. -- Module added / moved / removed, or data flow changed → update `context/MAP.md`. -- Intentional tradeoff made → **append to `context/DECISIONS.md`** (mandatory; - this is the most-forgotten artifact). -- New repeatable pattern or standard adopted → add to `context/CONVENTIONS.md`. -- User-facing behavior or usage changed → update `README.md`. +Do not append decisions for bug fixes, cleanup, dead-code removal, renames, +mechanical refactors, one-feature implementation tactics, or routine test/lint +chores. Before appending, prefer amending or superseding an existing decision. +When in doubt, do not append; keep task-local rationale in the todo, PR, commit +message, or final response. -## Do NOT document +## What not to document -- Changelog / worklog — that is git history. -- Feature or status lists — code already shows what exists. -- Restatements of what the code plainly does. -- Decisions with no real tradeoff. +- Changelogs/worklogs; git already has history. +- Feature/status checklists duplicated from code/tests. +- Restatements of obvious code behavior. +- Decisions that fail the decision-log bar. ## CONVENTIONS vs DECISIONS -A convention is **one imperative line with no "because"**. The moment it needs a -"because", it is a decision — move the rationale to `context/DECISIONS.md` and let -the convention link to it. +- `CONVENTIONS.md` contains terse imperative rules only. +- Rationale belongs in `DECISIONS.md` only if it passes the decision-log bar. ## Todos ↔ Decisions -The `todo` tool is stateful, not a scratchpad: todos are persisted under -`.pi/todos` with status, tags, body notes, subtasks, and `claim`/`release` -assignment. Keep active working context in the todo body while a task is live. - -Closed/done todos are garbage-collected (default ~7 days after creation), so -when closing a todo that involved a real tradeoff, **graduate the durable part -into `context/DECISIONS.md`** first. Closing is not archiving. +Use todos as stateful task records, not scratch notes. Keep live working context +in the todo body. Before closing a todo, graduate durable rationale to +`context/DECISIONS.md` only if it passes the decision-log bar. ## Definition of Done -A task is done only when the matching durable artifacts reflect the change. An -unrecorded tradeoff means **not done**. +Code, tests/lint, and durable docs must agree. If a change passes the +decision-log bar, its rationale must be recorded before the task is done. diff --git a/bottom-up-analyst/SKILL.md b/bottom-up-analyst/SKILL.md index 56ad6f0..4158480 100644 --- a/bottom-up-analyst/SKILL.md +++ b/bottom-up-analyst/SKILL.md @@ -44,31 +44,25 @@ without inventing anything. Every conclusion in the memo must trace to something you actually verified in a document or computed yourself. This is not a style note - it is the whole point. A confident memo built on an unchecked assumption is worse than no memo, because it *launders a guess into a -recommendation*. The discipline that prevents this is borrowed from the `pitch-like-lou` -corpus, and it is a **necessary condition on every memo regardless of company type**: - -- **Separate what you *know* from what you *believe*.** State which claims are verified - (with the source) and which are estimates or assumptions. Mark them differently in the - memo so a reader can audit your confidence. -- **Concede the weak points out loud.** The bear case is part of *your* job, not the - reader's. A thesis you have not tried to kill is not yet a thesis. -- **Tag second-hand claims as second-hand.** The cautionary tale from the corpus: a - brilliant structural thesis (MCI QUIPS) nearly blew up because its author relayed - *third-hand* that the books were clean; ~$24B of intercompany claims surfaced later. Know - which claims you checked yourself, and flag the ones you didn't. -- **Demand a margin of safety.** Price the bad parts in - bad governance, dilution, cyclical - risk - and require that the thesis survives anyway. - -Lou's discipline is *necessary but not sufficient.* It is the quality gate every memo passes -through. It does **not** dictate the analysis - this skill researches companies Lou never -touched (hypergrowth tech, regulatory-tailwind inflections, turnarounds). The *method* below -supplies the sufficiency; Lou's temperament supplies the honesty. +recommendation*. + +The quality gate that prevents this is **Lou's honesty gate** - separate what you *know* +from what you *believe*, concede the weak points out loud, tag second-hand claims as +second-hand, and demand a margin of safety that survives the bad parts (governance, +dilution, cyclical risk). It is a **necessary condition on every memo regardless of company +type**. The gate lives in one place - `pitch-like-lou`, "the one inviolable rule" (with the +MCI QUIPS cautionary tale of a thesis nearly sunk by an unverified third-hand claim). Read +it there; apply it to every memo here. + +Lou's gate is *necessary but not sufficient.* It does **not** dictate the analysis - this +skill researches companies Lou never touched (hypergrowth tech, regulatory-tailwind +inflections, turnarounds). The *method* below supplies the sufficiency; Lou's temperament +supplies the honesty. ## The loop Work through these phases in order, but let the **archetype** decide where the weight goes - a hypergrowth name lives in phases 3 and 6; a cyclical in 4; a special-situation in 5 and 7. -Do not pad a phase just because it exists. 1. **Orient and scope - filings first, always, before any web search.** Run `sec-edgar-skill`'s `scripts/orient.py` as the **very first tool call** - before web @@ -78,16 +72,9 @@ Do not pad a phase just because it exists. the same information is slower, less authoritative, and often wrong about the company. **Breaking-news pattern:** if the user mentions a same-day event, orient.py will show the - 8-K filed today. Immediately follow with (`sec-edgar-skill` scripts): - - ```bash - python scripts/fetch_filing.py --ticker --form 8-K --date - python scripts/fetch_filing.py --ticker --form 8-K --date --attachment list - # then fetch Exhibit 99.1 (the press release): - python scripts/fetch_filing.py --ticker --form 8-K --date --attachment "ex-99.1" - ``` - - The press-release exhibit is the primary source; do not web-search for what it contains. + 8-K filed today. Pull it and its press-release exhibit (Exhibit 99.1) via `sec-edgar-skill`, + which documents the exact breaking-news fetch sequence. That exhibit is the primary + source; read it rather than web-searching for what it contains. After orient, read the latest **annual report** (10-K, or 20-F for an FPI) - its business section and MD&A - and skim the most recent **interim/current** reports (10-Q/8-K, or 6-K @@ -96,17 +83,10 @@ Do not pad a phase just because it exists. cap, **the peer set**, sector) from `market-scout` to frame size and comps - orientation, not evidence. - **Pull the latest earnings call transcript.** After the filing read and market snapshot, - fetch the most recent earnings call transcript. This is a `market-scout` script (resolve - the path against the `market-scout` skill directory, not this one): - - ```bash - python scripts/fetch_transcripts.py --ticker --latest 1 - ``` - - Then read it (or grep it). The transcript is a **primary source** — management's own - words on guidance, strategy, and tone. The Q&A section is especially valuable: analyst - questions often target exactly the weak points you need to stress-test in phase 6. + **Pull the latest earnings call transcript** via `market-scout`, then read or grep it. + The transcript is a **primary source** — management's own words on guidance, strategy, + and tone. The Q&A section is especially valuable: analyst questions often target exactly + the weak points you need to stress-test in phase 6. 2. **Classify the archetype.** Almost every company is dominated by one shape, and the shape decides which DD emphases, metrics, disqualifiers, and valuation method carry the @@ -137,14 +117,9 @@ Do not pad a phase just because it exists. (their 8-Ks, 10-Qs, 10-Ks) for management commentary, pricing, and sentiment you can cite. **Peers' earnings call transcripts** are equally valuable primary sources - a competitor's CEO discussing pricing pressure, capacity additions, or market-share wins - on their own call is citable competitive intelligence (`market-scout` script): - - ```bash - python scripts/fetch_transcripts.py --ticker --latest 1 - ``` - - Then grep the cached transcript for the subject company's name, the product category, - or pricing language. Use **web research only for what filings and transcripts genuinely + on their own call is citable competitive intelligence - pull peer transcripts via + `market-scout` and grep the cached file for the subject company's name, the product + category, or pricing language. Use **web research only for what filings and transcripts genuinely cannot give you** - relative positioning, market-share dynamics, channel/customer checks - and label every web claim as such. See `references/guide_competitive.md`. @@ -168,85 +143,18 @@ Do not pad a phase just because it exists. 6. **Try to kill it - pre-mortem.** Assume it's a year later and the thesis failed; write down why. Run the **archetype's disqualifiers** (each playbook lists them) *and* Lou's - gate (above). Most candidates should die here or get marked down - that is the system - working, not failing. Re-tag every surviving claim as verified vs. assumed. - - **Check the institutional ownership picture.** Before finalising the risk assessment, - pull the 13F holder data. This is a `sec-edgar-skill` script (resolve the path against - the `sec-edgar-skill` skill directory): - - ```bash - python scripts/fetch_13f_holders.py --ticker --top 15 - python scripts/fetch_13f_holders.py --ticker --history - ``` - - The output reports **share counts**, not dollar values (13F values are stale - quarter-end prices). To convert to ownership percentages, divide by total shares - outstanding from the `market-scout` snapshot or the latest 10-Q. - - This reveals who is positioned and how ownership has shifted - signals that feed - directly into the risk and catalyst assessment: - - **Concentration risk:** if 3-5 holders own >30% of the float, a single redemption - cycle can crater the stock independent of fundamentals. - - **Smart-money conviction:** are high-conviction value managers (Royce, Needham, - Baupost) building or trimming? A rising share count from a known deep-diver is a - confirming signal; a quiet exit is a warning. - - **Activist presence:** a 13D/13G filer showing up in the holder list may signal an - upcoming catalyst (board fight, strategic review, buyback demand). - - **Passive vs. active mix:** a stock dominated by index funds (Vanguard, BlackRock, - State Street) has different liquidity and governance dynamics than one held by - concentrated active managers. - - **Ownership trend vs. price:** rising institutional ownership into a falling price - suggests accumulation; the reverse suggests distribution. Cross-reference with the - `--history` output. - - **Check insider ownership and recent activity.** Insider transactions are a direct, - auditable signal of whether the people running the business are aligned with outside - shareholders — or quietly heading for the exits. A management team buying stock with - their own money while the price is depressed is one of the strongest confirming signals - in fundamental analysis; a management team selling into your thesis is a warning you - cannot ignore. Pull the insider data. This is a `sec-edgar-skill` script (resolve the - path against the `sec-edgar-skill` skill directory): - - ```bash - python scripts/fetch_insider_trades.py --ticker - python scripts/fetch_insider_trades.py --ticker --start <12mo-ago> --end - python scripts/fetch_insider_trades.py --ticker --buys-only - ``` - - The output reports recent Form 4 transactions — open-market purchases (code P), sales - (code S), option exercises (code M), and tax withholdings (code F) — with share counts, - prices, and each insider's remaining holdings. - - Read the insider picture for what it tells you about adverse selection risk and - alignment: - - **Open-market purchases by officers/directors** are the strongest signal — these are - voluntary, with the insider's own capital, and filed publicly. A CEO or CFO buying - $500K+ of stock at current prices is putting their money where their mouth is. - Multiple insiders buying in the same window (a "cluster buy") is even stronger. - - **Selling context matters.** Not all insider sales are bearish — 10b5-1 plans, - diversification, and tax-driven exercises are routine. But *discretionary* sales by - senior officers outside a pre-announced plan, especially into strength or ahead of a - known risk, are a red flag. Look at the pattern: is the CEO selling every quarter - like clockwork (plan), or did three executives dump shares the week after an earnings - beat (discretionary)? - - **Ownership level vs. compensation.** Cross-reference insider holdings (the - "Remaining Shares" column) against the proxy's compensation tables. An executive - whose stock holdings are 10x+ their annual salary has real skin in the game; one - whose holdings are a rounding error relative to their cash comp does not. - - **Buy/sell ratio and trend.** The summary table shows the aggregate buy/sell ratio. - A ratio well above 1x (net buying) over the past 6-12 months is confirming; a ratio - well below 1x (net selling) into a thesis you're building long is a direct adverse- - selection warning — the people with the best information are reducing exposure. - - **Insider activity at inflection points.** The most informative insider trades happen - around events — after a selloff, before a catalyst, during a turnaround. An insider - buying after a 40% drawdown is telling you they think the market overreacted. An - insider selling ahead of a product launch they've been hyping is telling you - something else entirely. - - **Foreign private issuers (FPIs):** FPIs are exempt from Section 16 and do not file - Forms 3/4/5 on EDGAR. Insider transaction data will not be available; note this gap - in the memo and check the home-jurisdiction regulator if the thesis depends on - insider alignment (e.g. SEDAR+ for Canadian filers). + honesty gate (above). Most candidates should die here or get marked down - that is the + system working, not failing. Re-tag every surviving claim as verified vs. assumed. + + Before finalising the risk assessment, read the **ownership signal**: pull institutional + (13F) and insider (Form 4) data via `sec-edgar-skill`, then interpret it against the + thesis. This is where adverse selection surfaces - a concentrated holder base that can + crater the float, smart money accumulating or quietly exiting, insiders buying with their + own capital or selling into your long. Account for every cluster buy and every + discretionary senior-officer sale; a signal you skip is a risk you took blind. See + `references/guide_ownership_signals.md` for how to read each pattern (13F reports stale + quarter-end prices, so use the **share counts** and divide by shares outstanding from the + `market-scout` snapshot for ownership %). 7. **Reach a verdict at the conviction the work supports.** State the call - **Long / Short / Pass / Watch** - with an honest conviction level, the **variant perception** @@ -288,12 +196,10 @@ You are the one deciding what the hands fetch. Be deliberate and frugal: - **Transcripts are greppable too.** Once cached, grep a transcript for "guidance", "margin", a competitor's name, or a specific metric - you don't need to read the whole 45-minute call to find the passage that matters. -- **Ownership data is cached like everything else.** `fetch_13f_holders.py` writes to - `sec-cache/{TICKER}/13f-holders_{YEAR}-Q{Q}.md` (or `13f-history_{TICKER}.md` for - `--history`). `fetch_insider_trades.py` writes to - `sec-cache/{TICKER}/insider-trades_{START}_{END}.md`. The quarter or date range in the - filename makes the scope explicit. Glob the cache before re-fetching — if the window - you need is already on disk, grep and read it rather than re-hitting the source. +- **Ownership data is cached like everything else.** `sec-edgar-skill` writes 13F and + insider output to the same `sec-cache/{TICKER}/` tree under scope-keyed filenames. Glob + the cache before re-fetching — if the window you need is already on disk, grep and read + it rather than re-hitting the source. - **Spend tokens where the archetype says the value hides.** Don't fetch a proxy's compensation tables for a hypergrowth TAM question, or a deferred-revenue footnote for a liquidation. Let the playbook route you. @@ -357,16 +263,17 @@ use three-stage vs two-stage, and how to set the discount rate and terminal valu | `references/guide_normalization.md` | Phase 3 - un-distorting the financials into owner earnings. | | `references/guide_competitive.md` | Phase 4 - SEC-first competitive work; when to go to the web. | | `references/guide_valuation.md` | Phase 5 - triangulation, reverse-DCF, discount/terminal discipline. | +| `references/guide_ownership_signals.md` | Phase 6 - reading the 13F and insider ownership signal. | | `references/archetypes/*.md` | Phase 2 - load the one matching the company's shape. | | `scripts/dcf.py`, `scripts/epv.py` | Phase 5 - the valuation arithmetic. `--help` for flags. | -## The two questions every memo must pass +## Definition of done: pitch-ready -Before you ship, ask the two questions the best write-ups always pass: +The memo ships when it passes **Lou's honesty gate** end to end - concretely: -1. *Is every claim here something I actually verified in a document or computed myself - - and is everything I didn't verify marked as such?* -2. *Have I been as honest and specific about what's wrong with this as I am about what's - right?* +1. every claim is verified in a document or computed yourself, and everything unverified is + marked as such; and +2. you have been as honest and specific about what is wrong with the thesis as about what + is right. -If yes to both, the memo is pitch-ready. +Both true - the memo is pitch-ready. diff --git a/bottom-up-analyst/references/archetypes/special_situation.md b/bottom-up-analyst/references/archetypes/special_situation.md index a94294a..d93318b 100644 --- a/bottom-up-analyst/references/archetypes/special_situation.md +++ b/bottom-up-analyst/references/archetypes/special_situation.md @@ -47,8 +47,7 @@ sum-of-the-parts value, the formula output you computed yourself. ## Normalize / adjust - **Compute the formula yourself** from the document — do not trust a summary or a third-hand - characterization (the MCI lesson: ~$24B of intercompany claims surfaced *after* a "books are - clean" was relayed second-hand). + characterization (`pitch-like-lou`'s inviolable rule, the MCI lesson). - Rebuild the **pro-forma** capital structure as it exists *after* the event. - For foreign issuers, reconcile foreign-GAAP/IFRS to a comparable basis before valuing. diff --git a/bottom-up-analyst/references/guide_ownership_signals.md b/bottom-up-analyst/references/guide_ownership_signals.md new file mode 100644 index 0000000..39895b1 --- /dev/null +++ b/bottom-up-analyst/references/guide_ownership_signals.md @@ -0,0 +1,58 @@ +# Reading the ownership signal — 13F and insider data + +Phase 6 support. Pull the data via `sec-edgar-skill` (institutional 13F holders and Form 4 +insider transactions), then read it against the thesis. This guide is *how to interpret* +each pattern; the fetch mechanics and flags live in `sec-edgar-skill` (`--help` is +authoritative). + +13F output reports **share counts**, not dollar values (13F values are stale quarter-end +prices). Convert to ownership percentages by dividing by shares outstanding from the +`market-scout` snapshot or the latest 10-Q. + +## Institutional ownership (13F) + +Who is positioned and how the holder base has shifted — signals that feed the risk and +catalyst assessment: + +- **Concentration risk:** if 3–5 holders own >30% of the float, a single redemption cycle + can crater the stock independent of fundamentals. +- **Smart-money conviction:** are high-conviction value managers (Royce, Needham, Baupost) + building or trimming? A rising share count from a known deep-diver is a confirming signal; + a quiet exit is a warning. +- **Activist presence:** a 13D/13G filer in the holder list may signal an upcoming catalyst + (board fight, strategic review, buyback demand). +- **Passive vs. active mix:** a stock dominated by index funds (Vanguard, BlackRock, State + Street) has different liquidity and governance dynamics than one held by concentrated + active managers. +- **Ownership trend vs. price:** rising institutional ownership into a falling price + suggests accumulation; the reverse suggests distribution. Cross-reference with the holder + history. + +## Insider activity (Form 4) + +Insider transactions are a direct, auditable read on whether the people running the business +are aligned with outside shareholders — or quietly heading for the exits. Read them for +adverse-selection risk: + +- **Open-market purchases by officers/directors** are the strongest signal — voluntary, with + the insider's own capital, filed publicly. A CEO or CFO buying $500K+ at current prices is + putting money where their mouth is; multiple insiders buying in the same window (a "cluster + buy") is stronger still. +- **Selling context matters.** Discretionary sales by senior officers outside a pre-announced + 10b5-1 plan — especially into strength or ahead of a known risk — are a red flag; routine + 10b5-1, diversification, and tax-driven exercises are not. Read the pattern: clockwork + quarterly selling is a plan; three executives dumping the week after an earnings beat is + discretionary. +- **Ownership level vs. compensation.** Cross-reference insider holdings (the "Remaining + Shares" column) against the proxy's compensation tables. Holdings 10x+ annual salary is + real skin in the game; holdings that round to zero against cash comp are not. +- **Buy/sell ratio and trend.** A ratio well above 1x (net buying) over the past 6–12 months + is confirming; well below 1x (net selling) into a long you are building is a direct + adverse-selection warning — the best-informed people are reducing exposure. +- **Activity at inflection points.** The most informative trades cluster around events. An + insider buying after a 40% drawdown thinks the market overreacted; an insider selling ahead + of a product launch they have been hyping is telling you the opposite. +- **Foreign private issuers (FPIs):** FPIs are exempt from Section 16 and do not file Forms + 3/4/5 on EDGAR. Insider data will be unavailable — note the gap in the memo, and check the + home-jurisdiction regulator (e.g. SEDAR+ for Canadian filers) if the thesis depends on + insider alignment. diff --git a/bottom-up-analyst/references/memo_template.md b/bottom-up-analyst/references/memo_template.md index ae4cf24..aecee28 100644 --- a/bottom-up-analyst/references/memo_template.md +++ b/bottom-up-analyst/references/memo_template.md @@ -7,7 +7,7 @@ stand on it without inventing anything. A memo is an argument, not a form. Use this structure as a skeleton, but let the **archetype** decide where the weight goes — a compounder earns its keep in the economics and moat sections; a special-situation in the structural fact and the payoff; a hypergrowth -name in the reverse-DCF and unit economics. Do not pad a section to fill it. A tight +name in the reverse-DCF and unit economics. Weight each section to the archetype; a tight six-page memo beats a padded twenty. ## The honesty markup (use it throughout) @@ -94,53 +94,29 @@ archetype, including a **reverse-DCF of what today's price implies**. Lay out **bear / base / bull** scenarios with their key assumptions, converge on an **intrinsic-value range**, and state the **margin of safety** at the current price. -This section **must** include a subsection titled **"Discount Rate Derivation"** (or -similar) that shows the reasoning behind the discount rate used in the DCF and EPV. The -subsection should show: the peer set used for beta benchmarking, their levered and -unlevered betas, the re-levered beta for the subject company's capital structure, the -resulting CAPM cost of equity, the WACC, and a sanity check against the business -description (see `guide_valuation.md` § "Discount rate" for the full methodology). A -discount rate without a derivation is an unauditable assumption — the reader cannot -disagree with it, which means they cannot trust it. +This section **must** include a **"Discount Rate Derivation"** subsection showing how the +rate was reasoned - peer betas, the re-levered beta, the CAPM cost of equity, the WACC, and +the sanity check against the business type (methodology in `guide_valuation.md` § "Discount +rate"). A rate without a derivation is unauditable - the reader cannot disagree with it, so +cannot trust it. ### 7. Ownership — institutional holders and insider activity -Who owns this stock — from the outside and from the inside — and what does the -ownership picture tell you about alignment, adverse selection, and risk? - -**Institutional holders.** Pull from `sec-edgar-skill`'s -`scripts/fetch_13f_holders.py`. Include: - -- **Top holders** (top 10–15 by shares) and whether they are passive index funds or - active/concentrated managers. -- **Ownership trend** — is institutional ownership rising or falling? Cross-reference - with price to distinguish accumulation from distribution. -- **Notable holders** — any known deep-value, activist, or sector-specialist funds? - Their presence (or absence/exit) is a signal. -- **Concentration risk** — if a handful of holders dominate the float, flag the - liquidity and forced-selling risk. - -**Insider ownership and activity.** Pull from `sec-edgar-skill`'s -`scripts/fetch_insider_trades.py`. Include: - -- **Recent insider transactions** — a table of open-market purchases and sales over - the past 6–12 months. Distinguish voluntary open-market trades (code P/S) from - routine option exercises (M) and tax withholdings (F). -- **Buy/sell ratio** — are insiders net buyers or net sellers? A strong buy/sell ratio - is a confirming signal; net selling into your long thesis is an adverse-selection - warning. -- **Key buyers/sellers** — name the individuals and their roles. A CEO buying $1M of - stock carries more weight than a director buying $20K. -- **Ownership level** — how much do insiders own in aggregate? Cross-reference - remaining holdings against compensation (from the proxy) to gauge skin in the game. -- **FPI note** — if the company is a foreign private issuer exempt from Section 16, - state that Form 4 data is unavailable and note any home-jurisdiction disclosures - found (or the gap, if none). - -This section is short (a table or two + a paragraph of interpretation per sub-topic), -but it grounds the catalyst and risk sections that follow. The insider picture in -particular is a direct check on adverse selection — if the people with the best -information are not aligned with your thesis, that fact belongs in the risk section. +Who owns this stock, inside and out, and what the picture says about alignment and adverse +selection. Pull 13F and Form 4 data via `sec-edgar-skill`, then read each pattern against +`guide_ownership_signals.md`. Include: + +- **Institutional (13F):** top 10–15 holders (passive index vs. active/concentrated), the + ownership trend vs. price (accumulation or distribution), any notable + deep-value/activist/specialist holders, and concentration/forced-selling risk. +- **Insider (Form 4):** a table of open-market buys/sells over the past 6–12 months + (distinguish voluntary P/S from routine M/F), the net buy/sell ratio, the key + buyers/sellers by name and role, aggregate insider ownership vs. compensation, and the FPI + Section-16 gap where it applies. + +Keep it to a table or two plus a paragraph of interpretation; it grounds the catalyst and +risk sections. If the best-informed people are not aligned with your thesis, that fact +belongs in the risk section. ### 8. Risks & pre-mortem diff --git a/context/CONVENTIONS.md b/context/CONVENTIONS.md index 78b9a29..a29cdf3 100644 --- a/context/CONVENTIONS.md +++ b/context/CONVENTIONS.md @@ -32,6 +32,7 @@ Terse imperative code rules. No rationale here — rationale lives in - Keep each `SKILL.md` terse; defer detail to `references/` (progressive disclosure). - 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`. ## Git diff --git a/context/DECISIONS.md b/context/DECISIONS.md index c57ff83..cb3e92f 100644 --- a/context/DECISIONS.md +++ b/context/DECISIONS.md @@ -1,5 +1,7 @@ # DECISIONS.md +This is a curated ADR file for durable, non-obvious project-level choices. It is not a changelog or implementation worklog. + Append-only log of intentional tradeoffs. Newest entries on top. Read before changing or re-litigating a choice. diff --git a/pitch-like-lou/SKILL.md b/pitch-like-lou/SKILL.md index 20db8bd..17b4ec1 100644 --- a/pitch-like-lou/SKILL.md +++ b/pitch-like-lou/SKILL.md @@ -102,7 +102,7 @@ Each move below earns its place; the parenthetical is *why* it works. Short quot Use the skeleton, but let the *situation* decide where the weight goes. A cigar-butt leans on questions 1 and 4; a compounder on 2 and 3; an arbitrage on 1 and 4 with the structural fact as -the spine. Do not pad a section just because it exists. +the spine. Weight each section to the situation. ### 1. Stat header diff --git a/signal-sweep/SKILL.md b/signal-sweep/SKILL.md index 4c7188f..c818136 100644 --- a/signal-sweep/SKILL.md +++ b/signal-sweep/SKILL.md @@ -2,15 +2,14 @@ name: signal-sweep description: >- Surface new investment ideas for a long-only investor by scanning SEC filings and market - data across the $50M–$10B US-listed universe. Use this skill whenever the user wants to - discover new tickers — not research a specific one they already have. Triggers include - "what should I look at", "show me insider buying", "any cluster buys", "what's near its - 52-week low", "run the screens", "who's exposed to [theme]", "which companies mention - [keyword] in filings", "who's presenting at conferences this week", "find me new ideas", - "surface some names", "what's interesting in small caps", or any request to scan, screen, - or sweep for investment candidates. Do NOT use this for single-company deep dives (that's - bottom-up-analyst), individual stock quotes (market-scout), or pulling a specific filing - (sec-edgar-skill). This skill produces tickers; the rest of the stack researches them. + data across the $50M–$10B US-listed universe. Use this skill to discover tickers you do not + yet have, via four scans: insider buying (cluster/dip/rip buys from Form 4), market screens + (near-52-week-low, high-short-interest, forgotten, and other presets), keyword/theme + exposure across filing full-text, and conference presenters. Triggers include "find me new + ideas", "show me insider buying", "run the screens", "who's exposed to [theme]", and "who's + presenting this week". This skill *produces* tickers for the rest of the stack to research: + reach for bottom-up-analyst to deep-dive a name you already have, market-scout for a quote, + sec-edgar-skill for a specific filing. --- # Signal Sweep diff --git a/signal-sweep/docs/flip_buy_difficulty_analysis.md b/signal-sweep/docs/flip_buy_difficulty_analysis.md index 32cafec..75f0dff 100644 --- a/signal-sweep/docs/flip_buy_difficulty_analysis.md +++ b/signal-sweep/docs/flip_buy_difficulty_analysis.md @@ -1,5 +1,11 @@ # Technical Analysis: Implementing a Flip-Buy Insider Filter +> **Not a skill instruction — do not act on this file.** This is a human-facing *design +> proposal* for an unbuilt feature, kept in `docs/` for developers. It is deliberately not +> referenced from `SKILL.md` or any script. An agent running `signal-sweep` must ignore it: +> the flip-buy filter and the draft code below **do not exist** in the skill. Use only the +> capabilities documented in `SKILL.md`. + This document provides a comprehensive feasibility and difficulty analysis for implementing a **Flip-Buy** filter within the `signal-sweep` workspace. A flip-buy is defined as an open-market purchase (code `P`) by an corporate insider who has a history of recent open-market sales (code `S`). ---