kali20gakki/msAgent / skills/accuracy/loss-gnorm-diff-analyzer
loss-gnorm-diff-analyzer
Verified端到端分析两侧 msprobe PyTorch statistics 原始 dump 数据(dump.json + stack.json + construct.json)与精度问题现象(loss / grad norm / 输出不一致等),按「确定性预处理 → 多视角候选发现 → 汇总排序 → 分级定向验证 → 报告校验」流程识别可疑候选节点并构建到目标异常现象的因果链,交付主分析报告与结构化证据记录。当用户提供两侧 dump 目录并需要定位训练精度问题根因时使用。侧别判定:用户指定 target(待分析侧)/ golden(参考侧)优先;未指定时按目录名与数据内容推断(npu/gpu 等仅为软线索,不作硬性假设);不可靠时询问用户。
loss / gnorm 差异根因分析
0. 目标、交付物与执行边界
核心目标:在保证证据可追溯、候选判断可靠的前提下,尽快识别并输出可疑候选节点;只对影响候选判断或排序的关键问题进行深入验证。候选发现优先于完整根因叙事——发现阶段不要求每条线索形成完整因果链,深度验证按条件触发。
每次分析必须交付两项(写入用户指定的工作目录,二者缺一不可):
- 主分析报告
report.md:直接服务于根因判断,6 章(结论前置):①目标异常现象(表现、范围、证据);②数据与对齐质量;③候选节点总表(候选节点及可疑原因、关键证据、因果链摘要、反证/不确定性、置信度);④根因判断与置信程度(区分已验证根因、较强候选、待验证假设——先结论后支撑);⑤候选详析(逐候选关键证据、因果链逐环节状态、反证);⑥后续验证建议。因果链必须直接呈现在主报告中。结构契约见references/report-validation.md。 - 结构化证据记录
evidence.json:机器可读,可追溯主报告全部关键判断(schema 见references/evidence-and-state.md);承载全部机器可查结构——候选资格表行(candidates[].qualification,HC-C8 四格)、排除/降权项与速览锚点结案台账(exclusion_ledger)、覆盖缺口与剩余不确定性(open_questions),报告不再誊入这些结构。
独立详细审计材料不是默认交付物:仅当用户明确要求详细推理、深入追踪或独立审计材料时才额外生成,且应复用已有证据记录,不重复展示相同信息。
执行边界(硬性):
- 承诺可靠分析的范围是两侧均为
task == "statistics"的 PyTorch dump;data/md5 模式:说明原因并停止,不做不可靠分析。其他框架(如 MindSpore)的 dump 未适配——不承诺成功、不预设拒绝,脚本按实际结构解析,失败时按异常处理记录并停止。 - 不要求、不接受预生成的 compare CSV 或中间分析结果作为输入;解析、对齐、统计、差异计算由本 Skill 的脚本与流程完成。
- 不修改原始输入;所有产物写入独立工作目录。
- 全程在当前上下文内完成,不派生子 Agent;确需更多分析时自行组织任务顺序。
- 分析深度与证据完整性优先于篇幅精简:不得以裁剪承重证据、跳过验证环节、降级研判完整性为代价。
过程纪律(硬性)
开工第一步:python3 -I <skill目录>/scripts/make_evidence.py new --case <case> --out <工作目录>/evidence.json——建立 evidence.json 结构骨架。new 的输出含候选/证据条目形状契约与枚举表——条目照抄该形状填充,防首稿结构违规返工。开工同时执行 date '+%s' 记录分析起点(HC-C11⑦ 下班点计时起点,阶段二初始化 investigation.json 时写入 start_time)。以下按主题分组,全条硬性;任何情形下不得以裁剪承重证据换取速度或篇幅。
取数工具纪律:
- 原始 dump/stack/construct 抽查一律经
scripts/query.py(子命令 node/order/count/quad/diff/first/gain/align/survey/ranks/params/stack/construct/census,用法见脚本头注释)。引值输出自带侧别标签+节点+order+槽位路径+全精度数值+出处文件,可直接抄入 evidence_log——查询输出即回查(HC-B3 by construction),取数后不再单独做"引值回查"式重验。禁止为单点查询手写一次性 Python 片段或专用脚本;仅 query.py 无法表达的批量计算才写脚本,且合并为一次调用。 - 对齐返工预防:发现族计数漂移/调用号错位/命名变体时,先用
query.py align(汇总模式看逐族 |Δ|,--family看实例级 k↔k 配对与错位嫌疑行)再谈该族数值对比;两侧错位配对中的"差异"不得作数值证据。 - 按任务的子命令选择(不自写等价扫描脚本):批量分歧普查与单侧簇=
survey;多 rank 逐 rank 复核=ranks(必须按族模式定向执行,逐 rank Top-N 表有截断,不替代定向复核);参数槽全库普查=params;首分歧锚点=first(机械产出,含前置核查行;扫描口径为全部槽位,报告引用"首个/无更早"类断言时按实际扫描口径如实表述);链增益/制造-继承判别=gain(单侧反向捕获失真/透传伪影族按gain --direction backward族模式一次分类,禁止逐节点 diff 拼凑);承重族逐 rank 四元组明细=ranks --quads;窗口级量词闭合=census(--backward全 rank 反向发射枚举、--patterns全 rank 全槽普查,8 rank 案 8 次取数折叠为 1 次);结构试探=order --range/count --grep/node,不整读 dump.json。 - 承报级普查折叠(硬性,细则=hard-constraints.md HC-C11⑥):候选承报所需的「方向/形态批量普查」统一折叠执行——族级批量调用一次(
params/census --patterns/survey单次调用即覆盖全库参数槽/全 rank×全槽位/全窗口同名对,发现层覆盖面不折叠)+代表实例抽样确认(每族 ≤3 个代表实例;多 rank 布局抽 1-2 个 rank 或每 rank 1 个代表);禁止逐实例/逐 rank 枚举展开普查——全量逐实例核验(含ranks --quads全实例明细)属 L3 深闭合,仅按阶段四 L3 触发条件执行且限当前决策所需。普查一律用 query.py 子命令取数,禁止自建普查脚本、禁止逐槽循环;子命令确实无法表达的批量计算才允许写脚本,且合并为一次调用。ranks按族模式(单次调用出逐 rank 分桶汇总)不属折叠对象,HC-B8① 逐 rank 复核义务照常以此形态履行。 - 反向侧入口定位形态:梯度现象入口的定位优先"gnorm² 参数梯度分解(params)→
census --backward全 rank 发射界"一至两次取数收敛到入口链,禁止从首分歧节点逐 hop 上溯定位入口;系统性捕获伪影族按 HC-D5 族级单列+一次独立归约交叉排除处置,禁止逐实例甄别。 - 批量取证:
node多模式并集一次取多节点;同一数值全文只取一次、后续引证据 ID。控制调用次数与单次输出长度。
下班点纪律(硬性,细则=hard-constraints.md HC-C11⑦):
- 计时:以开工第一步的
date '+%s'为起点(阶段二写入 investigation.jsonstart_time);每次准备启动新的取数/普查/验证/深挖批次前自查墙钟(date '+%s'与 start_time 相减);上下文压缩恢复后计时连续(start_time 不重置)。 - 分档:两侧 dump 的 rank 目录总数 <4 = 轻案(盒 45 分钟)、≥4 = 重案(盒 60 分钟)——开工识别目录布局时判定并记入 investigation.json(
box字段)。 - 超盒即冻结取数:禁止任何新查询/普查/深验证,只准用在册材料(investigation.json 已登记证据/候选/台账)完成写作定稿与交付(report.md、evidence.json、report_check);冻结不是中止——交付义务与结构契约不减,未及完成的深验证/次候选补证如实记入 open_questions,禁止以冻结为由裁剪已承报证据或跳过结构自检。
上下文与恢复纪律(防上下文压缩后重复劳动与证据丢失):
- ① 取数输出即取即誊:批量输出的承重行取数后立即誊入 investigation.json / report.md 草稿对应小节(同一数值全文只取一次、后续引证据 ID),Top-N 长输出只截承重行(--top/head);预计 >30 行的取数(ranks --quads/survey/批量 diff 等)一律 stdout 重定向
analysis_out/q_<NN>.txt后按承重行 grep 读回(长输出移到盘上,不滞留上下文)。 - ② 参考文档一次分析只整读一遍,重开按节定位(先 grep -n 行号再定向读该节),不重复通读全文。
- ③ 恢复禁令:上下文被压缩后只读 investigation.json + report.md 未完成小节(按"(待填)"钉与各节标题定位)——禁止重跑 dump_analyzer.py、禁止重读 analysis_summary.md 全文、已落盘的已完成候选小节/排除项、任何参考文档全文(需要时按 ② 定向节读);恢复后新增取数仅限各候选 next_action 所需(逐条计入 checked_queries)。
- ④ 检查点粒度:investigation.json 在阶段三结束(候选池定型)、每次 L1/L2 验证完成、排序落盘后必须更新(candidates 状态+已验值+next_action)——保证压缩后单次恢复即可续作,不重新推导。恢复后先完成位序 1 候选的承报级定稿,再回头补排除线(排除线未结案不阻塞交付,如实留痕)。
落盘纪律:
- report.md 骨架=契约模板原文:直接拷贝 report-validation.md §1 末尾的骨架模板;dump_analyzer 预处理一完成、正式取数开始前即落盘——此后一切更新为就地增量改写,压缩恢复后只续写未完成小节。骨架落盘后立即跑一次 report_check.py(结构层应全绿)。骨架各节就地填充替换,禁止把骨架占位文本前置/追加在正式报告头部或尾部(report_check E9 检出即打回)。
- 每完成一个阶段/一个候选详析/一条排除结案立即写盘、消掉该节的"(待填)"钉(候选逐条誊写;排除项每结案一条立即誊入 evidence.json exclusion_ledger);较长批次(批量普查/逐 rank 复核)取数前,先把已有候选草稿写盘。禁止把正文落盘统一推迟到分析结束;禁止在单次响应内拼出全文再一次性写入。
- 落盘拦截预案:Write 工具对交付物被环境策略拦截时,不反复重试、不停手——直接改用 bash heredoc 一次写入同一目标路径,并在 run_notes 留痕。
验证深度分配(细则见 hard-constraints.md HC-C11):
- 全体候选以承报级为验证基线(位序第 1 亦然:锚点槽位直接核验+折叠普查+代表槽对照,所涉窗口级量词的 census 义务不减、按普查折叠口径执行);深验证(L3=充分闭合级:全量逐实例枚举、逐 rank 展开、深闭合证据)按位序轮候执行——基线完成后盒内余量按位序顺次分配升级(位序定顺序、盒定总量、不定资格,HC-C11②),完成当前决策所需验证后立即停止,盒冻结即终止轮候、未升级候选按[待验证]如实承报。保护承重证据可靠性的前置甄别(对齐/伪影排除、rank-1 census 义务)义务不减。
- 量级界与窗口级量词纪律、控制类操作数结构簇位序保护、初排校正、状态/实现型位序正典等排序细则以 hard-constraints.md HC-C10/HC-C11⑤/HC-C12 为权威。
输入识别:
- 目录布局不固定(
step/rank、step/proc、深层嵌套、直接给定均可),递归发现;proc<PID>不是 rank,按序号配对并说明。 - 两侧角色:用户指定优先;否则按目录名/数据内容推断(待分析侧常见
npu/target/tp,参考侧常见gpu/cpu/golden/bench/gp——名称不作硬性假设,以实际数据结构识别);不可靠时询问用户。 - 现象:先探索 case 目录实际存在的说明文件(
phenomenon.md、reference.md/references.md等,文件名不固定,逐案检查),结合用户 Prompt;只有 Prompt 描述时也要能分析。 - 多 step/rank:按 step 分组、rank 配对;无同标识 rank 且数量相等时按序号配对并告警;rank 数不等只配对公共部分并告警。
1. 常驻硬约束(总纲)
以下约束全程有效;每条在 references/hard-constraints.md 有唯一权威定义(含触发条件→执行程序→违反后果)。分析中触及对应触发条件时,必须先打开该文件核对完整程序再执行:
- HC-A 信息隔离:候选与证据必须由当前 case 数据推导;历史/外部结论不构成证据(可参考部分只能作待验证假设,引用前按当前数据独立验证);是否读取此类文件由部署方约定。
- HC-B 证据资格:显著性按相对量判定(≥1e-3 等);引值可回查、有侧别、有计数;全窗口否定断言须以分歧普查为据;多 rank 布局须逐 rank 复核承重族、一致断言注明 rank 有效域(HC-B8)。
- HC-C 候选资格与位序:现象载体不是候选;根因主语须有机制身份与生产者锚点;覆盖内未排除簇位序优先、最早显形锁定;量级不参与位序(含让位论证);未捕获算子的症状簇候选不得位居已验证生产者锚点候选之上;同侧同缺陷类须归一审查;差异源与放大器竞争位序时源优先(放大器只作传播环节并入,HC-C3⑧);候选间验证口径须一致(HC-C3⑨);让位仅限四情形;状态型内容差簇与实现型制造差簇并存的位序正典(HC-C12)。
- HC-D 验证义务:控制类操作数须消费点验证(前向+反向);伪影判定须算术闭合且闭合有效域=采证节点——禁止跨节点"同理"泛化(输入一致而输出分歧的节点上,分歧≥显著阈值的操作数槽=唯一在册差异源,其内容差假说须承报或以本节点证据判别;算子实现差机制须做同族兄弟实例一致性核查,HC-D2⑥⑦);单侧语义缺陷候选的公度性判定覆盖全部四统计量与取值模式(极值形态结构性不同即不可公度,Norm 接近不是公度证明);"生产链闭合"只闭合身份不闭合内容正确(HC-D2⑤);无窗口内生产者的注入形态槽位以捕获伪影为第一假说,形态对照不作跨簇位序依据(HC-D5);守恒检验分侧;就地写须写-消费三值核查;反查、栈帧、反证各有纪律。
- HC-E 表述纪律:区分 已证实/合理推断/待验证/已排除/未检查;置信度与证据强度分列;不把相关性表述为已证实的因果。
2. 总体流程
[阶段一] 确定性预处理(脚本 dump_analyzer.py)
→ analysis.json + analysis_summary.md(证据底座)
[阶段二] 建立事实底座(读摘要;量化现象锚点;登记速览锚点核查义务;初始化状态文件)
[阶段三] 多视角候选发现 → 候选池(investigation.json)
[阶段四] 汇总去重、统一排序(候选资格表)→ 分级定向验证(L1 全部 / L2 关键 / L3 按需)
[阶段五] 报告与证据落盘(增量落盘)→ 结构与一致性自检 → 交付
| 阶段 | 主要目标 | 不应做的事 |
|---|---|---|
| 一 确定性预处理 | 脚本一次性完成可复用的基础计算 | 手工重复计算统计量 |
| 二 事实底座 | 对齐质量、可比性、锚点、数据质量 | 直接通读原始 dump.json |
| 三 候选发现 | 多视角提高候选覆盖率 | 要求每条线索形成完整根因结论 |
| 四 汇总与验证 | 合并候选、统一排序、核实关键候选 | 对所有候选执行相同深度的验证 |
| 五 报告校验 | 输出有证据且前后一致 | 在报告中重复整段分析过程 |
3. 阶段一:确定性预处理
步骤 0(开工第一件事,先于一切分析动作):
python3 -I <skill目录>/scripts/make_evidence.py new \
--case <case> --out <工作目录>/evidence.json
(建立 evidence.json 结构骨架;骨架自带结构校验要求的全部必填顶层字段。)
python3 -I <skill目录>/scripts/dump_analyzer.py \
--target <目标侧目录> --golden <参考侧目录> --out <工作目录>/analysis_out
脚本完成:目录发现、解析标准化、精确匹配 + 受证据约束的命名变体增配、统计差异计算(含噪声地板、结构分歧、标量参数差异)、首分歧锚点、参数梯度与 gnorm 估计、未匹配分组、多 rank 汇总、分侧守恒检验、操作数身份对照、全窗口分歧普查。机制细节见 references/dump-analysis-mechanism.md。
输出:analysis.json(全量)+ analysis_summary.md(摘要;顶部有「⚡ 决定性锚点速览」与「⚠ 排除迁移禁令」警告,均由数据状态机械触发)。
不要直接通读原始 dump.json(可达数百 MB);抽查原始节点一律经 scripts/query.py(子命令与纪律见 §0 取数工具纪律;查询模式背景见 mechanism §3.6)。
停止条件:脚本成功运行且摘要生成。脚本失败/数据不可读:记录具体错误与影响,停止分析,不得伪造结果。
4. 阶段二:建立事实底座
通读 analysis_summary.md,提取五类事实(判定细则见 hard-constraints.md 与 alignment-playbook.md):
取证准备(本阶段必读):mechanism §3.6(张量同一性反查、四元组索引、批量溯源、栈帧定案)——此后所有原始 dump 抽查均按该模式经 query.py 执行。三类首分歧锚点(前向/反向首个显著数值分歧+结构首分歧)用 query.py first 一次机械产出(含前置核查行),与摘要值交叉核对。锚点落账必须转录分歧槽位名与该槽双侧四统计量(HC-B3③)——分歧槽为 input_args/parameters 类输入槽时,该节点不得登记为"输入一致而输出分歧"的制造节点,按 mechanism §3.9 程序六来源定性处置。****多 rank 布局(两侧 dump 路径含多个 rank 目录):analysis_summary.md 的逐 rank 章节与「跨 rank 共识族表」一并读——rank 专属族是候选线索(rank 集中显形本身是承重证据形态,HC-B8②);承重族的逐 rank 复核在阶段四 L2 用 query.py ranks 按族模式定向执行。
- 对齐质量:匹配率、族计数漂移、形状一致率可疑族、命名变体对、未匹配分组。漂移/可疑族内的"差异"先怀疑错配,不得直接当数值证据。
- 可比性:分片(
_rankN族、DTensor/placements、成倍调用数)使统计量不可比;跨侧同位 op 槽两侧张量内容性质签名不同类(值域极值形态,如精确 ±1.0 归一化输入量程 vs 参数/嵌入量程)时该槽为不同张量流,其 NRE 不可比、不得作为参数/配置效应数值证据(HC-D4);结构分歧(dtype/shape/标量参数/槽位缺失)单独归档。 - 关键锚点:前向首分歧、反向首分歧、结构首分歧、标量参数差异、参数梯度分解与 gnorm 估计(与用户报告的 gnorm/loss 数值交叉核对,评估捕获完整性)。
- 数据质量:NaN/Inf、null 统计、噪声占比、rank 配对告警。
- 速览锚点:分侧守恒(违反侧=缺陷侧第一指向)、高置信操作数身份不对称、梯度覆盖缺口、聚合输入单侧悬殊、反向内产生分歧、首分歧、Top 结构簇——均为关系型指纹,对统计失真鲁棒;命中 ≠ 定罪。每条登记为待核查项,报告前必须逐条消费点复核并留痕(作为证据,或明确标注"已核查、非因果"及理由);未核查的锚点不得默认按伪影处理。身份不对称/四元组反查类锚点结"非因果"前,若其四元组在同侧命中任何写语义 API(
__setitem__/copy_/fill_等)的槽位,必须先执行 HC-D4 写-消费三值核查——四元组命中出现在写节点槽位即触发,"生产链归属已判明"不构成跳过理由。
随后完成两件事:
- 现象锚点量化:明确要解释的现象(loss 从哪步开始偏、gnorm 差多少、谁大谁小),量化为比值/差值——后续每个候选都要能对着它解释。
- 初始化
investigation.json(schema 见 evidence-and-state.md):记录现象锚点、速览锚点核查清单、两侧路径、已确认的映射限制。
停止条件:五类事实提取完成、现象锚点已量化、状态文件已建立。
5. 阶段三:多视角候选发现
目标:召回可疑节点,不要求闭合因果链、不深挖。执行本阶段时必载 references/candidate-discovery.md(视角清单与检查方法)。至少覆盖:
- 速览高置信锚点(守恒违反、身份不对称、覆盖缺口、聚合悬殊、反向内分歧)
- 首分歧锚点(前向/反向/结构)
- 结构分歧簇(dtype/shape/标量参数/槽位缺失/控制类操作数)
- 参数梯度分解(gnorm² 差贡献排序)
- 未匹配节点(一侧独有计算)
- 张量同一性指纹(统计四元组反查)
- 就地写算子的写-消费断连
- Top 差异表(仅作线索,不作排序依据)
每个发现的候选登记进候选池(含发现渠道、初步证据、匹配质量、待验证问题);不在此阶段做完整根因论证。
候选数量纪律:由证据决定,不设下限、不凑固定数目——可以少于 5 个;不得为凑数加入缺乏证据的候选,也不得为省输出而遗漏强候选。承报候选上限 3 个(含并列双假设形态):超出时保留资格与位序最前的候选承报,其余以证据摘要记入 evidence.json exclusion_ledger 如实披露(同缺陷类合并为族级行,参考上限 5 行——誊写折叠细则见 evidence-and-state.md §5)——上限约束的是承报验证深度,不是发现覆盖。
停止条件:计划内独立发现视角均已执行;候选及来源证据已登记;没有新的有效发现路径。
6. 阶段四:汇总去重、统一排序与分级验证
执行本阶段时必载 references/causal-validation.md 与 references/hard-constraints.md(HC-C/HC-D 条目)。
- 合并去重与归一审查:同一机制/同一节点的重复候选合并;统一证据格式;保留不同发现路径的支持与反证。同侧多个单侧缺陷且机制指纹同属一缺陷类时,先完成 HC-C3⑦ 归一判定(同一底层缺陷的多显形,还是独立缺陷)并留痕,再进入排序。
- L1 快速筛查(全部候选):节点/数据真实存在、可定位;异常信号与原始证据一致;无明显无效数据、重复候选、证据误读;证据是否足以保留该候选进入排序。L1 只排除明显无效候选,不负责根因证明。
- 统一排序:按 HC-C 位序规则排序,落盘候选资格表(HC-C8 四格,逐格机械填写——“锚点验证”格合并承载正向生产者锚点、锚点节点级验证、同缺陷类归一判定三项;“背景级与未排除”格合并承载背景级与未排除(含 HC-C5 迁移留痕);资格结论格含机制覆盖内/外——逐候选存 evidence.json
candidates[].qualification,报告不誊入)。排序第 1 位产生规则:资格通过候选先经 HC-C3⑦ 归一审查,再两级分组——优先组=满足 HC-C2② 生产者锚点且锚点节点级验证=已验证的候选(验证对象须为候选主张的机制/差异制造环节;载体值复现与发射/放大/传播环节验证不入优先组——核验细则见 HC-C8①),组内 order 最小者居第 1;优先组为空时其余候选按 order 最小居第 1。排序同趟完成(不设独立复核阶段,HC-C3⑨):机制角色标注(差异源/放大器,mechanism §3.9 程序五)与源优先重排(HC-C3⑧)、HC-C5⑦ 迁移核对、输入槽状态差候选的来源定性与分维闭合(mechanism §3.9 程序六,含 HC-B3③ 自证证据 ID 义务)、身份不对称锚点的内容正确性核查(程序四/HC-D2⑤)、HC-C12 状态/实现型位序正典——各程序细则以 hard-constraints.md 与 mechanism §3.9 为权威,逐项在资格表对应格留痕。量级占比与"闭合更完整"论证禁止用于位序或让位(HC-C3③/HC-C2①)。 - L2 定向验证:对排序靠前、证据冲突或可能影响结论的候选——核对关键输入输出与上下游关系、验证异常沿计算路径传递、检查替代解释;只补当前判断缺失的关键证据。多 rank 布局时,承重候选族/首分歧族/结构分歧簇/守恒违反族的逐 rank 复核(
query.py ranks按族模式,HC-B8①)属 L2 必做项——单 rank 抽查不满足义务,任一 rank 上的复核证据须按 rank 分列入册。验证方法库见 causal-validation.md。验证深度按 §0 过程纪律的位序挂钩分配(HC-C11)。 - L3 深度验证:仅当(现有证据不足以判断关键候选 / 排序对复杂依赖高度敏感 / 存在重要反证需区分解释 / 硬约束明确要求)时触发,触发后按位序轮候执行(HC-C11②),启动前自查墙钟(HC-C11⑦ 下班点——超盒不得启动新批次);完成当前决策所需验证后立即停止,不默认展开全部候选。
验证结果(保留/降级/升级/重排、未决问题)即时写入 investigation.json。
停止条件:影响候选资格或排序的关键问题已有足够证据;继续检查预计不会改变候选状态、排序或结论;当前限制与未决问题已明确记录。
7. 阶段五:报告与证据落盘
执行本阶段时必载 references/report-validation.md 与 references/evidence-and-state.md。
增量落盘纪律(硬性):report.md 骨架应在预处理完成后即已落盘(若本阶段开始时骨架尚未落盘,此时立即补落)——直接拷贝 report-validation.md §1 末尾的骨架模板(含全部小节标题、总表列头、"(待填)"占位钉);骨架落盘后立即跑一次 report_check.py 预检。此后按 §0 落盘纪律逐节增量填充:每完成一个阶段/一个候选详析/一条排除结案立即写盘消钉;较长批次(批量普查/逐 rank 复核)取数前先把已有候选草稿写盘。
承报证据分级(硬性):候选承报(进入排序/双假设并列)的最小充分证据集=锚点槽位直接核验(双侧四统计量并列)+方向/形态批量普查一遍(按 §0 承报级普查折叠口径执行:族级一次+代表实例抽样)+代表槽对照——据此即可落盘候选小节;报告正文呈报配额:每候选「关键证据」参考上限 3 条承重项,深挖产出的其余证据全量落 evidence.json evidence_log(带 ID 可回查),正文以 ID 引用呈现(细则=report-validation.md §1 候选小节契约)——挖掘深度由位序轮候与盒决定,呈现密度由此统一;深闭合证据(全库逐槽定量拟合/指纹参数估计/全族逐实例画像等 L3 增强项)仅在必要时(阶段四 L3 触发条件)追加,完成当前决策所需验证后立即停止——承报级结论不因深证据未完成而阻塞交付,未做项如实记入 evidence.json open_questions。
交付物:
report.md:6 章结构(§0,结论前置——§4 根因判断在 §5 候选详析之前),候选总表 + 逐候选详析(因果链逐环节状态、反证、置信度);结构契约见 report-validation.md。evidence.json:结构化证据记录,全部必填字段齐备,承载候选资格表行(qualification)、排除/锚点结案台账(exclusion_ledger)、open_questions。 由scripts/make_evidence.py管理:开工new落骨架,阶段五从 investigation.json 提炼填入内容,交付前最后一步check(复跑 report_check 全部结构校验)。- 机械自检:
python3 -I <skill目录>/scripts/report_check.py <report.md> <evidence.json>——结构完整性检查(占位残留、小节齐备、候选数一致、evidence 必填字段、qualification 四格、exclusion_ledger 条目)。脚本检查不替代语义自检。
交付前自检(核心项,完整清单见 report-validation.md):
- 每个候选有可回查直接证据(节点名+槽位+数值,与 dump 可查值一致)?
- 速览锚点每条已留痕(evidence.json exclusion_ledger 或作为证据引用)?因果链逐环节标注状态、终点接到现象载体?
- 候选资格表四格已填齐(evidence.json qualification),报告呈报与结论主语同位序第 1(三级一致,HC-C8②③)?
- 位序与让位论据合规(无任何量级占比/"闭合更完整"类让位论据;未捕获算子症状簇未居已验证锚点候选之上;归一判定已留痕)?
- 排除迁移禁令:在册触发时已执行 HC-C5⑦ 迁移核对并留痕(压缩恢复后以 investigation.json 记录为准)?输入槽状态差候选按程序六定性留痕、无环境差下游影子承主语?
- 反证与不确定性已披露(报告正文反证条目 + evidence.json open_questions/unverified_links)?置信度与证据强度匹配、无反串?多 rank 布局承重族已逐 rank 复核留痕、"一致"类断言注明 rank 有效域(HC-B8)?
- report.md 无"(待填)"残留;evidence.json 可解析且必填字段(含 qualification/exclusion_ledger)齐全?
8. 参考文档加载索引(按需,禁止默认全读)
| 模块 | 内容 | 触发条件 |
|---|---|---|
references/hard-constraints.md | 全部硬约束唯一权威定义(HC-A…HC-E,触发条件→程序→后果) | 阶段四必载;任何阶段触及约束触发条件时 |
references/candidate-discovery.md | 发现视角、检查方法、漏检防范清单 | 阶段三必载 |
references/causal-validation.md | L1/L2/L3 验证方法库、消费点验证、算术闭合、守恒、gnorm/loss 专项 | 阶段四必载;反证/深挖时 |
references/evidence-and-state.md | evidence.json schema(含 qualification/exclusion_ledger)、investigation 状态、查询去重、上下文恢复 | 阶段二建池时;阶段五落盘前 |
references/report-validation.md | 报告结构契约(6 章、结论前置)、骨架模板、表述纪律、一致性检查 | 阶段五必载(骨架模板即取即用) |
references/dump-analysis-mechanism.md | dump 结构、字段语义、脚本计算机制、查询模式 | 阶段二必读 §3.6(含 ranks/params/first/gain 用法与 Top-N 截断限制——多 rank 布局必看);阶段四排序前读 §3.9;解析/统计量/查询疑问时 |
references/alignment-playbook.md | 对齐证据标准、错配模式、可比性门槛 | 出现匹配疑义时;对齐结论入因果链前 |
scripts/dump_analyzer.py | 确定性预处理 | 阶段一 |
scripts/query.py | 原始 dump/stack/construct 抽查、四元组反查(单点/批量/容差)、跨侧对齐(align)、分歧普查与单侧簇(survey)、首分歧扫描(first)、链增益剖面(gain)、多 rank 逐 rank 复核与集中性(ranks,--quads 给逐 rank 四元组明细)、参数槽全库普查与方向统计(params)、窗口级量词闭合(census)(引值自带出处,即查即回查) | 阶段二起的一切原始数据抽查;取数纪律见 §0 |
scripts/make_evidence.py | evidence.json 骨架/结构校验 | 开工第一步;交付前 check |
scripts/report_check.py | 报告结构机械自检 | 骨架落盘后;交付前 |
mechanism 文档表述如与本文件或 hard-constraints.md 有出入,以 hard-constraints.md 为权威。
9. 异常处理
- 预处理脚本失败/数据不可读:记录具体错误与影响,停止分析,不得伪造结果。
- task 模式不支持(data/md5):说明原因并停止。其他框架 dump 的处置见执行边界(未适配、不承诺、不预设拒绝)。
- 关键结论证据不足:保留不确定性如实报告,不强行裁定,不为完整性制造内容。
- 输入目录含历史产物(旧分析/中间结果):识别、排除并说明,不作为输入。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |