hk-ipo/.agents/skills/hk-ipo-audit/SKILL.md

---
name: hk-ipo-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 hk-ipo-archivist and investment
  conclusions to hk-ipo-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 `hk-ipo-archivist` first when required facts or source files are missing. Use `hk-ipo-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.

Treat derived evidence as first-class audit material, not optional convenience. If an archived raw source is expected to generate a reusable derived artifact, the audit must reconcile the raw source, derived artifact, manifest row, and hashes.

## 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.

## Derived Evidence Checklist

For broad historical audits and any analysis-readiness audit:

- Every archived PDF in `source_refs` must have one row in `data/snapshots/extracted_text_manifest.csv`.
- Every extracted-text manifest row must point back to an existing PDF `source_id`.
- `pdf_sha256` in the manifest must match `source_refs.file_sha256`.
- `text_local_path` must be repo-relative, must exist, and must match `text_sha256`.
- Manifest extraction status must be reviewed. `error`, missing text, missing manifest rows, orphan manifest rows, hash mismatches, or non-repo-relative paths are `blocker` issues for historical-data completeness.
- HKEX `.htm`/`.html` notices and Yahoo JSON files are raw text-like evidence under `data/raw/`; do not require `data/extracted_text/` rows for them.

## 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. Reconcile derived artifacts, especially PDF extracted text, against their manifests and source hashes.
6. Compare database row counts with `data/snapshots/` exports for tables used by the audit.
7. Review `ticker_sync_state` and `sync_tasks` for the target ticker or sample. Treat open due tasks as possible blockers.
8. Mark each required stage fact as `present`, `missing`, `stale`, `estimated`, `inferred`, or `not_applicable`.
9. 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 `hk-ipo-archivist`.

Do not rewrite an analyst conclusion during an audit. If the logic fails, explain why and route the revised judgment to `hk-ipo-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.
- PDF source references are reconciled to extracted text and manifest hashes when auditing historical or analysis-ready data.
- 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.