fithia2/dev/finished/phase3_deliverables/implementation_plan.md

Phase 3 구현 계획

1. 선행조건

• Phase 0 승인 완료
• Phase 1 저장소/DB/서비스 계약 구현 완료
• Phase 2 ingestion 파이프라인이 raw/staging/structured 데이터를 안정적으로 제공
• parser_event.schema.json 사용 가능

2. 구현 단위

Workstream A. Parser foundation

목표:

• 문서 선택기
• 텍스트 normalizer
• rule parser skeleton
• span mapper

완료 조건:

• 8-K + EX-99.1 문서를 정규화 텍스트로 만들 수 있다.

Workstream B. LLM enrichment

목표:

• llm client wrapper
• schema validation
• prompt registry
• cache layer
• raw response logging

완료 조건:

• 동일 문서 재호출 없이 schema-valid 응답을 저장할 수 있다.

Workstream C. Canonicalization

목표:

• rule + llm 병합
• provenance 저장
• disagreement 탐지
• review queue 생성

완료 조건:

• canonical event record를 event_records에 적재할 수 있다.

Workstream D. Feature builder

목표:

• event/document/numeric/market/regime/attention feature 계산
• as_of_ts / available_ts 저장
• leakage validator

완료 조건:

• event_feature_records 생성 가능

Workstream E. Labeling

목표:

• reaction date 계산
• entry convention별 label 생성
• MFE/MAE 계산
• snapshot export

완료 조건:

• train/valid/test parquet snapshot 생성 가능

Workstream F. QA and review

목표:

• gold set loader
• parser evaluator
• review queue tooling
• weekly quality report skeleton

완료 조건:

• 골드셋 회귀 검증과 review queue triage 가능

3. 권장 작업 순서

1. document selector + normalizer 구현
2. rule parser 기본 필드 구현
3. line/span reference 구현
4. llm wrapper + schema validator 구현
5. canonical merge 구현
6. event feature builder 구현
7. market/regime feature join 구현
8. labeler 구현
9. dataset snapshot exporter 구현
10. review queue / gold set evaluator 구현

4. 금지사항

• 규칙/LLM 출력 형식을 중간에 자주 바꾸기
• evidence 없이 핵심 필드 저장
• as_of_ts 없는 feature 저장
• future leakage 검사 없이 label 생성
• raw response를 버리고 normalized output만 저장

5. Task slicing 예시

Task 1

apps/parser/document_selector.py

• 입력: filing_documents
• 출력: parser_jobs
• 테스트: 8-K with EX-99.1 prioritization

Task 2

libs/common/text_normalizer.py

• HTML to text
• disclaimer strip option
• hash generation

Task 3

apps/parser/rule_parser.py

• guidance keywords
• one-off keywords
• demand/pricing/margin keywords

Task 4

libs/llm/client.py

• invoke
• cache
• retry
• raw response persistence

Task 5

apps/parser/canonicalize.py

• merge policy
• disagreement flags
• review queue write

Task 6

apps/feature_builder/build_event_features.py

• parser-derived features
• availability metadata

Task 7

apps/feature_builder/build_market_features.py

• reaction day price/volume features
• regime join

Task 8

apps/labeler/generate_labels.py

• reaction_date
• entry_date
• 1D/3D/5D labels
• MFE/MAE

Task 9

apps/qa/evaluate_gold_set.py

• parser metrics
• regression compare

6. 완료 정의

Phase 3 완료는 아래를 모두 만족해야 합니다.

• parser output schema validation 100%
• gold set core metrics가 baseline 이상
• feature leakage tests pass
• snapshot export reproducible
• review queue 생성/소진 흐름 작동
• operator가 파싱 실패 원인과 review 대상을 추적 가능