Improvement Discriminator

Multi-signal scoring engine: heuristic rules + evaluator rubrics + LLM-as-Judge + multi-reviewer blind panel.

When to Use

• 对改进候选打分和排序——产出 ranked list 供 executor 按优先级执行
• 运行多审阅者盲审（CONSENSUS/VERIFIED/DISPUTED 认知标签），降低单人偏见
• 用 LLM-as-Judge 评估 4 个语义维度（clarity, specificity, consistency, safety）
• 组合 --panel + --llm-judge 获得最全面的评估（两者不互斥）
• 调试为什么所有候选都被标为 hold——通常是 riskpenalty 过高或缺少 sourcerefs
• 在 orchestrator pipeline 第 2 阶段自动调用
• 需要可解释的评分明细时（每个维度独立打分，附 judge_notes）
• 需要对比多轮改进的候选质量趋势时

When NOT to Use

• 评估 skill 目录结构 → use improvement-learner（learner 做 6 维结构分析，discriminator 做语义评分）
• keep/revert/reject 决策 → use improvement-gate（discriminator 只打分不做决策）
• 执行文件变更 → use improvement-executor（discriminator 不修改任何文件）
• 生成改进候选 → use improvement-generator
• 候选数量为 0 时调用会报错，应先确认 generator 产出了候选
• 不要用 discriminator 做回归检测——回归检测是 gate 的 RegressionGate 层负责
• 不要把 discriminator 的 accept 当做最终决策——它只是评分建议，最终 keep/reject 由 gate 决定
• 不要在没有 candidates.json 的情况下调用——输入必须是 generator 产出的标准格式

Scoring Modes

4 种模式可以独立或组合使用，从纯启发式到全信号融合逐步增加评估深度。 默认模式（Heuristic only）零成本、确定性，适合快速过滤。 加入 evaluator evidence 后，利用 task_suite 执行结果作为评分依据，更贴近实际效果。 加入 LLM Judge 后引入语义理解，但会消耗 token 且结果有随机性。 Panel 模式引入多视角盲审，捕捉单一审阅者无法发现的偏差。

Why Panel Review Matters

Tradeoff: single reviewer speed vs. multi-reviewer accuracy.

之所以引入 panel 盲审而非依赖单一评分器，原因是：

1. Single reviewer bias is real — 一个 "structural" 审阅者倾向于高分（偏好结构完整的候选），而 "conservative" 审阅者倾向于低分（偏好最小变更）。单一审阅者会系统性地偏向某类候选。
2. CONSENSUS/VERIFIED/DISPUTED 三态标签捕捉了审阅者之间的分歧程度。DISPUTED 意味着候选质量有争议，gate 层会据此做更谨慎的决策。
3. LLM-as-Judge 弥补启发式盲区 — 启发式规则无法判断"这段改写是否真的更清晰"，LLM judge 的 clarity/specificity 维度填补了这个空白。

问题: 为什么不直接用 LLM judge 替代所有启发式规则？Because LLM judge 有 token 成本（每个候选约 500-1000 tokens）且存在随机性。启发式规则是确定性的、零成本的，适合作为第一层过滤。组合使用时，启发式占 60% 权重、LLM 占 40%，既保证了稳定性又引入了语义理解。

当 panel 结果全是 hold 时，通常是以下原因之一：

• 候选缺少 sourcerefs（引用来源），导致 sourceref_bonus = 0
• risklevel 被标为 high，导致 riskpenalty 过大
• LLM judge 的 safety 维度给了低分（候选可能引入了不安全的模式）

<example> 正确用法: 多审阅者盲审 + LLM 语义打分 $ python3 scripts/score.py --input candidates.json --panel --llm-judge mock --output scored.json → 输出包含: panelreviews: [{reviewer: "structural", score: 7.5}, {reviewer: "conservative", score: 5.0}] cognitivelabel: "VERIFIED" (2人同意) llm_verdict: {score: 0.78, decision: "conditional", dimensions: {clarity: 0.85, ...}} </example>

<anti-example> 常见误解: --panel 和 --llm-judge 互斥 → 错！两者可以同时使用。每个审阅者独立调用 LLM judge，得到独立的语义分数。 → 如果只用 --panel 不加 --llm-judge，panel 只做启发式评分，不做语义评估。 </anti-example>

CLI

score.py 是核心入口，接收 candidates.json，输出 scored.json。 所有模式共用同一个入口，通过 flag 组合控制评分深度。 --llm-judge 支持 3 种 provider: claude（最准）、openai、mock（测试用，零成本）。 --panel 会自动创建 structural 和 conservative 两个独立审阅者。 输出的 scored.json 可直接传给 executor 或 gate 消费。 使用 --verbose 可查看每个审阅者的详细评分过程和 judge_notes。

# Basic scoring (heuristic only, fastest)
python3 scripts/score.py --input candidates.json --output scored.json

# Full pipeline: panel + LLM judge
python3 scripts/score.py \
  --input candidates.json --panel --llm-judge mock --output scored.json

Panel-only mode (no LLM, lower cost):

# Panel blind review without LLM judge — heuristic scoring only
python3 scripts/score.py \
  --input candidates.json \
  --panel \
  --output scored.json

LLM-judge-only mode (no panel, single reviewer):

# Single reviewer + LLM semantic evaluation
python3 scripts/score.py \
  --input candidates.json \
  --llm-judge claude \
  --use-evaluator-evidence \
  --output scored.json

Output Artifacts

输出中的 cognitive_label 含义：

• CONSENSUS — 所有审阅者评分方向一致（全部 accept 或全部 reject），高置信度
• VERIFIED — 多数审阅者同意，少数有保留意见，中等置信度
• DISPUTED — 审阅者之间存在根本分歧（一人 accept 一人 reject），需要 gate 层额外审慎处理

decision 字段的三态语义：accept 直接通过，conditional 需要满足附加条件（记录在 judge_notes），reject 直接拒绝。

Related Skills

• improvement-generator: Produces the candidates that this skill scores — discriminator 的输入来自 generator
• improvement-gate: Consumes scored candidates for keep/revert/reject — gate 依赖 cognitive_label 做 ReviewGate 判定
• improvement-learner: Structural evaluation (6-dim); discriminator focuses on semantic — 两者互补，learner 看结构，discriminator 看内容
• benchmark-store: Frozen benchmarks for regression checking — 提供历史基线数据
• improvement-executor: Applies top-ranked candidates — executor 按 discriminator 的排序依次执行
• improvement-evaluator: Task-based evaluation — evaluator 的 pass_rate 可作为 --use-evaluator-evidence 的数据源
• improvement-orchestrator: Calls discriminator as stage 2 — 全流程中 discriminator 在 generator 之后、evaluator 之前

Pipeline 中的数据流: generator → discriminator → evaluator → executor → gate