eggmasonvalue · eggmasonvalue · Aug 31, 2026 · Aug 31, 2026
diff --git a/context/CONVENTIONS.md b/context/CONVENTIONS.md
@@ -10,6 +10,8 @@ Terse imperative code rules. No rationale here — rationale lives in
 - Check formatting: `uv run ruff format --check .`
 - Lint Markdown: `npx markdownlint-cli2 "**/*.md"`
 - Sync project dependencies: `uv sync`
+- Do not add automated test suites, fixtures, or eval workspaces; validate with lint and focused
+  smoke commands.
 
 ## Python
 

diff --git a/context/DECISIONS.md b/context/DECISIONS.md
@@ -17,6 +17,21 @@ Status: active | superseded by <date/title>
 
 ---
 
+## 2026-08-31 — Distill routine 13F queries while preserving SEC-level provenance
+
+Context: SEC 13F filings are authoritative but awkward for reverse stock-holder lookup and
+routine manager history, while 13f.info already resolves managers, CUSIPs, filing portfolios,
+and position histories. Exposing provider URLs or low-level CUSIP flags would invite agents to
+leave the tool surface and repeat work.
+Decision: Use 13f.info behind the SEC skill's routine stock-, manager-, and manager-position
+queries. Keep the agent-facing interface job-based, abstract the intermediary from generated
+reports, and expose the underlying SEC period, CIK, and accession. Use raw EDGAR for fields the
+distilled route omits, provider failure, discrepancies, or requested verification.
+Tradeoff: Routine queries depend on an unofficial distilled backend and its HTML/JSON shape, but
+agents get a smaller, more capable interface while retaining a direct path to the regulatory
+record.
+Status: active
+
 ## 2026-08-12 — Replace Pi's coding identity without duplicating tool or skill guidance
 
 Context: A profile-level `SYSTEM.md` replaces Pi's default prompt, which removes the

diff --git a/context/MAP.md b/context/MAP.md
@@ -51,7 +51,8 @@ sessions, and unrelated settings remain profile-local and untouched.
   `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`; guides in `references/`; shared bootstrap in `scripts/_common.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
   `scripts/_common.py`.
 - `skills/bottom-up-analyst/` — valuation `scripts/dcf.py`, `epv.py`; archetypes and guides in
@@ -71,8 +72,10 @@ flowchart TD
 - `bottom-up-analyst` is the brain and conductor: it decides what to pull, reasons over it,
   and writes the memo. The data skills never decide what matters.
 - The two filing/market data skills know nothing of each other and are swappable.
-- `signal-sweep` and `sec-edgar-skill` both read `EDGAR_IDENTITY` and share on-disk cache
-  contracts defined in their `_common.py` modules.
+- `signal-sweep` and SEC-facing `sec-edgar-skill` 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
 

diff --git a/skills/README.md b/skills/README.md
@@ -92,6 +92,7 @@ cloc \
   skills/sec-edgar-skill/references/guide_filings.md \
   skills/sec-edgar-skill/references/guide_financials.md \
   skills/sec-edgar-skill/references/guide_ownership.md \
+  skills/sec-edgar-skill/references/guide_proxy.md \
   skills/sec-edgar-skill/references/guide_holdings.md \
   skills/sec-edgar-skill/scripts/orient.py \
   skills/sec-edgar-skill/scripts/fetch_filing.py \

diff --git a/skills/sec-edgar-skill/README.md b/skills/sec-edgar-skill/README.md
@@ -1,65 +1,70 @@
 # SEC EDGAR Research Skill
 
-A tools skill that teaches an AI coding agent how to retrieve and extract data from
-**SEC EDGAR** filings for US-listed companies (domestic issuers and foreign private
-issuers), efficiently and within a token budget.
-
-It is the **data/tools layer** of a research stack: it fetches and extracts; it does not
-decide what matters. Pair it with an analytical-framework skill (which supplies the
-judgment and the output shape) and, optionally, a presentation/consumer skill. Keeping
-this layer unopinionated lets any framework compose on top of it.
-
-## What's included
-
-- **`SKILL.md`** — the entry point: setup, the token-efficient retrieval method, the
-  cache contract, and routing to the guides and scripts.
-- **`references/`** — modular, lazily-loaded guides, one per data domain:
-  - `guide_core.md` — company lookup, filing discovery, `.to_context()`, `.docs`.
-  - `guide_filings.md` — filing text by SEC item code (10-K/10-Q/8-K/20-F) or heading discovery (DEF 14A/6-K); attachments (6-K Exhibit 99.1).
-  - `guide_financials.md` — XBRL statements and facts (US-GAAP & IFRS).
-  - `guide_ownership.md` — insider transactions (3/4/5) and executive compensation (DEF 14A; 20-F Item 6).
-  - `guide_holdings.md` — 13F institutional holdings and 13D/13G blockholders.
-- **`scripts/`** — thin, self-documenting wrappers around `edgartools` (shared setup
-  lives in `_common.py`):
-  - `orient.py` — company summary + filing-mix survey + recent filings (run first).
-  - `fetch_filing.py`, `fetch_filings.py` — filings (and sections/attachments) to Markdown.
-  - `parse_financials.py` — XBRL statements to CSV.
-  - `list_headings.py` — heading→line map for a cached filing.
-  - `fetch_insider_trades.py` — insider transactions (Form 4 buys/sells).
-  - `fetch_13f_holders.py` — institutional 13F holders (via 13f.info).
-  - `test_setup.py` — environment diagnostics.
-
-## Setup
-
-1. **Install this skill's dependencies** from this directory: `uv sync`
-2. **Set `EDGAR_IDENTITY`** — see [profile setup](../../README.md#one-time-runtime-setup).
-3. **Verify:** `python scripts/test_setup.py --live`
-
-## Add the skill to your agent
+An agent skill for retrieving, verifying, and inspecting SEC filings and filing-derived
+financial, ownership, compensation, and governance data without loading whole filings into
+context.
+
+## Included resources
+
+- `SKILL.md` — agent workflow, source hierarchy, cache contract, and resource routing.
+- `references/guide_core.md` — company and filing discovery.
+- `references/guide_filings.md` — sections, free-form filings, and exhibits.
+- `references/guide_financials.md` — XBRL statements, facts, and reporting periods.
+- `references/guide_ownership.md` — Forms 3/4/5 and insider transactions.
+- `references/guide_proxy.md` — beneficial ownership, governance, compensation, and voting.
+- `references/guide_holdings.md` — 13F and 13D/13G holdings.
+- `scripts/` — command-line retrieval and extraction helpers.
+
+## Install this skill
+
+From the SecStack repository:
+
+```bash
+npx skills add eggmasonvalue/secstack --skill sec-edgar-skill
+```
+
+SecStack's profile bootstrap installs the Python dependencies automatically. For a standalone
+installation, run from this directory:
+
+```bash
+uv sync
+```
+
+Then invoke the scripts with that environment, or configure the harness to use its Python.
+
+## SEC identity
+
+SEC requests require a real contact identity under the SEC fair-access policy:
 
 ```bash
-npx skills add eggmasonvalue/sec-edgar-skill
+export EDGAR_IDENTITY="Jane Analyst jane@example.com"
 ```
 
-## How it works
+Do not commit it. The 13f.info convenience queries and local-file utilities do not require an
+SEC identity. Verify the full environment with:
 
-Filings are huge, so the skill keeps them on disk and pulls only what's needed into the
-agent's context:
+```bash
+uv run python scripts/test_setup.py --live
+```
 
-1. **Orient** with `scripts/orient.py` (company summary + filing-mix survey) to decide what to fetch.
-2. **Download** filings to a local cache (`./sec-cache/{TICKER}/`) as clean Markdown.
-3. **Map** a large filing to a heading→line table of contents.
-4. **Search** the cache with native grep and read only the matching line ranges.
+## Retrieval model
 
-The cache location is configurable (`$SEC_CACHE_DIR` or `--cache-dir`) and filenames are
-deterministic (keyed by SEC accession number), so re-runs reuse cached files instead of
-re-downloading.
+1. Survey a company's filing mix when the relevant form is unknown.
+2. Select a filing by company/form/period or exact SEC accession.
+3. Save filing text as Markdown and statements as CSV.
+4. Search the local cache and read only relevant ranges.
+5. Use structured item or XBRL extraction where the filing supports it.
+
+Accession-keyed filing artifacts are reused unless `--force` is passed. Rolling ownership
+summaries refresh because their source set can change.
 
 ## Data sources
 
-Filing data comes from the public SEC EDGAR system via the open-source `edgartools`
-library. Respect the source's terms and the SEC fair-access policy — which is why a
-contact identity is required.
+Filing data comes from SEC EDGAR through the open-source `edgartools` library. Routine 13F
+holder, manager, and position-history queries are distilled through 13f.info; generated reports
+surface the underlying SEC reporting period, manager CIK, and accession rather than provider
+navigation links. Raw EDGAR remains the verification and deep-field route.
 
 ---
-Part of the [SecStack skills](../README.md) collection.
+
+Part of the [SecStack skills](https://github.com/eggmasonvalue/secstack) collection.