hk-ipo/.codex/skills/analyst/SKILL.md

---

name: analyst description: Use for Hong Kong IPO subscription analysis in this project: T0/T1/T2 prediction cards, scoring, cross-IPO comparison, research reports, post-listing reviews, error attribution, and rule-update recommendations. Use archived facts when available and keep predictions append-only.

HK IPO Analyst

Purpose

Assess Hong Kong IPO subscription candidates using the project's archived facts, scoring rules, prediction cards, and review history. This skill owns judgment: whether to subscribe, wait, avoid, sell in grey market or on D1, or revise a rule after outcomes arrive.

Use archivist first when source documents, listing facts, allotment results, prices, or database snapshots need to be updated.

Core Discipline

Separate the decision stage from later facts:

• T0_prospectus: prospectus and offer terms only.
• T0_5_market_heat: subscription-period non-official market heat, such as broker-aggregated margin subscription multiples, observed before official allotment results.
• T1_allotment: allotment results, public subscription, international placing, allocation, and final pricing.
• T2_grey_market: grey-market result and immediate pre-listing trading context.
• D1, D5, D20, D60: post-listing review checkpoints.

Do not let later facts leak into earlier prediction cards. When reviewing an older call, compare the frozen prediction against the actual outcome instead of rewriting the original judgment.

Trading Horizon

The analyst model is a short-exit IPO subscription model, not a long-term holding model.

• The intended exit is T2_grey_market when a reliable grey-market signal and executable price are available, or D1 otherwise.
• The default assumption is to sell allocated shares by D1 unless a later rule explicitly creates a documented exception.
• D5/D20/D60 are review labels for learning, not holding targets and not inputs for subscription decisions.
• Reports should frame expected return, triggers, and exit discipline around T2/D1 realization rather than long-term fundamentals.
• Recommendations should avoid long-hold language unless the user explicitly asks for a separate long-term investment thesis.

Project Storage Contract

Use repo-relative paths everywhere:

• Memos: memos/{ticker}_{stage}_{date}.md
• Reports: reports/{date}_{topic}.md or another repo-relative report path requested by the user.
• Rules: rules/ipo_score_v*.yaml and rules/rule_change_log.md
• Source references: cite archived files using paths such as data/raw/06658/prospectus.pdf

Never store or cite machine-specific absolute paths in durable project files.

Responsibilities

• Produce IPO subscription analysis and cross-candidate rankings.
• Write append-only T0/T1/T2 prediction cards.
• Include probability forecasts, score breakdowns, key reasons, risks, triggers, and exit discipline.
• Review actual outcomes against prior predictions.
• Attribute errors using stable tags such as fundamental_miss, valuation_miss, heat_miss, structure_miss, market_window_miss, execution_miss, and data_gap.
• Recommend scoring-rule changes only after evidence supports them.

Boundaries

Do not silently mutate archived source facts. If facts are missing or stale, call out the data gap and use archivist to update the archive before relying on them.

Do not overwrite prediction cards. If a view changes, write a new stage card or review card that references the earlier prediction.

Workflow

1. Inspect current repo state and recent commits before changing files.
2. Determine the requested stage: T0, T1, T2, or post-listing review.
3. Load available archived facts and rules from repo-relative project files.
4. If facts are missing or stale, update the archive through archivist or state the gap clearly.
5. Score the IPO using the current rule version.
6. Record probability forecasts rather than only directional language.
7. Write a memo/report with data-as-of time, rule version, sources, score, decision, and triggers.
8. For reviews, compare the frozen prediction to actual outcomes and classify the error type.
9. Commit only the related memo/report/rule changes after verification.

Single-Ticker Markdown Report

When the user gives a single IPO ticker and asks for an analyst report, use the report generator after archived facts and the analysis dataset are current:

.venv/bin/python scripts/build_analysis_dataset.py --as-of YYYY-MM-DDTHH:MM:SSZ
.venv/bin/python scripts/generate_ipo_report.py 06658 --stage auto

The generator writes reports/{date}_{ticker}_{stage}_analysis.md by default. Use --stdout for a dry run, --stage T0_prospectus to force a prospectus-stage report, or --stage T1_allotment only when structured T1 demand exists.

If the ticker is absent from data/snapshots/analysis_model_v0_dataset.csv, use archivist first to archive the IPO facts and rebuild the analysis dataset before generating the report.

Generated prediction reports must remain stage-safe:

• Analyst Markdown reports should be written in Simplified Chinese by default, while preserving ticker symbols, stage codes, rule ids, source paths, and stable error tags in their original machine-readable form.
• T0 reports use only prospectus-stage fields and T0 calibration.
• T0.5 reports may add archived ipo_market_heat rows, but must label them as non-official, live market-heat snapshots and include observed_at, provider, and source path.
• T1 reports may add allotment demand fields and T1 calibration.
• T2/D1 is the intended sell window; D5/D20/D60 returns are never shown as prediction inputs and are reserved for later review cards.
• Every report must include a concrete stage calendar for the ticker: T0 subscription window, T1 allotment-result date, T2 grey-market date/window, and D1 listing date.

T0.5 Market Heat Overlay

Use rules/ipo_score_v0_5_market_heat_trial.yaml when the user asks to include subscription-period heat before official allotment results.

T0.5 discipline:

• Use archivist first to archive the raw source page and structured ipo_market_heat rows.
• Keep T0.5 separate from official T1 demand. Do not copy T0.5 margin multiples into ipo_demand.public_oversubscription_times.
• Keep third-party final history, such as external_ipo_history.public_oversubscription_times, separate from T0.5. It is useful for post-hoc calibration but is not available at the original T0.5 decision time.
• Treat raw margin multiples as less reliable when IPOs are at different points in their subscription windows.
• Freeze the observed_at timestamp in the report so later T1/D1 reviews can test whether the heat signal helped.
• Write T0.5 conclusions as watchlist upgrades/downgrades, not as final high-conviction subscription calls.

Output Standards

Every prediction card should include:

• ticker
• stage
• data_as_of
• concrete T0/T1/T2/D1 dates for the ticker
• rule_version
• decision
• total_score
• score breakdown
• probability forecast
• expected return framing
• key bull points
• key risks
• triggers for upgrade/downgrade
• exit plan
• explicit T2/D1 sell discipline
• source paths

Language standard:

• Write analyst reports, prediction cards, and review cards in Simplified Chinese by default.
• Keep field identifiers, model versions, score buckets, ticker symbols, and source paths as code-formatted English identifiers when they are part of the project data contract.

Every review card should include:

• linked prediction card
• actual IPO outcome
• direction correctness
• magnitude error
• reason correctness
• execution assessment
• error tags
• rule-change recommendation, if any

Quality Checks

Before finishing, confirm:

• The analysis stage matches the information set used.
• Later facts are not used in earlier-stage conclusions.
• Paths in durable files are repo-relative.
• Probabilities and scores are explicit.
• Facts, assumptions, estimates, inferences, and PM judgment are separated.
• Any rule update has a named trigger case and an effective date.