69 lines
4.7 KiB
Markdown
69 lines
4.7 KiB
Markdown
# Quant Investment Engine - Analysis & Reporting Guide
|
|
|
|
This document is the authoritative guide for LLMs analyzing the packaged data feed and generating operational/investment reports. It defines the mapping of data files, metric interpretations, and hard reporting rules.
|
|
|
|
---
|
|
|
|
## Completion Harness
|
|
|
|
작업 완료는 아래 4가지가 모두 있을 때만 인정한다.
|
|
|
|
- `YAML` 증빙
|
|
- `코드` 증빙
|
|
- `데이터 실체` 증빙
|
|
- `검증 증빙`
|
|
|
|
하나라도 없으면 완료로 보지 않는다.
|
|
|
|
For this guide, the same rule applies: YAML evidence, code evidence, data artifact evidence, and validation evidence must all be present before marking work complete.
|
|
|
|
---
|
|
|
|
## 1. Directory & File Mapping
|
|
|
|
When the zip package is unpacked, the directory structure is organized as follows. Use these files to verify numbers and trace decisions:
|
|
|
|
* **`AGENTS.md`**: The overall constitution and index of governance rules.
|
|
* **`README.md`**: Project setup and script description.
|
|
* **`REPORT_GUIDE.md`**: This guideline document.
|
|
* **`GatherTradingData.json`**: The raw source data from GAS containing market history, macro factors, and account snapshots.
|
|
* **`spec/`**: Contains the source of truth for investment formulas, exit policies, scoring rules, and contract specifications.
|
|
* `spec/13_formula_registry.yaml`: Authority for all formula IDs, inputs, and thresholds.
|
|
* `spec/12_field_dictionary.yaml`: Definition of keys and expected value shapes.
|
|
* `spec/30_completion_criteria_contract.yaml`: Definition of completion and quality gates.
|
|
* **`governance/rules/`**: Detailed policy constraints.
|
|
* `governance/rules/00_core_locks.yaml`: Strict rules preventing value invention.
|
|
* `governance/rules/02_portfolio_policy.yaml`: Cash floor and rebalance rules.
|
|
* `governance/rules/04_reporting_contract.yaml`: Narrative constraints and provenance requirements.
|
|
* **`Temp/`**: Active pipeline outputs and decision packets.
|
|
* `Temp/final_decision_packet_active.json`: The authoritative source of execution verdicts, quantities, and prices.
|
|
* `Temp/horizon_rebalance_plan_v1.json`: Output of the portfolio rebalance model containing limit violations and waterfall trim plans.
|
|
* `Temp/factor_lifecycle_completeness_v1.json`: Match result between factor registry specs and actual data availability.
|
|
* `Temp/number_provenance_ledger_v4.json`: Key-value registry mapping every output number to its exact execution step/file source.
|
|
|
|
---
|
|
|
|
## 2. Key Data Interpretations
|
|
|
|
### A. Horizon Rebalance Plan (`horizon_rebalance_plan_v1.json`)
|
|
* **Excess Pct & Reduction**: Calculated as `current_pct` minus `cap_pct`. If positive, a reduction is required.
|
|
* **Trim Action Waterfall**:
|
|
1. `FULL_TRIM`: Ordered for positions with `verdict: SELL` first, sorted by lowest effective confidence and highest weight.
|
|
2. `PARTIAL_TRIM`: Applied to other positions if `FULL_TRIM` on sell candidates cannot cover the required reduction.
|
|
3. `BLOCKED`: Positions that cannot be sold due to trading locks (e.g. min holding periods) are marked as blocked and shadow-recorded.
|
|
* **Gate Status**: If the estimated post-plan exposure still exceeds the cap (due to physical holding constraints), the gate is correctly reported as `FAIL`.
|
|
|
|
### B. Factor Lifecycle Completeness (`factor_lifecycle_completeness_v1.json`)
|
|
* **`violations`**: Array of factors that are marked as `shadow` or `active` in specifications but lack required data inputs in reality. Must be empty (`[]`) for `gate: PASS`.
|
|
* **`shadow_ready_candidates`**: List of draft factors whose required fields are 100% present in the live data feed (`coverage_pct: 100.0`), making them eligible for promotion to shadow.
|
|
|
|
---
|
|
|
|
## 3. Strict Reporting Rules (No-Hallucination Constraints)
|
|
|
|
1. **Explicit Provenance**: Every number presented in the narrative report must carry an explicit origin tag matching `number_provenance_ledger_v4.json` or its respective source file (e.g., `[source: final_decision_packet_active.json:total_asset_krw]`).
|
|
2. **No Value Invention**: Never calculate, average, or extrapolate prices, target/stop levels, or score metrics inside the narrative. Use copy-only rendering from the JSON packets.
|
|
3. **Portfolio Health First**: The top section of any report must clearly state the overall portfolio health, active gate statuses (PASS/FAIL), and any blocked assets or critical warnings.
|
|
4. **Transparency of Blocked Positions**: Even if a stock or order is blocked, all computed parameters (stop price, target price, priority scores) must remain visible in the shadow ledger. Do not omit or hide data for blocked candidates.
|
|
5. **No Narrative Mitigation**: Do not soften hard gate failures (e.g., "The limit was slightly exceeded, but it is acceptable..."). A gate failure must be described as a failure.
|