results-reporting

用途

results-reporting 用于把用户自有的指标和分析产物，转化为一份陌生人也能信任的体育分析结果报告。其核心要求是：每一项量化结论都必须可追溯到数据、验证和复现证据；观察结果与解释分开；预测性能与解释或因果分开。

该技能适用于笔记本总结、研究笔记、README 结果章节、内部报告、公开文章，以及分析完成后的最终回答。如果还没有指标或基线，应先停止并产出评估产物。对于冻结的可复用模型应使用 model-card，视觉诚实性审查使用 anti-slop-analytics，当主要问题是错误或预测为何发生时使用 model-interpretation。

主要能力

• 证据清单：收集建模章程或确切问题、来源清单、数据快照、模式、过滤器和样本计数；目标、决策时间、特征定义和泄漏结果；基线与候选配置；折分配、预测、聚合与折级指标；校准、切片、敏感性和不确定性输出；图表及其源表；环境、种子、代码版本和确切复现命令。缺失证据应标注为缺失并收窄结论，而不是推断。
• 必需结构：执行结果（一句有界句子，含主指标与基线）、问题、数据、方法、验证、结果、解释、局限与失败检查、图表与表格、复现。
• 指标呈现规则：按目标或主张选择主指标，例如胜率概率用 log-loss 或 Brier，概率可靠性用校准曲线/表与误差，二分类用适当评分且准确率次要，边际或连续结果用 MAE 或 RMSE，计数用偏差或适当评分，排名用样本外相关或效用，解释性效应用估计与区间，模拟用分布、分位数与校准。始终说明样本量、评估周期、折聚合方式以及哪个方向更好；不得仅以准确率作为概率质量的唯一证据。
• 结果表模式：基线与候选相邻，列出折/赛季、n、基线、候选、候选减基线、是否更好；并定义汇总方式（未加权折均值、事件加权均值或合并评分）。
• 解释阶梯：只能推进到证据允许的程度，从观察、比较、稳定性、泛化、操作价值到因果解释，不得从第 1 级跳到第 5 或 6 级。
• 体育特定报告陷阱：团队-比赛粒度下两行可能代表一场比赛，需同时报告行数和唯一比赛数；互补两行面板的总体胜率接近 0.5；区分常规赛、季后赛、中立场地、加时和平局；说明指标是否跨联赛、赛事、赛季、球队或球员合并以及权重是否反映暴露；报告赛季初状态或评级的冷启动行为；披露规则、赛程、阵容、追踪和来源定义变化；球员排行榜需要机会阈值和幸存者/选择注意事项；概率报告若未检查校准则不完整。

使用方式

技能附带一个独立的 JSON 到 Markdown 渲染器，接受如下最小 JSON 结构（字段可扩展）：

{
  "title": "Home-form win model",
  "analysis_type": "predictive",
  "question": "Does prior form improve held-out win probabilities?",
  "data": {"source": "immutable schedule snapshot", "sport": "NFL", "grain": "team-game", "period": "2021-2023 regular seasons", "n": 1632},
  "methods": {"target": "won", "decision_time": "kickoff", "baseline": "constant rate", "candidate": "logistic"},
  "validation": {"design": "season walk-forward", "primary_metric": "log_loss", "metric_direction": "lower", "comparison_population": "identical held-out game rows"},
  "results": {"baseline_log_loss": 0.693, "candidate_log_loss": 0.681},
  "interpretation": "The candidate improved held-out log-loss modestly.",
  "limits": ["Public injury information was not included."],
  "reproduction": {
    "artifacts": ["data/metrics.json", "data/predictions.csv"],
    "command": "python run_analysis.py --config analysis.json"
  }
}

渲染器要求显式提供 analysis_type、source、sport、grain、period、正 n、非空结果、局限和复现产物指针。预测和排名模式还要求基线、候选、决策/截至时间、验证设计、主指标与方向，以及定义比较总体的声明。描述性、解释性、因果和模拟报告使用模式特定的方法字段，不强制套用预测基线或前向验证模式。复现元数据可包含用户实际拥有的内容，绝不虚构命令。

辅助命令：

python <path-to-results-reporting>/scripts/render_results_report.py \
  --json data/results.json \
  --out data/results_report.md

渲染后需编辑并验证草稿。有效模式并不能证明指标可比、解释合理或报告完整。

适用场景

• 体育分析或建模完成后的结果报告撰写。
• 需要将指标、基线、验证、图表和复现证据组织成可审计报告的场景。
• 需要区分预测性能与因果解释、观察与解释的报告。

限制

• 若尚无指标或基线，不应使用本技能，而应先产出评估产物。
• 不得报告没有锁定基线的候选指标；不得只报告最佳折、分段、超参数搜索或种子；不得比较不同总体上的指标而不披露；不得仅凭区分度指标称模型已校准；不得省略负面、零、不稳定或失败结果；不得将训练拟合呈现为留出或前向性能；不得混合运动项目或粒度而不加明确标签和聚合规则；不得制造复现命令、包版本或审计状态；不得从观察性预测暗示因果解释。若未检查泄漏或校准，需在主结果附近说明。
• 反模式包括：无方法或来源的排行榜截图；无基线的“模型很好”；无折表的平均指标；结果前冗长的方法前言；悄悄丢弃失败的赛季；无效用却将微小指标改进报告为经济上有意义；与附表不一致的圆整文字数字；用图表标题夸大谨慎正文所承认的内容。

输出契约

返回执行结果、问题、数据、方法、验证、基线与候选结果、折/切片证据、解释、局限、图表清单、产物清单和复现说明。报告长度应与受众匹配，但不丢弃证据链。

资源

• references/templates.md — 在简洁与完整叙述形式之间选择时阅读。
• references/writeup_checklist.md — 最终证据与诚实性检查时阅读。
• scripts/render_results_report.py — 经过验证的独立 JSON 到 Markdown 渲染器。