Audit: prune cross-skill duplication and bottom-up sprawl

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

README.md

@@ -44,34 +44,60 @@ own; together they form a pipeline.
 
 **Production order:** signal-sweep → analyst → memo → (optionally) Lou pitches from it.
 
-### Progressive discovery at the center of design - lets your model's intelligence shine through
+### Progressive disclosure at the center of design - lets your model's intelligence shine through
 
-#### v0.1.0
+#### Current snapshot
+
+From the repository root, reproduce these reports with:
+
+```bash
+# Agent-loaded entry points
+cloc --by-file --include-lang=Markdown bottom-up-analyst/SKILL.md pitch-like-lou/SKILL.md sec-edgar-skill/SKILL.md signal-sweep/SKILL.md market-scout/SKILL.md
+
+# Referenced skill surface only
+cloc \
+  bottom-up-analyst/SKILL.md \
+  bottom-up-analyst/references/memo_template.md \
+  bottom-up-analyst/references/guide_normalization.md \
+  bottom-up-analyst/references/guide_competitive.md \
+  bottom-up-analyst/references/guide_valuation.md \
+  bottom-up-analyst/references/guide_ownership_signals.md \
+  bottom-up-analyst/references/archetypes/*.md \
+  bottom-up-analyst/scripts/dcf.py bottom-up-analyst/scripts/epv.py \
+  market-scout/SKILL.md market-scout/requirements.txt market-scout/scripts/fetch_market_data.py market-scout/scripts/fetch_transcripts.py \
+  pitch-like-lou/SKILL.md pitch-like-lou/references/corpus/*.md \
+  sec-edgar-skill/SKILL.md \
+  sec-edgar-skill/references/guide_core.md sec-edgar-skill/references/guide_filings.md sec-edgar-skill/references/guide_financials.md sec-edgar-skill/references/guide_ownership.md sec-edgar-skill/references/guide_holdings.md \
+  sec-edgar-skill/scripts/orient.py sec-edgar-skill/scripts/fetch_filing.py sec-edgar-skill/scripts/fetch_filings.py sec-edgar-skill/scripts/parse_financials.py sec-edgar-skill/scripts/list_headings.py sec-edgar-skill/scripts/fetch_insider_trades.py sec-edgar-skill/scripts/fetch_13f_holders.py sec-edgar-skill/scripts/test_setup.py \
+  signal-sweep/SKILL.md signal-sweep/screens.json signal-sweep/references/guide_screens.md \
+  signal-sweep/scripts/scan_insiders.py signal-sweep/scripts/scan_market.py signal-sweep/scripts/search_themes.py signal-sweep/scripts/scan_conferences.py
+```
+
+The second command lists the referenced skill paths explicitly, so repository-level docs and
+unreferenced proposals are not counted.
 
 ```text
 ------------------------------------------------------------------------------------------
 File                                        blank        comment           code
 ------------------------------------------------------------------------------------------
-./bottom-up-analyst/SKILL.md                   64              0            308
+./bottom-up-analyst/SKILL.md                   51              0            228
 ./pitch-like-lou/SKILL.md                      39              0            164
 ./sec-edgar-skill/SKILL.md                     36              0            135
-./signal-sweep/SKILL.md                        27              0             82
+./signal-sweep/SKILL.md                        27              0             81
 ./market-scout/SKILL.md                        19              0             60
 ------------------------------------------------------------------------------------------
-SUM:                                          185              0            749
+SUM:                                          172              0            668
 ------------------------------------------------------------------------------------------
 
 -------------------------------------------------------------------------------
 Language                     files          blank        comment           code
 -------------------------------------------------------------------------------
-Markdown                        34           1704              0           3370
-Python                          19            746            627           2919
-JSON                             2              0              0            109
-YAML                             2             15              2             75
-TOML                             1              5              2             30
-Text                             3              3              0             17
+Markdown                        29           1608              0           3025
+Python                          16            711            534           2890
+JSON                             1              0              0             99
+Text                             1              1              0              5
 -------------------------------------------------------------------------------
-SUM:                            61           2473            631           6520
+SUM:                            47           2320            534           6019
 -------------------------------------------------------------------------------
 ```
 

bottom-up-analyst/README.md

@@ -36,7 +36,7 @@ the data skills decide nothing and Lou assumes the work is already done. See the
 - `SKILL.md` — the skill itself (the entry point an agent loads): the loop, archetype routing,
   how it drives the tools, and the valuation tooling.
 - `references/` — lazily-loaded guides: the memo template, normalization, competitive analysis,
-  valuation, and one playbook per archetype (`references/archetypes/`).
+  valuation, ownership signals, and one playbook per archetype (`references/archetypes/`).
 - `scripts/` — thin, self-documenting valuation tools:
   - `dcf.py` — two-stage DCF, **forward** (assumptions → intrinsic value) and **reverse**
     (price → implied growth), with a bear/base/bull sensitivity table.