data-analysis-quality-gate

Data Analysis Quality Gate

这个 skill 用于在 Mira 研究中判断数量型结论是否需要可复算数据、工具计算或显式降级。

它不是一个独立数据分析插件，也不绑定 Data Analytics、Python、Spreadsheet 或外部 API。它的职责是把 LLM 从“直接给数字结论”约束为：

• 先提出数据需求
• 再判断是否必须计算
• 决定是否需要征求用户同意动用工具
• 记录公式、口径、来源和限制
• 对没有完成计算的数量型结论降级

Use When

当研究结论涉及以下任一内容时，必须进入本 gate，或明确写明 waived reason：

• 同比、环比、CAGR、run-rate、margin bridge
• peer comparison、peer ranking、相对估值、相对财务质量
• valuation implied expectation、base / bull / bear scenario math
• 市场规模、渗透率、份额、TAM / SAM / SOM
• 三表交叉校验、现金流质量、营运资本异常
• 宏观、商品、价格、库存、利率、就业或通胀时间序列
• 多来源数字冲突或口径不一致
• 任何会影响 thesis_impact、research_action、actionability_bridge 或 durable conclusion 的数量判断

Inputs

• research_object
• research_question
• market_scope
• time_boundary
• candidate_numeric_claims
• available_sources
• user_speed_preference 可选。若用户明确要求快看，可降低计算深度，但不能升级结论强度。
• tool_constraints 可选。说明是否允许本地脚本、CSV、Spreadsheet、联网、外部 API 或插件。

Gate Output

每次运行本 gate，至少输出：

• quant_dependency none / low / medium / high
• calculation_required yes / no
• data_requirement_brief_required yes / no
• calculation_ledger_required yes / no
• tool_consent_required yes / no
• allowed_without_tool yes / no
• downgrade_if_not_calculated none / calculation_gap / source_gap / watch_only / needs_refresh
• recommended_tool_path none / manual_formula_note / local_csv_script / spreadsheet / python / public_api / external_plugin
• calculation_depth none / formula_note / ledger_required / full_model_required
• refresh_condition

Calculation Depth

none

用于没有派生数量结论，或数量只作为非核心背景且已有可靠来源直接披露的场景。

输出要求：

• 记录 quant_dependency: none 或 low
• 不生成 calculation artifact

formula_note

用于简单、低行数、可口头复核的计算，例如一个同比、一个 run-rate sanity check、简单估值倍数或明确公式的市场隐含值。

输出要求：

• 在正文或 source note 写明公式、输入来源、期间和限制
• evidence log 可记录 claim_type=derived_calculation
• 不默认生成 calculation-ledger.csv

ledger_required

用于会影响 thesis impact、research action、actionability bridge、peer ranking、scenario table 或多来源冲突处理的计算。

输出要求：

• 使用 templates/calculation-ledger.csv
• 记录输入来源、公式、结果、交叉校验、限制和对应 evidence ref
• 若缺失数据阻断结论，输出 data-requirement-brief.md 或 source_gap

full_model_required

用于多变量估值、三表联动、复杂 peer set、时间序列、宏观/商品历史比较、TAM / SAM / SOM 或需要用户复用的 spreadsheet / script。

输出要求：

• 先明确工具和数据权限
• 生成可复算 model、script、spreadsheet 或 notebook，并把摘要写回 calculation ledger
• 如果用户选择不做，相关结论只能是 watch_only、needs_refresh、source_gap 或 calculation_gap

Data Requirement Brief

如果 data_requirement_brief_required = yes，或 calculation_depth 为 ledger_required / full_model_required 且关键输入缺失，使用：

• templates/data-requirement-brief.md

brief 必须回答：

• 要回答的研究问题
• 需要哪些变量
• 指标公式或计算方法
• 口径、单位、币种和期间
• 对比对象或 peer set
• 来源优先级
• 缺失数据如何处理
• 哪些缺失会导致结论降级

Calculation Ledger

如果 calculation_ledger_required = yes，或 calculation_depth 为 ledger_required / full_model_required，使用：

• templates/calculation-ledger.csv

ledger 必须记录：

• 计算 ID
• 研究对象和问题
• 指标、公式、期间、单位
• 输入来源
• 结果
• 交叉校验
• 使用工具
• 验证状态
• 限制
• 对应 evidence log ref

Tool Consent Rules

默认不因为本 gate 自动引入插件或联网。

可以直接使用工具的场景：

• 用户已经提供 CSV、表格或可读数据
• 只需要小规模本地计算
• 不需要联网、下载数据、外部 API 或额外插件
• 输出可用 formula note 或 calculation ledger 复核

必须先征求用户意见的场景：

• 需要联网抓取或下载数据
• 需要使用外部 API、付费数据源或登录态
• 需要引入插件或新依赖
• 需要生成较大的 spreadsheet、dashboard 或图表包
• 计算会明显改变任务范围或耗时

建议话术：

这个判断依赖可复算计算。仅靠文本阅读容易出错。建议进入 calculation gate，用本地 CSV/Python/Spreadsheet 生成 calculation ledger；是否继续？

Downgrade Rules

如果数量型结论没有完成必要计算：

• 不得写成 durable conclusion。
• 不得作为 research_action 或 actionability_bridge 的唯一依据。
• 必须标记 calculation_gap 或 source_gap。
• 如果用户要求快看，可写 calculation_waived_by_speed，但置信度不得高于 low 或 medium。
• 如果估值锚、共识代理或 peer rank 缺失，actionability 默认降级为 watch_only、needs_refresh 或 no_action。

Evidence Log Relationship

evidence-log.csv 记录 claim 来源和性质。

calculation-ledger.csv 记录公式、口径和复算路径。

派生计算结论必须同时满足：

• evidence log 中有 claim_type=derived_calculation 或 explicit source note
• upstream_sources 指向 L1-L5 来源
• calculation ledger 或 formula note 记录可复算步骤

Output Boundaries

• 不要把 market pricing 写成基本面验证。
• 不要把 company guidance 写成已兑现事实。
• 不要把 LLM 心算结果写成高置信结论。
• 不要因为工具输出了数字就自动提高投资结论强度。
• 工具只提高计算可复核性，不替代来源质量和 thesis judgment。