From 67b78cc172a840c01a8b9bf24ca6699605fbc95b Mon Sep 17 00:00:00 2001 From: geometrybase Date: Mon, 15 Jun 2026 05:53:53 +0000 Subject: [PATCH] Add project-local HK IPO skills Request: - Keep the HK IPO workflow skills inside the repo so they travel with the project. - Use concise names while preserving clear HK IPO scope and repo-relative path rules. Changes: - Add .codex/skills/archivist for source archiving, SQLite fact updates, hashes, and CSV snapshots. - Add .codex/skills/analyst for T0/T1/T2 IPO decisions, prediction cards, reviews, and rule-change recommendations. - Add agents/openai.yaml metadata for both skills. Verification: - Checked staged changes include only .codex skill files. - Searched .codex for machine-specific absolute path patterns; none found. Next useful context: - AGENTS.md remains untracked and was not included in this commit. --- .codex/skills/analyst/SKILL.md | 102 +++++++++++++++++++++ .codex/skills/analyst/agents/openai.yaml | 7 ++ .codex/skills/archivist/SKILL.md | 82 +++++++++++++++++ .codex/skills/archivist/agents/openai.yaml | 7 ++ 4 files changed, 198 insertions(+) create mode 100644 .codex/skills/analyst/SKILL.md create mode 100644 .codex/skills/analyst/agents/openai.yaml create mode 100644 .codex/skills/archivist/SKILL.md create mode 100644 .codex/skills/archivist/agents/openai.yaml diff --git a/.codex/skills/analyst/SKILL.md b/.codex/skills/analyst/SKILL.md new file mode 100644 index 0000000..adc0877 --- /dev/null +++ b/.codex/skills/analyst/SKILL.md @@ -0,0 +1,102 @@ +--- +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, hold after allocation, 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. +- `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. + +## 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. + +## Output Standards + +Every prediction card should include: + +- `ticker` +- `stage` +- `data_as_of` +- `rule_version` +- `decision` +- `total_score` +- score breakdown +- probability forecast +- expected return framing +- key bull points +- key risks +- triggers for upgrade/downgrade +- exit plan +- source paths + +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. diff --git a/.codex/skills/analyst/agents/openai.yaml b/.codex/skills/analyst/agents/openai.yaml new file mode 100644 index 0000000..af1425f --- /dev/null +++ b/.codex/skills/analyst/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "HK IPO Analyst" + short_description: "Score HK IPOs and review prediction quality" + default_prompt: "Use $analyst to evaluate a Hong Kong IPO subscription candidate from archived project data." + +policy: + allow_implicit_invocation: true diff --git a/.codex/skills/archivist/SKILL.md b/.codex/skills/archivist/SKILL.md new file mode 100644 index 0000000..33bdf37 --- /dev/null +++ b/.codex/skills/archivist/SKILL.md @@ -0,0 +1,82 @@ +--- +name: archivist +description: Use for Hong Kong IPO fact archiving in this project: downloading or recording prospectuses, allotment results, listing facts, market data, source references, file hashes, SQLite updates, and CSV snapshots. Do not use for investment conclusions, subscription recommendations, score interpretation, or research memos. +--- + +# HK IPO Archivist + +## Purpose + +Maintain the project-local Hong Kong IPO evidence archive and structured fact database. This skill owns facts, sources, database updates, path hygiene, and reproducible snapshots. + +It does not decide whether an IPO is worth subscribing for. Route judgment, scoring, prediction cards, review cards, and reports to `analyst`. + +## Project Storage Contract + +Use repo-relative paths everywhere. Never store machine-specific absolute paths. + +- Resolve the repo root at runtime, for example with `git rev-parse --show-toplevel`. +- Store paths without a leading `./`. +- Store paths with POSIX separators, such as `data/raw/06658/prospectus.pdf`. +- Store `path_base = "repo_root"` when a table needs an explicit base. +- Store `file_sha256` for archived source files whenever practical. + +Expected project layout: + +```text +data/ + hk_ipo.sqlite + raw/ + snapshots/ +memos/ +reports/ +rules/ +schema/ +scripts/ +references/ +``` + +## Responsibilities + +- Archive primary source files under `data/raw/{ticker}/`. +- Record source references, URLs, as-of timestamps, relative paths, and hashes. +- Update embedded SQLite tables for IPO facts. +- Export Git-friendly CSV snapshots after database updates. +- Preserve raw source files; do not overwrite without first checking whether the contents changed. +- Label missing, stale, inconsistent, or estimated fields explicitly. + +## Boundaries + +Do not write: + +- Subscription decisions. +- Investment ratings. +- Scoring interpretations. +- Prediction cards. +- Review conclusions. +- Rule-change recommendations. + +If a user asks for both data update and analysis, complete the archive/update step first, then hand the frozen as-of dataset to `analyst`. + +## Workflow + +1. Inspect current repo state and recent commits before changing files. +2. Identify the IPO ticker, company, stage, and source documents needed. +3. Save raw source files under `data/raw/{ticker}/` using descriptive names. +4. Compute hashes for archived files. +5. Insert or update structured facts in `data/hk_ipo.sqlite`. +6. Record every source in the source reference table using repo-relative paths. +7. Export key tables to `data/snapshots/` for readable Git diffs. +8. Verify path rules, required fields, and snapshot generation. +9. Commit only the related archive/database/snapshot changes. + +## Quality Checks + +Before finishing, confirm: + +- No stored local path is absolute. +- No stored local path starts with `./`. +- Raw files referenced by the database exist. +- Source hashes match current file contents. +- CSV snapshots reflect the database update. +- Any unavailable field is marked as a data gap rather than invented. diff --git a/.codex/skills/archivist/agents/openai.yaml b/.codex/skills/archivist/agents/openai.yaml new file mode 100644 index 0000000..70f50c3 --- /dev/null +++ b/.codex/skills/archivist/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "HK IPO Archivist" + short_description: "Archive HK IPO facts, sources, and snapshots" + default_prompt: "Use $archivist to update the project IPO archive for a Hong Kong new listing." + +policy: + allow_implicit_invocation: true