From 408ba59bc657911d67ef3884d1a269a2bca047e3 Mon Sep 17 00:00:00 2001
From: geometrybase <geometrybase@gmail.com>
Date: Mon, 15 Jun 2026 06:02:10 +0000
Subject: [PATCH] Document HK IPO project workflow

Request:
- Write a README introducing the project.

Changes:
- Describe the HK IPO research feedback loop.
- Document the stage-based workflow, project-local skills, storage model, path rules, and Git discipline.

Verification:
- Reviewed README contents with sed.
- Ran rg for machine-specific absolute path patterns; none found.
- Ran git diff --check.
---
 README.md | 92 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 92 insertions(+)

diff --git a/README.md b/README.md
index e69de29..b446cbe 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,92 @@
+# HK IPO
+
+HK IPO is a project for building a repeatable, auditable research workflow for Hong Kong new listing subscription decisions.
+
+The project is designed around a feedback loop:
+
+1. Archive IPO facts and source documents.
+2. Freeze the analysis that was possible at each decision stage.
+3. Compare predictions with post-listing outcomes.
+4. Improve the scoring rules only from reviewed evidence.
+
+## Goals
+
+- Maintain a local, Git-tracked history of Hong Kong IPO data.
+- Separate factual archiving from investment judgment.
+- Keep every subscription decision tied to the information available at that time.
+- Review actual IPO outcomes against prior predictions.
+- Build a better IPO scoring process through structured error attribution.
+
+## Workflow
+
+Each IPO is evaluated by stage:
+
+- `T0_prospectus`: prospectus and offer terms only.
+- `T1_allotment`: allotment results, public subscription, placing, allocation, and final pricing.
+- `T2_grey_market`: grey-market result and immediate pre-listing context.
+- `D1`, `D5`, `D20`, `D60`: post-listing review checkpoints.
+
+The key discipline is to avoid hindsight leakage. A T0 prediction should only use T0 information, even after the IPO has listed.
+
+## Project Skills
+
+This repository includes project-local Codex skills under `.codex/skills/`.
+
+### `archivist`
+
+Owns facts and source control:
+
+- archive prospectuses, allotment results, listing facts, and market data;
+- record source URLs, as-of timestamps, repo-relative paths, and file hashes;
+- update the embedded SQLite database;
+- export Git-friendly CSV snapshots.
+
+It does not make investment recommendations.
+
+### `analyst`
+
+Owns IPO judgment and review:
+
+- produce T0/T1/T2 prediction cards;
+- score IPO candidates;
+- compare multiple IPOs;
+- write research memos and review cards;
+- classify forecast errors;
+- recommend scoring-rule updates.
+
+It should use archived facts when available and keep prediction cards append-only.
+
+## Storage Model
+
+The project is intended to be self-contained and portable across machines. Durable paths should always be relative to the repository root.
+
+Expected layout:
+
+```text
+data/
+  hk_ipo.sqlite
+  raw/
+  snapshots/
+memos/
+reports/
+rules/
+schema/
+scripts/
+references/
+```
+
+Path rules:
+
+- store paths like `data/raw/06658/prospectus.pdf`;
+- do not store absolute paths;
+- do not store paths with a leading `./`;
+- use POSIX `/` separators;
+- store file hashes for archived source documents when practical.
+
+SQLite is the embedded source of structured facts. CSV snapshots provide readable Git diffs. Markdown memos preserve the reasoning at each decision point.
+
+## Git Discipline
+
+The repository uses automatic focused commits for completed project changes. Push only when explicitly requested.
+
+Before committing, check that unrelated dirty files are not included and that generated durable files use repo-relative paths.