@v587d/capital-generation 2.7.1 → 2.7.2

package/selected-skills/peter-lynch-skill/README.md

@@ -0,0 +1,305 @@
+# Peter Lynch Skill
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE)
+[![Agent Skills](https://img.shields.io/badge/Agent%20Skills-Open%20Standard-111827?style=flat-square)](https://agentskills.io/home)
+
+An [Agent Skills](https://agentskills.io/home) open-standard skill for Peter
+Lynch-style public company research. Give it a ticker or company name, choose a
+quick screen or a deep dive, and it guides a compatible AI agent through current
+web research, source verification, and a cited markdown report.
+
+This repository is a skill package, not a web application. It has no Django
+server, database, frontend build, bundled data fetcher or project-specific API keys. The skill relies on the host
+agent's web search and page-fetch tools.
+
+## About Peter Lynch
+
+Peter Lynch ran the **Fidelity Magellan Fund** from 1977 to 1990, delivering an
+average annual return of 29.2%, beating the S&P 500 index — making it one of the
+best-performing mutual funds in history.
+
+His investment philosophy is grounded in a simple but powerful idea: ordinary
+investors have a real edge when they pay attention to the world around them.
+
+- **Invest in what you understand** — focus on businesses whose products,
+  services, and revenue model you can clearly explain.
+- **Focus on fundamentals** — prioritize earnings growth, financial health, and
+  business quality over short-term market movements or predictions.
+- **Growth at a reasonable price (GARP)** — seek companies that combine solid
+  growth with sensible valuation.
+- **Think long-term** — durable business performance matters far more than
+  short-term market noise.
+- **Use your individual advantage** — everyday observations can help you spot
+  great investments before Wall Street does.
+
+> *"The person that turns over the most rocks wins the game."* — Peter Lynch
+
+He is best known for the books: **Learn to Earn**, **One Up on Wall Street**,
+and **Beating the Street**.
+
+<br />
+
+<table align="center">
+  <tr>
+    <td align="center" width="220">
+      <img src="https://raw.githubusercontent.com/DjNero11/fundamentalio/refs/heads/main/fundamentalio/static/img/LearnToEarn.jpg" width="180" alt="Peter Lynch portrait" /><br />
+      <sub><b>Peter Lynch</b></sub><br />
+    </td>
+    <td align="center" width="160">
+      <img src="https://raw.githubusercontent.com/DjNero11/fundamentalio/refs/heads/main/fundamentalio/static/img/once_up.jpg" width="130" alt="One Up on Wall Street" /><br />
+      <sub><b>One Up on Wall Street</b></sub><br />
+    </td>
+    <td align="center" width="160">
+      <img src="https://raw.githubusercontent.com/DjNero11/fundamentalio/refs/heads/main/fundamentalio/static/img/beating_the_street.jpg" width="130" alt="Beating the Street" /><br />
+      <sub><b>Beating the Street</b></sub><br />
+    </td>
+  </tr>
+</table>
+
+<br />
+
+I created this project to see whether AI agents could generate stock research
+reports inspired by **Peter Lynch's** investing philosophy. After a few months
+of analyzing his books and iterating on the methodology/prompt engineering, it started
+producing surprisingly useful reports.
+
+## What It Does
+
+The skill supports two research workflows:
+
+| Workflow | Purpose | Evidence base | Output |
+|---|---|---|---|
+| Quick Research | Decide whether a company deserves deeper research | Reputable financial-data aggregators | Up to 450 words with a `SKIP`, `WATCHLIST`, or `DEEP RESEARCH` decision |
+| Deep Research | Produce full due diligence | Annual reports, filings, official company materials, live market data, and targeted external sources | Up to 3000 words with an attractiveness score out of 10 |
+
+Both workflows are designed around evidence discipline:
+
+- Use the smallest reliable source set that can support the conclusion.
+- Date time-sensitive market data.
+- Cite every web-derived factual claim with a linked `source:` line.
+- Do not invent missing financial data.
+- Do not expose research scratchwork in the final report unless the user asks for it.
+
+## Quick Research
+
+Quick Research is a triage workflow. It answers one practical question:
+
+> Is this company worth spending 2-5 hours researching in detail?
+
+The quick workflow intentionally avoids annual reports, full filings, SEC detail
+pages, company quarterly reports, and long investor-relations documents. It uses
+reputable aggregator pages for identity, business description, financial trends,
+cash flow, balance sheet risk, valuation, and recent trend checks.
+
+Default evidence budget:
+
+- 1-3 aggregator sources
+- 2-3 searches
+- 2-3 page fetches
+
+The report follows the quick methodology in
+[references/quick/methodology.md](references/quick/methodology.md) and ends with
+one of these decisions:
+
+- `SKIP`
+- `WATCHLIST`
+- `DEEP RESEARCH`
+
+## Deep Research
+
+Deep Research is a full due-diligence workflow. It starts with official sources
+and treats the latest annual report, 10-K, 20-F, or equivalent full-year filing
+as the factual base whenever available.
+
+The deep workflow then fills methodology gaps with targeted external sources for
+items such as live valuation, ownership, insider activity, peer context,
+industry structure, recession resilience, recent updates, and material legal or
+regulatory risks.
+
+Default evidence budget:
+
+- 7-10 sources
+- 8-12 searches
+- 10-16 page or document fetches
+
+The report follows the deep methodology in
+[references/deep/methodology.md](references/deep/methodology.md) and ends with
+an attractiveness score:
+
+```text
+Attractiveness score: X / 10
+```
+
+## How To Use
+
+Install the folder in any AI tool that supports the Agent Skills format, then
+ask for research by ticker or company name.
+
+Example prompts:
+
+```text
+Quick research MSFT
+```
+
+```text
+Do a quick screen of ASML.AS
+```
+
+```text
+Do a deep research on IBM company
+```
+
+```text
+Full analysis of Nintendo, Japan listing
+```
+
+If the request is ambiguous, the skill asks whether you want quick screening or
+deep due diligence. If only a brand, ambiguous company name, or ambiguous ticker
+is provided, the skill resolves the traded entity before analysis.
+
+Useful optional hints:
+
+- ticker
+- exchange
+- country
+- primary listing
+- company name if the ticker is ambiguous
+
+Do not provide API keys or annual report PDFs. The skill is designed to find the
+needed public sources through the host agent's browsing tools.
+
+## Installation
+
+Installation is client-specific. Agent Skills are supported by multiple AI tools
+and agentic clients; use the official
+[Client Showcase](https://agentskills.io/clients) to find instructions for your
+tool.
+
+Make sure that all .md files are included when you install the skill.
+
+## Repository Structure
+
+```text
+.
+|-- SKILL.md
+|-- references
+|   |-- disclaimer.md
+|   |-- filing-rules.md
+|   |-- quick
+|   |   |-- methodology.md
+|   |   |-- system-prompt.md
+|   |   `-- web-research.md
+|   `-- deep
+|       |-- methodology.md
+|       |-- system-prompt.md
+|       `-- web-research.md
+|-- LICENSE
+`-- README.md
+```
+
+## How The Files Work Together
+
+The skill is intentionally split into a small entrypoint and focused reference
+files. A compatible agent first sees only the metadata in [SKILL.md](SKILL.md).
+When a stock-research request matches the description, the agent reads the full
+skill instructions, chooses Quick or Deep Research, then loads only the
+workflow-specific reference files it needs.
+
+The normal flow is:
+
+1. [SKILL.md](SKILL.md) routes the request and sets the operating rules.
+2. A workflow-specific `web-research.md` file tells the agent what sources to
+   gather and when to stop.
+3. A workflow-specific `methodology.md` file defines the analytical checklist.
+4. A workflow-specific `system-prompt.md` file constrains the final report
+   format, citations, and language.
+5. [references/disclaimer.md](references/disclaimer.md) is appended after the
+   report body.
+
+## File Guide
+
+| File | What it does | Edit this when... |
+|---|---|---|
+| [SKILL.md](SKILL.md) | Main entrypoint. Defines the skill metadata, routing rules, required inputs, research checklist, citation standard, and failure handling. | You want to change when the skill triggers, how it chooses Quick vs Deep, or the top-level operating rules. |
+| [references/quick/web-research.md](references/quick/web-research.md) | Source-gathering playbook for fast screening. Sets the aggregator-only rule, search budget, extraction targets, triggered evidence checks, and internal brief template. | Quick reports gather too much, too little, or the wrong kind of evidence. |
+| [references/quick/methodology.md](references/quick/methodology.md) | Analytical framework for Quick Research. Defines understandability, diagnostic profile, fatal flaws, category checks, bonus points, and the final `SKIP` / `WATCHLIST` / `DEEP RESEARCH` decision. | You want to tune the screening philosophy or change what counts as a pass/fail signal. |
+| [references/quick/system-prompt.md](references/quick/system-prompt.md) | Output constraints for Quick Research. Controls word limit, markdown style, citation placement, plain-language rules, and cross-statement validation. | Quick reports are too verbose, too vague, poorly cited, or formatted inconsistently. |
+| [references/deep/web-research.md](references/deep/web-research.md) | Source-gathering playbook for due diligence. Defines annual-report discovery, official-source priority, external gap-fills, live market-data rules, and the deep research brief. | You think deep reports miss important source categories, over-browse, or fail to ground analysis in filings and official materials. |
+| [references/deep/methodology.md](references/deep/methodology.md) | Full due-diligence framework. Covers business model, track record, balance sheet, cash flow, growth drivers, competition, valuation, triggered modules, and final score. | You want to expand or refine the investment analysis itself. |
+| [references/deep/system-prompt.md](references/deep/system-prompt.md) | Output constraints for Deep Research. Controls report length, source priority, markdown format, citation placement, simple language, and validation rules. | You think that deep reports need a different structure, tone, citation discipline, or final-report behavior. |
+| [references/filing-rules.md](references/filing-rules.md) | Special handling for regulator data, XBRL, accounting basis, ADRs, secondary listings, and banks, insurers, REITs, and other specialized financial companies. | When you notice the skill to struggle with filing data, non-US listings, or financial companies. |
+
+## Customizing The Skill
+
+For most changes, edit the smallest file that owns the behavior:
+
+- Triggering or routing: [SKILL.md](SKILL.md)
+- Research source selection: the relevant `web-research.md`
+- Investment logic: the relevant `methodology.md`
+- Final report style: the relevant `system-prompt.md`
+- Legal language: [references/disclaimer.md](references/disclaimer.md)
+
+That separation keeps the skill easier to tune. You can make Quick Research
+stricter without touching Deep Research, or change Deep report formatting without
+changing the source-gathering rules.
+
+## Methodology
+
+The research framework is inspired by the investment principles popularized in
+Peter Lynch's books, especially the emphasis on understandable businesses,
+earnings growth, financial strength, valuation discipline, and knowing what kind
+of business you are analyzing.
+
+The skill does not force every company into a single label. Instead, it builds a
+diagnostic profile across traits such as:
+
+- cyclicality
+- turnaround status
+- growth profile
+- business maturity
+- asset angle
+- dominant analytical lenses
+
+That profile determines which checks matter most. A cyclical company, a
+turnaround, a fast grower, a stalwart-like compounder, and an asset play should
+not be judged by the same shortcut.
+
+## Citation Standard
+
+Final reports use claim-level citations. Source lines are placed directly below
+the claim they support:
+
+```md
+- Revenue grew from $10.0 billion in FY2022 to $12.0 billion in FY2024.
+  source: [Annual Report (FY2024)](https://example.com/annual-report)
+```
+
+The skill should not cite a source that is absent from the internal Source
+Ledger, and it should not include a factual claim unless it can trace that claim
+to a linked source.
+
+## Disclaimer
+
+This project is independent and is not affiliated with, endorsed by, sponsored
+by, or associated with Peter Lynch, Fidelity Investments, or any related
+organization.
+
+Reports generated with this skill are AI-generated and may contain errors or
+inaccuracies. They are provided for educational and informational purposes only
+and do not constitute financial, investment, tax, accounting, or legal advice.
+Always verify information independently before making investment decisions.
+
+The skill tends to perform poorly on companies that have recently gone public.
+
+## License
+
+Distributed under the **MIT License** — see [`LICENSE`](LICENSE) for details.
+
+---
+
+<p align="center">
+  <sub>
+    Created by <a href="https://www.linkedin.com/in/szymon-nycz/">Szymon Nycz</a>
+    · Inspired by Peter Lynch's philosophy
+  </sub>
+</p>

package/selected-skills/peter-lynch-skill/UPSTREAM.md

@@ -0,0 +1,71 @@
+# Upstream Record
+
+- Project: Peter Lynch Research（一颗 skill、两条工作流：Quick 快筛给 SKIP / WATCHLIST / DEEP RESEARCH，Deep 出完整尽调报告）
+- Repository: https://github.com/DjNero11/peter-lynch-skill
+- Upstream commit: `e0eaf5830f57768cc4fb6543682ae1eb3c8d022c`（main，2026-06-28）
+  - 全仓只有两次提交：上一条 `4f028d6`（2026-06-23，Initial commit）。无 release、无 tag、无 CI。
+- License: MIT；`LICENSE` 为上游原件（`Copyright (c) 2026 Szymon Nycz`），未改写。
+  frontmatter 的 `metadata.author` 是 **Szymon Nycz**，与 GitHub login `DjNero11` 不同名——
+  catalog 的 `owner` 用后者，因为它拼的是仓库链接。
+- Imported content: 该 commit 的完整文件树（`SKILL.md` + `references/` 下 8 份附属文件 + `README.md` + `LICENSE`），
+  132 KB。无脚本、无凭据读取、无出网调用、不落盘产物（`python3` / `node` / `install` 命中 0）。
+- Local modifications（三类，逐条可复核；口径与理由见 `docs/dev/selected-skills.md` §8.6 的接入必查清单）：
+  1. **套了一层 `skills/peter-lynch-skill/`。** 上游把 `SKILL.md` 放在**仓库根**，而 provider 的
+     `customSkillDirs`、`test/selected-skills-content.test.mjs`、`test/packaging.test.mjs`、
+     `test/persona.test.mjs` 与 `capital-config` 的原文旁路五处都按 `<repo>/<skillsDir>/<name>/SKILL.md`
+     反查（AGENTS.md §9.7 那一族：漂了不报错，只是"勾了那一格、技能永远不出现"）。
+     `references/` 跟着 `SKILL.md` 一起搬，正文里的相对链接不破；`SELECTED_SKILL_SKILL_DIRS`
+     因此填 `'skills'`，与前两颗同形。上游 `README.md` 那张仓库结构图随之与实际路径不符——
+     它是**不进 catalog 的材料**，按"不进 catalog 的正文一律不动"原样保留。
+  2. **删除上游的 `.gitignore`。** 它带 `lib/` `build/` `dist/` `tmp/` `*.log` 一类目录规则，今天在这份
+     快照里挡不到东西，但会把 ignore 规则继续带进宿主仓库，并让"按 commit 重导"的快照与所钉 commit
+     不一致（InvestSkill 那一轮就是三个文件被静默挡掉）。vendored 快照不把 ignore 规则带进宿主仓库。
+  3. **取数口径改写**（六份文件共 124 行改动，全部落在"谁去取数"与一处评分释义上；分析结论、
+     预算数字、Source Ledger 字段、`Reported/Calculated/Inference` 标注、停止规则与章节结构一字未改）。
+     上游正文写给"什么工具都在手边"的宿主，与本插件的取数边界冲突：
+     - `SKILL.md` 开篇 `All data comes from **web search and fetched pages**` → 改为"数据来自宿主自己的
+       取数通道；角色分流的宿主里把标的、字段、as-of 日期与来源档写进委派 brief 交出去"（1 处）。
+     - `SKILL.md` Step 3 抬头 `Using the host agent's **web search** and **page fetch** tools:` →
+       `Asking the host's own retrieval path …（delegate it with the brief, do not browse from here）`；
+       配套把预算的计量对象改成"向通道要几次"（`2-3 searches` / `8-12 searches` → `retrieval requests`），
+       **数字一字未动**（2 处）。
+     - `references/{quick,deep}/web-research.md` 里 28 处独立 `search` 的**主语与动词**：
+       `Every search must fill a Source Ledger slot` / `Before adding a search after the third Quick search` /
+       `Do not run separate searches…` / `Use targeted external searches…` → 改成"向宿主取数通道要一份来源"；
+       `Query Pack` 与 `Phase 2` 的 query 清单**原样保留**，只写明"每一条都是向通道要的目标，不是从这里去开的页面"。
+       deep 的 `fetch/read the document` 明确成"把 URL 交给宿主检索通道，PDF 由检索角色解析，用回来的正文继续"
+       （合计 14 处句子级改动）。
+     - `references/deep/system-prompt.md` 的 `… use web search results for recent strategic and competitive
+       context` → "use what the host's retrieval path returned…"。这是 `test/selected-skills-content.test.mjs`
+       六条 FORBIDDEN 在本颗的**唯一实际命中**（1 处）。
+     - `SKILL.md` 失效处理 `If web search is unavailable: state the limitation and stop — do not fabricate data`
+       → "宿主对某个字段没有可用取数路径时：点名缺哪些字段、该字段下的分析停止"；后半句 `do not fabricate data`
+       原样保留。同段 `use another reputable aggregator` → `ask the channel for another reputable aggregator`（2 处）。
+     - `SKILL.md` 的 Required inputs 之后加一段**市场口径**说明：正文的 aggregator / SEC-EDGAR / Form 4-13F /
+       wash-sale 都是美股与境外上市口径，A 股会话要换成 A 股披露口径，而换口径由宿主取数通道决定，
+       不由这颗 skill 自行联网去补（§8.6 第 8 条；`us-stock` 标签就是给使用者的提示）。
+     - `references/deep/methodology.md` §10 Final Score 加一句：X/10 衡量的是论点自洽度与结构特征，
+       不预测价格或收益，也不是买卖指令（§8.6 第 7 条 / CONTRIBUTING.md §3 第 8 条）。
+     **没有新增 `Retrieval:` 出处档**：上游既没有这个枚举，也不把记忆列成取数途径——
+     第 2 条（记忆回填）在本颗**实测零命中**（`model memory` / `training-data` / `Live data unavailable` 全无），
+     `system-prompt.md` 本来就把取回的东西限定成"来自研究简报"。不为了套 InvestSkill 的改法新造上游没有的模板字段。
+  复核方法：`git clone` 所钉 commit 后 `diff -r`，差异只应包含以上三类；
+  `test/selected-skills-content.test.mjs` 扫正文**结果**、本文件记**理由**，两边任一漂回去都会红。
+- Packaging: 这颗**不带 `.npmignore`**——除 `README.md`（13 KB）之外全是运行时正文与溯源，包体积增量约 120 KB，
+  没有需要挡的成图、静态站或脚本目录（`china-stock-research-skills` 同样没挡）。
+  `package.json` 的 `files` 已逐仓库登记 `selected-skills/peter-lynch-skill`，
+  `test/packaging.test.mjs` 从 catalog 反查发布清单里的真实 `SKILL.md` / `LICENSE` / `UPSTREAM.md`。
+- Catalog 收录判断：`SKILL.md` 内部的 Quick / Deep 二选一**不算**"会接管会话路由的编排 skill"——
+  它不跨 Agent、不改本插件的角色分流，只在本颗的两条工作流之间选择（`china-stock-research-orchestrator`
+  与 InvestSkill 的 `full-report` 是另一类东西）。也不触发 §7（报告交付链路已删除）与 §6.1（出图只走
+  `render_chart`）：这颗的输出是**最终答复里的 markdown 报告**，不落文件、不出图。
+- Maintenance snapshot (checked 2026-10-11): 全仓两次提交，最后一次 2026-06-28，之后 105 天无提交；
+  单人仓库、无 issue 响应记录。因此标 `watchlist`——与 `china-stock-research-skills` 同一口径
+  （内容可用、维护薄，启用前请使用者自行复核来源），而不是内容缺陷。
+  See [GitHub commit history](https://github.com/DjNero11/peter-lynch-skill/commits/main/)。
+- Runtime status: `watchlist` / 默认关闭的显式实验。只有使用者在「插件」→ Capital Generation →「精选 Skills」
+  里亲手打开，它才对**之后新建**的 Capital 根 Agent 可见；子 Agent 不继承，上游附属文件从不执行。
+  能力标签（含本颗带来的新标签 `peter-lynch`）与 `riskNote` 维护在 `selected-skills/catalog.js`。
+- Review status: 2026-11-06 复查上游、许可证与维护状态。正文是 Lynch 三部著作（*One Up on Wall Street*、
+  *Beating the Street*、*Learn to Earn*）方法论的**二手转写**，与 Lynch 本人、Fidelity 或 Capital Generation
+  均无关联，不构成背书；美股口径不得直接当作 A 股规则，所有金融主张须回到原始证据核验。

package/selected-skills/peter-lynch-skill/skills/peter-lynch-skill/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: peter-lynch-skill
+description: >-
+  Peter Lynch-style stock research from a ticker or company name: quick
+  screening or deep due diligence with linked web citations. Use when the user
+  asks for quick research, screening, an initial look, deep research, due
+  diligence, full analysis, valuation context, an attractiveness score, or a
+  SKIP / WATCHLIST / DEEP RESEARCH decision.
+license: MIT
+metadata:
+  author: Szymon Nycz
+  version: "1.0"
+---
+
+# Peter Lynch Research
+
+One skill, two workflows. Answers either:
+
+- **Quick:** Is this company worth 2–5 hours of deeper research? (~450 words, SKIP / WATCHLIST / DEEP RESEARCH)
+- **Deep:** Full due-diligence report (up to 3000 words, attractiveness score X / 10 — how consistent and well-supported the thesis reads, not a forecast of performance)
+
+All data comes from **the host's own retrieval path** — no API keys, no bundled scripts, no user-provided PDFs. In a host that splits roles, gathering it is not this skill's job: write the exact brief (ticker or company, the fields needed, the as-of date, the source tier) and hand it to the host's retrieval channel, then work only from what comes back. Time-sensitive market data must be freshly gathered and dated. Every retrieved claim in the final report must be cited with a link.
+
+Use different source depth by workflow:
+
+- **Quick:** aggregator-only screening. Use reputable financial-data aggregator pages by default; do not open annual report PDFs, full 10-K / 10-Q / 20-F filings, SEC filing detail pages, company quarterly reports, or long investor-relations documents.
+- **Deep:** official-source due diligence. Use annual reports, filings, company results, and official investor materials as the factual base; use aggregators mainly for valuation and market-data gaps.
+
+Operate with strict evidence-budget discipline. The goal is high-quality research from the smallest reliable source set, not exhaustive browsing. Do not narrate research progress or intermediate retrieval reasoning in the final answer.
+
+## Routing
+
+Determine the workflow from the user's message:
+
+| Trigger keywords | Workflow |
+|------------------|----------|
+| quick research, screening, filter, initial look, worth researching | **Quick** |
+| deep research, due diligence, full analysis, attractiveness score, score / 10 | **Deep** |
+
+- If intent is **ambiguous**, ask one question: *"Quick screening (~450 words) or deep due diligence (~3000 words)?"*
+- If still unclear after one exchange, default to **Quick**.
+
+## Required inputs
+
+- `company_symbol` or `company_name` — ticker (e.g. `MSFT`, `ASML.AS`, `VOD.L`) or company name. If the user gives only a brand, company name, or ambiguous ticker, resolve the traded entity before analysis. For Quick, use reputable aggregator profile / quote pages. For Deep, use official, exchange, or regulator sources.
+- `exchange` or `country` — optional hint for global tickers
+
+If neither a company nor ticker can be inferred from the request, ask one concise clarification question.
+
+The source tiers below (aggregator profile pages, SEC / regulator filings, annual reports) are US and overseas-listing conventions. In an A-share session the same analysis must be asked for in A-share terms instead — disclosure platforms, no Form 4 / 13F, no wash-sale rules — and that is decided by the host's retrieval channel, not by this skill.
+
+Do **not** ask the user for an annual report PDF or API keys.
+
+## Workflow overview
+
+Copy this checklist and track progress:
+
+```
+Task Progress:
+- [ ] Step 1: Route (quick or deep)
+- [ ] Step 2: Read workflow-specific web research guide
+- [ ] Step 3: Gather data and compile structured research brief
+- [ ] Step 4: Read workflow prompts
+- [ ] Step 5: Write report from the brief only
+- [ ] Step 6: Append disclaimer
+```
+
+### Step 1: Route
+
+Select **Quick** or **Deep** using the routing table above.
+
+### Step 2: Read workflow-specific web research guide
+
+Read only the workflow-specific web guide:
+
+- **Quick:** [references/quick/web-research.md](references/quick/web-research.md)
+- **Deep:** [references/deep/web-research.md](references/deep/web-research.md)
+
+Read [references/filing-rules.md](references/filing-rules.md) only when regulator/XBRL data, ADRs, secondary listings, specialized financial companies, or accounting-basis issues matter. Do not read it for normal Quick Research unless the Quick web guide specifically triggers it.
+
+### Step 3: Gather data and compile research brief
+
+Asking the host's own retrieval path for the data (in a host that splits roles: delegate it with the brief, do not browse from here):
+
+1. Follow the **workflow-specific** source plan, retrieval brief, stopping rule, and research brief template in `references/quick/web-research.md` or `references/deep/web-research.md`.
+2. Respect the workflow-specific default budgets unless an override in that workflow guide is triggered — the budget is how many sources you ask the channel for, not how many you go and open yourself:
+   - **Quick:** practical default of 1-3 reputable aggregator sources, 2-3 retrieval queries, and 2-3 page fetches; expand only when another aggregator is needed to complete the existing Quick methodology.
+   - **Deep:** 5-7 sources, 6-8 retrieval queries, 7-10 page/document fetches, with the default source set kept as small as the report can support.
+3. For **Quick**: gather the minimum viable evidence needed for a responsible SKIP / WATCHLIST / DEEP RESEARCH decision, then stop.
+4. For **Deep**: follow the annual report discovery procedure in `references/deep/web-research.md` — ask for the latest full annual report on the company's investor relations site (HTML or PDF); regulator filings are the fallback.
+5. Do not ask for a separate retrieval per fiscal year for normal historical metrics. For Quick, use aggregator tables. For Deep, use the annual report, 10-K / 20-F, regulator filing, or regulator facts feed as the historical base.
+6. Do not print research narration, retrieval play-by-play, or the full research brief unless the user asks for it.
+7. Capture period, currency, units, date gathered, and source ID(s) for every important number and claim. Each source ID must resolve to a URL in the Source Ledger. Filing labels may be included, but they do not replace a ledger URL.
+8. Do **not** invent financial data.
+
+### Step 4: Read workflow prompts
+
+**Quick path** — read both before writing:
+
+- [references/quick/system-prompt.md](references/quick/system-prompt.md)
+- [references/quick/methodology.md](references/quick/methodology.md)
+
+**Deep path** — read both before writing:
+
+- [references/deep/system-prompt.md](references/deep/system-prompt.md)
+- [references/deep/methodology.md](references/deep/methodology.md)
+
+### Step 5: Write report
+
+Use the research brief as the only factual context for the report. Do not include the full research brief in the final report unless the user asks for it.
+
+Every final report must cite sources with links:
+
+- Any company description, financial number, valuation metric, market data point, management claim, industry claim, competitor claim, ownership claim, or news/update claim needs a source.
+- Use source lines directly below the relevant bullet or paragraph: `source: [Source name](https://...)`.
+- Multiple sources may be separated with semicolons.
+- Do not cite a source that is not in the research brief Source Ledger.
+- Expand any internal source IDs from the brief into full linked `source:` lines in the final report.
+- Source lines do not count toward Quick or Deep word limits.
+
+Internally prefix the analysis context with:
+
+```
+Data gathered: YYYY-MM-DD
+
+## Research brief
+
+{full research brief markdown}
+```
+
+### Step 6: Append disclaimer
+
+Read [references/disclaimer.md](references/disclaimer.md) only when the report body is ready. After the report body, add a horizontal rule and append the full contents of the disclaimer.
+
+## Failure handling
+
+- If the host's retrieval path returns nothing for a field you need: name the missing fields and stop the analysis that depends on them — do not fabricate data.
+- If a ticker cannot be resolved: inform the user clearly.
+- If the annual report cannot be found after all fallbacks in `references/deep/web-research.md`: note the gap in the research brief and proceed using other verified sources — do **not** ask the user for a PDF.
+- If a specific metric is unverified: say you do not know; do not estimate or invent numbers.
+- If retrieved claims lack source ID(s) that resolve to Source Ledger URL(s): do not include them in the report.
+- If live market data cannot be verified from the current source: for Quick, ask the channel for another reputable aggregator; for Deep, use the workflow's market-data fallback rules. Do not use stale or unsourced values.