data-analysis-quality-gate

name	data-analysis-quality-gate
description	Gate quantitative Mira conclusions by requiring reproducible data, formulas, calculation ledgers, or explicit downgrades when numbers drive judgment.

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。