diff --git a/.codex/skills/audit/SKILL.md b/.codex/skills/audit/SKILL.md new file mode 100644 index 0000000..7022d51 --- /dev/null +++ b/.codex/skills/audit/SKILL.md @@ -0,0 +1,117 @@ +--- +name: audit +description: Use for independent audit of Hong Kong IPO archive quality and analysis quality in this project: confirm data completeness, data sufficiency, source integrity, stage-appropriate evidence, and self-consistency of IPO subscription analysis logic. Do not archive new facts or make investment recommendations; route fact updates to archivist and investment conclusions to analyst. +--- + +# HK IPO Audit + +## Purpose + +Audit the evidence base and reasoning quality before a Hong Kong IPO analysis is trusted, compared with outcomes, or used to refine rules. + +This skill answers two questions: + +- Is the data complete and sufficient for the requested stage and conclusion? +- Is the analysis logic self-consistent, stage-correct, and supported by the available evidence? + +Use `archivist` first when required facts or source files are missing. Use `analyst` for subscription decisions, score interpretation, prediction cards, and rule changes. + +## Core Principles + +Separate three standards: + +- `integrity`: source files, hashes, repo-relative paths, database rows, and snapshots are internally consistent. +- `completeness`: the expected facts and sources for the analysis stage are present or explicitly marked as gaps. +- `sufficiency`: the available facts are strong enough to support the claims, scores, probabilities, and decision. + +Do not treat a filled field as sufficient evidence by itself. A conclusion is only audit-ready when the source, stage, assumption, and reasoning chain can be followed. + +## Stage Data Checklist + +Use the stage being audited to decide what must exist: + +- `T0_prospectus`: prospectus source, offer terms, timetable, sponsor, industry, business model, financial profile, valuation basis, cornerstone/lock-up facts when applicable, and explicit data gaps. +- `T1_allotment`: allotment-results source, final price, public subscription level, international placing signal when available, allocation outcome, clawback/reallocation facts, and demand-quality interpretation inputs. +- `T2_grey_market`: grey-market source, price move, turnover/liquidity context, and whether the signal is usable or noisy. +- `D1`, `D5`, `D20`, `D60`: post-listing prices, benchmark/market-window context, realized return, drawdown, liquidity, and comparison to the frozen prediction. + +For broad historical or cross-IPO work, also check that the sample definition, inclusion/exclusion rules, and date range are explicit. + +## Data Audit Workflow + +1. Inspect current repo state and recent commits before auditing. +2. Identify the ticker, report, rule version, stage, and data-as-of timestamp being audited. +3. Load the relevant archived facts from `data/hk_ipo.sqlite`, CSV snapshots, raw source paths, memo/report files, and rule files. +4. Check `source_refs` for repo-relative `local_path` values, existing files, and matching `file_sha256` values when present. +5. Compare database row counts with `data/snapshots/` exports for tables used by the audit. +6. Review `ticker_sync_state` and `sync_tasks` for the target ticker or sample. Treat open due tasks as possible blockers. +7. Mark each required stage fact as `present`, `missing`, `stale`, `estimated`, `inferred`, or `not_applicable`. +8. Decide whether remaining gaps are blocking or non-blocking for the specific conclusion being audited. + +## Logic Audit Workflow + +Check the analysis artifact, memo, report, or proposed conclusion for: + +- Stage leakage: later facts must not appear in earlier-stage conclusions. +- Source support: each material claim cites an archived source, structured fact, explicit assumption, or clearly labeled inference. +- Score arithmetic: subtotals and total score match the rule file. +- Rule alignment: the decision follows the stated rule thresholds, or any override is explicit and justified. +- Probability consistency: probabilities, expected return framing, and decision language do not contradict each other. +- Causal discipline: bull points, risks, and triggers explain why the IPO should behave differently from base rates. +- Comparable discipline: IPO history, industry comparisons, and peer cases use a defined sample rather than cherry-picked examples. +- Internal consistency: valuation, demand, market window, business quality, and exit plan point to a coherent conclusion or explicitly explain tension. +- Feedback readiness: predictions are frozen, measurable, and comparable with actual post-listing outcomes. + +## Output Standard + +Use this structure for audit reports or final audit summaries: + +```text +Audit status: pass | pass_with_gaps | fail +Target: +Stage: +Data as of: + +Data integrity: +- ... + +Data completeness and sufficiency: +- ... + +Analysis logic self-consistency: +- ... + +Blocking issues: +- ... + +Non-blocking gaps: +- ... + +Required fixes: +- ... +``` + +Severity labels: + +- `blocker`: conclusion should not be trusted until fixed. +- `major`: materially weakens confidence, but may be usable with explicit caveats. +- `minor`: clarity or traceability issue. + +## Boundaries + +Do not silently repair data during an audit. If source facts need to be added or corrected, report the gap and route the update to `archivist`. + +Do not rewrite an analyst conclusion during an audit. If the logic fails, explain why and route the revised judgment to `analyst`. + +Do not pass an audit just because the final recommendation sounds reasonable. Pass only when the data and reasoning chain are traceable, sufficient, and internally consistent. + +## Quality Checks + +Before finishing, confirm: + +- The audit target and stage are explicit. +- Data completeness and data sufficiency are judged separately. +- Missing facts are not converted into assumptions without labels. +- Later facts are not used to validate earlier predictions. +- Any pass/fail result names the evidence that supports it. +- Durable audit files use repo-relative paths.