QuantEngineByItz/REPORT_GUIDE.md

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.

---

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.