TW Stock Researcher

New here? Read FIRST_RUN.md first for the quick-start checklist.

What This Is

This repository is a markdown-first workspace template for researching one stock thesis at a time. It is designed to keep a case persistent across sessions so facts, inference, open questions, signals, and active decisions stay separate and reviewable.

Core Principles

• Work one stock case at a time.
• Preserve reusable files instead of one-off chat summaries.
• Separate facts, inferences, open questions, and thesis changes.
• Prefer public and free sources unless the user explicitly provides something else.
• Update the case incrementally when new signals arrive.

Standard Workflow

1. Start a case with stock-case-init.
2. Fetch Yahoo profile + financials with yahoo-profile-financials.
3. Build the company view with company-deep-dive.
4. Run financial analysis with financial-analysis (Goodinfo annual via fetch_goodinfo.py plus official monthly revenue, quarterly statements, and valuation band via fetch_fundamentals.py).
5. Map industry drivers with industry-transmission-analysis.
6. Filter macro variables with macro-impact-analysis.
7. Add the value-investor quality layer with quality-and-valuation-check.
8. Write the current thesis with investment-thesis.
9. Refresh TDCC and FinMind market data with market-data-fetch.
10. Add the market-state layer with market-action-read; after this final evidence layer is complete, automatically refresh the derived HTML summary with research-html-output.
11. Use signal-update for new filings, revenue releases, or news.
12. Use case-revisit when returning to the case later.
13. Use session-wrap before ending a session to record expected evidence, thesis kill criteria, and tracking triggers in active-decisions.md.

Research Run Boundary

研究 <ticker> runs the existing workflow only for that case. It may write to the matching companies/<ticker>-<slug>/ directory and required current shared data under market/; it must not modify skills, templates, scripts, the renderer, another case, or workspace policy unless the user explicitly requests a system change. Every case-file update must be evidence-linked to the current fetch results.

Data Layout

The workspace keeps shared market context under market/, reusable templates under templates/, and per-stock cases under companies/. Create shared market files in market/ by copying the corresponding templates from templates/ when needed. See docs/data-layout.md for file ownership and docs/data-freshness.md for stale-data defaults.

HTML Summary Output

Markdown and JSON files remain the source of truth. When the user explicitly asks for a comprehensive research result as HTML, or when the standard workflow finishes market-action-read, use the research-html-output skill and render a derived preview from templates/research-html-summary.html.

The HTML output is produced by string replacement, not by changing the canonical case files:

.venv/bin/python scripts/render_research_html.py \
  --data companies/<ticker-slug>/research-summary-data.json \
  --output companies/<ticker-slug>/research-summary.html

After the market-action-read.md evidence layer is verified, build the JSON payload from the completed current case files, then let scripts/render_research_html.py replace the template placeholders. The HTML output stays in that company folder as companies/<ticker-slug>/research-summary.html.

Do not reuse, patch, or manually reconstruct a prior payload as a substitute for the current case synthesis. If the current payload cannot satisfy the template contract, stop and report the blocker; do not change the workflow contract during a stock research run. The shared template includes the research snapshot, expectation gap, pricing-stage verification, confidence calibration, cross-layer conflicts, adversarial review, data availability, evidence timeline, scenario summary, watch items, and source quality.

Rendered HTML Preview

The screenshot below is the result of rendering a case into HTML with scripts/render_research_html.py.

The Skills

These project-local workflow skills live under .agents/skills/<skill-name>/SKILL.md.

• stock-case-init: create case metadata, core questions, and initial open questions.
• yahoo-profile-financials: run the Yahoo profile and supplemental financial fetch flow.
• company-deep-dive: analyze business model, products, customers, and revenue structure.
• financial-analysis: run Goodinfo first, then write the financial fact layer with MOPS cross-checks.
• industry-transmission-analysis: map the industry chain and leading indicators.
• macro-impact-analysis: keep only macro variables that materially transmit into the case.
• quality-and-valuation-check: assess ROIC, owner earnings, working-capital quality, capital allocation, implied expectations, and margin of safety.
• investment-thesis: produce the current memo with assumptions and disconfirming evidence.
• market-data-fetch: refresh TDCC ownership distribution and FinMind market data for the requested stock id.
• market-action-read: summarize market state, institutional flow, and egg-theory evidence without trading instructions, then automatically render the summary HTML preview.
• research-html-output: derive the current HTML payload and preview from completed case files using templates/research-html-summary.html and scripts/render_research_html.py; it does not alter source evidence layers.
• signal-update: append new events and decide whether the thesis changed.
• case-revisit: re-enter an existing case with a file-grounded summary.
• session-wrap: preserve unresolved questions, expected evidence, thesis kill criteria, decisions, and next follow-ups.

Getting Started

1. Read FIRST_RUN.md.
2. Start a new case with stock-case-init so metadata, research questions, and open questions are created in the right order.
3. Use the files in templates/ as the canonical shapes for the artifacts each skill should create or update.
4. Create shared market context files in market/ by copying the corresponding templates from templates/ when needed.
5. Run the structure and skill checks in tests/ after changing the workspace.

Usage Examples

Example 1: Researching a new stock

User: "幫我分析 3105 穩懋"

What happens:

1. stock-case-init creates companies/3105-awsc/ directory
2. yahoo-profile-financials runs scripts/fetch_yahoo.py 3105 → saves yahoo-data.json in the case directory
3. Fetches Yahoo profile + financials (revenue, margins, cash flow) for the company deep-dive input
4. financial-analysis runs scripts/fetch_goodinfo.py 3105 → saves raw-data.json in the case directory
5. Uses Goodinfo data with MOPS cross-check links for financial-analysis primary evidence
6. Writes company-analysis.md with business model, product mix, margin analysis
7. Writes financial-analysis.md with 3D analysis (經營/獲利/財務健全度) using Goodinfo data
8. Writes industry-transmission.md mapping the industry chain
9. Writes macro-map.md filtering relevant macro variables
10. Writes quality-and-valuation-check.md with business quality, implied expectations, and margin-of-safety evidence
11. Writes investment-memo.md with Bull/Base/Bear scenarios using the investment-reasoning-framework.md pricing framework
12. market-data-fetch runs TDCC then FinMind with FIN_MIND_TOKEN when needed → saves tdcc-data.json and market-data.json in the case directory
13. Writes market-action-read.md with 1D/3D/5D price-volume, institutional flow, holder distribution, and egg-theory evidence
14. Refreshes research-summary-data.json and renders research-summary.html
15. Records expected evidence timeline and thesis kill criteria in active-decisions.md
16. Updates stock-meta.json with all file references

Files created:

companies/3105-awsc/
├── stock-meta.json          # Case index
├── yahoo-data.json          # Yahoo profile, revenue, margins, and cash-flow summary
├── raw-data.json            # Goodinfo raw financial data
├── fundamentals-data.json   # FinMind monthly revenue, quarterly statements, valuation band
├── tdcc-data.json           # TDCC ownership distribution snapshot
├── research-questions.md    # Core questions & unknowns
├── open-questions.md        # Active open questions
├── active-decisions.md      # Research stance & tracking triggers
├── company-analysis.md      # Business model deep-dive
├── financial-analysis.md    # 3D financial analysis
├── industry-transmission.md # Industry chain & leading indicators
├── macro-map.md            # Macro variables
├── quality-and-valuation-check.md # Quality, implied expectations, margin of safety
├── investment-memo.md      # Investment thesis (dual framework)
├── market-data.json        # FinMind price/volume, institutional, margin, and egg-theory data
├── market-action-read.md   # Neutral market-state read
├── research-summary-data.json # HTML summary payload
├── research-summary.html   # Derived summary preview
├── signal-log.md           # Append-only event log
└── thesis-updates.md       # Explicit thesis changes from new signals

Example 2: Updating a case with new data

User: "更新 2344 華邦電最新財報"

What happens:

1. signal-update classifies the new item and reads the existing case files
2. Refreshes the relevant fetcher only when the signal depends on updated structured data
3. Appends the event to signal-log.md
4. Updates only the affected thesis or tracking section when the signal changes the research stance

Example 3: Revisiting a case

User: "我上次研究的 6789 采鈺現在怎麼樣了？"

What happens:

1. case-revisit reads stock-meta.json to find the case
2. Summarizes current active decisions from active-decisions.md
3. Lists open questions from open-questions.md
4. Suggests next follow-ups

Example 4: Multi-stock comparison

Peer comparison is outside the one-stock case workflow. Keep each stock in its own case; do not write a cross-company comparison into a case-owned analysis file.

Key Conventions

• Raw data: Always saved as companies/{ticker-slug}/raw-data.json, never in repo root
• Yahoo data: Always saved as companies/{ticker-slug}/yahoo-data.json, never in repo root
• Market data: Always saved as companies/{ticker-slug}/market-data.json, never in repo root
• Financial data: Goodinfo.tw is the annual primary source; scripts/fetch_fundamentals.py adds official monthly revenue, quarterly statements, and the P/E / P/B valuation band (fundamentals-data.json); always include MOPS links for cross-checking
• Macro data: Taiwan-focused. Run scripts/fetch_macro.py to refresh market/shared-macro-data.json (TWSE Open API, Yahoo Finance, MOF customs trade statistics by default); include only variables with a concrete company-level transmission path
• Quality and valuation: Keep business-quality judgment and implied market expectations in quality-and-valuation-check.md; the investment memo should consume its conclusion, not duplicate its tables
• Expectation gap: Use investment-memo.md to separate market belief, verified evidence, narrative-only claims, and the evidence needed to close or invalidate the gap
• Market action: market-action-read.md summarizes evidence only; it must not output trade instructions
• Market data fetch: run market-data-fetch before market-action-read when TDCC, FinMind, or egg-theory data is stale
• Tracking discipline: Use active-decisions.md for expected evidence timelines, thesis kill criteria, and review triggers so a case can be downgraded when evidence stops compounding
• Thesis format: Dual framework (Business Thesis + Pricing Thesis per investment-reasoning-framework.md)
• Pricing stages: Stage 1 (narrative expansion) → Stage 2 (fundamentals catch up) → Stage 3 (growth slows)
• No unsupported targets: Never generate price targets without scenario analysis

What This Is Not

• Not a trading bot.
• Not a valuation engine.
• Not a scheduler or watchlist product.
• Not a source of guaranteed returns, price targets, or trade orders.