hard-cheese

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/hard-cheese

The gate mitigates epistemic debt — the failure mode where AI-scaffolded code passes review, type-checks, and tests green while the author cannot explain it to a reviewer.

该关卡用于缓解认知债务（epistemic debt）——即AI辅助生成的代码通过了评审、类型检查和测试，但作者却无法向评审者解释其逻辑的失效模式。

Inputs

输入参数

text

/hard-cheese [<slug>] [--socratic-cap N=3] [--passing-score N=3] [--no-judge]

Arguments:

```
<slug>
```
— optional. Identifies the artifact at
```
.cheese/hard-cheese/<slug>.md
```
. When omitted, fall back to the git short SHA of
```
HEAD
```
. An explicit slug always wins.
```
--socratic-cap N
```
— max retry attempts before the gate marks the artifact
```
FAILED
```
and exits non-zero. Default
```
3
```
. Vibecheck does not cap; easy-cheese does to avoid infinite loops.
```
--passing-score N
```
— minimum SOLO score that counts as PASS. Valid range
```
1..5
```
; default
```
3
```
(Multistructural-or-higher). A previous PASS below the requested threshold is treated as stale and must be re-judged.
```
--no-judge
```
— log-only mode. Capture the user's explanation, write the artifact with
```
status: LOGGED
```
, skip the judge sub-agent spawn. Mirrors vibecheck's optional JSONL telemetry mode.

text

/hard-cheese [<slug>] [--socratic-cap N=3] [--passing-score N=3] [--no-judge]

参数说明：

```
<slug>
```
— 可选参数。用于标识
```
.cheese/hard-cheese/<slug>.md
```
路径下的产物。若未指定，默认使用
```
HEAD
```
的git短SHA值。显式指定的slug优先级更高。
```
--socratic-cap N
```
— 关卡判定为
```
FAILED
```
并返回非零退出码前的最大重试次数。默认值为
```
3
```
。普通认知检查（vibecheck）无次数限制；本工具设置限制是为了避免无限循环。
```
--passing-score N
```
— 判定为PASS的最低SOLO分数。有效范围为
```
1..5
```
；默认值为
```
3
```
（即达到多结构级别及以上）。若之前的PASS分数低于当前设定的阈值，则判定为过期，需重新评审。
```
--no-judge
```
— 仅日志模式。捕获用户的解释内容，生成状态为
```
LOGGED
```
的产物，跳过评判子Agent的启动。与vibecheck的可选JSONL遥测模式一致。

Invocation modes

调用模式

Mode	How it fires	Where the gate sits
standalone	User runs `/hard-cheese <slug>` directly before opening a pull request.	Outside the pipeline. No upstream skill required.
propagated	`/plate --hard` invokes `/hard-cheese <slug>` after its final writing gate and before publication.	At the verified-artifacts → share-for-review boundary.

--hard

propagates through

/cheese → /mold → /cook → /press → /age → /cure → /plate

. Upstream skills pass the flag;

/plate

is the only pipeline skill that invokes

/hard-cheese

Portability reference:

../cheese/references/harness-portability.md

. It covers helper resolution, sub-agent dispatch, GitHub operations, and handoff transitions; prefer the bundled or repo-local helper first, and treat

${CLAUDE_SKILL_DIR}

as optional host-provided fallback. The handoff blocks below are the portable contract; slash commands are host renderings, not the control model.

模式	触发方式	关卡位置
独立调用	用户在创建拉取请求（PR）前直接运行 `/hard-cheese <slug>`	流水线外部。无需上游技能支持。
流水线传递	`/plate --hard` 会在最终写入关卡之后、发布之前调用 `/hard-cheese <slug>`	已验证产物 → 提交评审的边界位置。

--hard

参数会在

/cheese → /mold → /cook → /press → /age → /cure → /plate

的流程中传递。上游技能仅负责传递该参数；

/plate

是唯一会调用

/hard-cheese

的流水线技能。

可移植性参考：

../cheese/references/harness-portability.md

。该文档涵盖了助手解析、子Agent调度、GitHub操作及交接流程；优先使用捆绑或仓库本地的助手，将

${CLAUDE_SKILL_DIR}

视为可选的宿主提供的备用方案。下方的交接模块是可移植契约；斜杠命令是宿主层的呈现形式，而非控制模型。

Flow

流程

Resolve scope.
- ```
diff_base = origin/main
```
  ,
```
diff_head = <short-sha of HEAD>
```
  .
- If
```
.cheese/specs/<slug>.md
```
  exists, load it as the intent reference (optional — diff is the ground truth).
- Slug fallback when none supplied: the HEAD short SHA.
- If the working tree has no diff against
```
origin/main
```
  , exit
```
0
```
  with
```
"nothing to gate on"
```
  and write no artifact.

Freshness check. Check freshness before launching the gate:

python3 skills/hard-cheese/scripts/hard-cheese.pyz freshness-check \
  --slug <slug> --passing-score <n>

Exit 0 (

previously_passed

): print

"previously passed"

and exit

. Exit 2 (

stale

: HEAD moved or the last PASS score is below

--passing-score

) or 3 (

new

): continue to step 3.

Compose the vibecheck prompt (faithful to Sankaranarayanan 2026, generalised to "share for review" so the gate stays implementation-agnostic):

Before this is shared for review, explain its causal logic in your own words. How does <feature or fix> work? Why does it produce the desired behavior? What state, control flow, or invariants does it rely on?
Render a diff summary alongside the prompt. When invoked by
```
/plate
```
, also render
```
/plate
```
's final artifact inventory and
```
{target, backend, verified}
```
rows so the explanation covers the exact state about to be shared.
Capture the user's explanation as free text. No coaching, no example answers — the explanation is the artifact under test.
Spawn the judge sub-agent in fresh context (same pattern
```
/cook
```
's fan pathway uses for adversarial review). The judge:
- Reads
```
references/judge-prompt.md
```
  as its system prompt.
- Receives the passing score threshold, the diff summary, the spec excerpt (if any), and the user's explanation as context.
- Returns a JSON object:
```
{score, level, pass, feedback, socratic_qs}
```
  .
See
```
references/judge-prompt.md
```
for the full system prompt and output shape.
Skip this step when
```
--no-judge
```
is set: mark the attempt
```
status: LOGGED
```
, write the artifact, exit
```
0
```
.

On judge result:

```
score >= <passing-score>
```
→ PASS.
```
score < <passing-score>
```
→ FAIL, render Socratic questions, loop to step 4 if
```
attempts < --socratic-cap
```
. Judge error → ERROR attempt, print warning, exit
```
0
```
(fail-open — see
```
## Divergence from the paper
```
).

Append the attempt row:

python3 skills/hard-cheese/scripts/hard-cheese.pyz append-attempt \
  --slug <slug> --status <PASS|FAIL|ERROR> --score <n> \
  --feedback "<judge feedback>" --explanation "<user explanation>"

On cap exhaustion: set the artifact
```
status: FAILED
```
, print the path, exit non-zero. Downstream chains must not proceed.

确定范围
- ```
diff_base = origin/main
```
  ，
```
diff_head = <HEAD的短SHA值>
```
  。
- 若
```
.cheese/specs/<slug>.md
```
  存在，则加载该文件作为意图参考（可选——diff为事实基准）。
- 未指定slug时的 fallback：使用HEAD的短SHA值。
- 若工作区与
```
origin/main
```
  无差异，则返回
```
0
```
  并输出
```
"nothing to gate on"
```
  ，不生成任何产物。
新鲜度检查 在启动关卡前检查新鲜度：
```
python3 skills/hard-cheese/scripts/hard-cheese.pyz freshness-check \
  --slug <slug> --passing-score <n>
```
返回0（
```
previously_passed
```
）：输出
```
"previously passed"
```
并返回
```
0
```
。返回2（
```
stale
```
：HEAD已更新或上次PASS分数低于
```
--passing-score
```
）或3（
```
new
```
）：继续执行步骤3。
生成认知检查提示（严格遵循Sankaranarayanan 2026的定义，泛化为“提交评审”以保持关卡的实现无关性）：

在提交评审前，用你自己的话解释其因果逻辑。<功能或修复>的工作原理是什么？它为何能产生预期行为？它依赖哪些状态、控制流或不变量？
在提示旁渲染diff摘要。若由
```
/plate
```
调用，还需渲染
```
/plate
```
的最终产物清单及
```
{target, backend, verified}
```
行，确保解释覆盖即将提交的准确状态。
捕获用户的解释内容（纯文本形式）。不提供指导或示例答案——解释内容即为待测试的产物。
启动全新上下文的评判子Agent（采用与
```
/cook
```
的分支路径相同的对抗性评审模式）。评判Agent：
- 读取
```
references/judge-prompt.md
```
  作为系统提示。
- 接收合格分数阈值、diff摘要、规范片段（若有）及用户解释作为上下文。
- 返回JSON对象：
```
{score, level, pass, feedback, socratic_qs}
```
  。
完整的系统提示和输出格式请参考
```
references/judge-prompt.md
```
。
若设置了
```
--no-judge
```
，则跳过此步骤：标记尝试状态为
```
LOGGED
```
，生成产物，返回
```
0
```
。

处理评判结果：

```
score >= <passing-score>
```
→ PASS。
```
score < <passing-score>
```
→ FAIL，展示苏格拉底式问题，若
```
attempts < --socratic-cap
```
则回到步骤4。评判错误 → ERROR尝试，输出警告，返回
```
0
```
（开放失败——详见
```
## 与论文的差异
```
）。

添加尝试记录行：

python3 skills/hard-cheese/scripts/hard-cheese.pyz append-attempt \
  --slug <slug> --status <PASS|FAIL|ERROR> --score <n> \
  --feedback "<judge feedback>" --explanation "<user explanation>"

重试次数耗尽：将产物状态设为
```
FAILED
```
，输出路径，返回非零退出码。下游流程不得继续执行。

Artifact

产物

.cheese/hard-cheese/<slug>.md

is the audit trail. The directory is gitignored by repo convention (

.gitignore

already ignores

.cheese/

), so the trail stays local — matching vibecheck's local-only stance on telemetry.

Each file opens with a YAML frontmatter block that travels with the audit trail:

yaml

---
slug: <slug>
attribution: Sankaranarayanan 2026 / vibecheck
rubric: SOLO Taxonomy (1-5), pass threshold = <passing-score>
passing_score: <n>
divergence: fail-open on judge error (vibecheck fails closed)
diff_base: <sha>
diff_head: <short-sha>
status: PASS | FAIL | FAILED | LOGGED
attempts: <n>
---

The attempt log uses a 6-column markdown table (written by

append-attempt

markdown

| timestamp | head_sha | status | score | feedback | explanation |
| --- | --- | --- | --- | --- | --- |
| 2026-06-25T10:00:00+00:00 | a1b2c3d | FAIL | 2 | "Unistructural: lists steps but no causal link" | <user explanation verbatim> |
| 2026-06-25T10:05:00+00:00 | a1b2c3d | PASS | 4 | "Relational: explains why invariant holds" | <user explanation verbatim> |

Attempts append; nothing is overwritten within a single invocation. If a re-invocation finds the artifact stale (HEAD moved), new attempt rows are appended below the prior ones — the trail is cumulative.

.cheese/hard-cheese/<slug>.md

为审计追踪文件。根据仓库约定，该目录已被git忽略（

.gitignore

已排除

.cheese/

），因此追踪记录仅保存在本地——与vibecheck的本地遥测立场一致。

每个文件开头包含随审计追踪同步的YAML前置块：

yaml

---
slug: <slug>
attribution: Sankaranarayanan 2026 / vibecheck
rubric: SOLO Taxonomy (1-5), pass threshold = <passing-score>
passing_score: <n>
divergence: fail-open on judge error (vibecheck fails closed)
diff_base: <sha>
diff_head: <short-sha>
status: PASS | FAIL | FAILED | LOGGED
attempts: <n>
---

尝试日志采用6列Markdown表格（由

append-attempt

写入）：

markdown

| timestamp | head_sha | status | score | feedback | explanation |
| --- | --- | --- | --- | --- | --- |
| 2026-06-25T10:00:00+00:00 | a1b2c3d | FAIL | 2 | "Unistructural: lists steps but no causal link" | <用户解释原文> |
| 2026-06-25T10:05:00+00:00 | a1b2c3d | PASS | 4 | "Relational: explains why invariant holds" | <用户解释原文> |

尝试记录会追加写入；单次调用内不会覆盖任何内容。若重新调用时发现产物过期（HEAD已更新），新的尝试记录行会追加到原有记录下方——追踪记录是累积式的。

Sub-agent contract — fresh judge

子Agent契约——全新评判者

Fresh context, every invocation. Same-context judging is biased toward the code it helped write.
Resolve a no-tool or read-only
```
reviewer
```
through the shared agent resolver at
```
default
```
power and
```
high
```
effort. A general worker qualifies only with prompt-only no-write enforcement and
```
degraded: true
```
.
```
references/judge-prompt.md
```
is the system prompt. The judge reads the supplied diff summary, spec excerpt, and explanation, then returns JSON without repository writes.
JSON output is parsed. If parsing fails, the attempt is logged as
```
ERROR
```
and the gate fails open (see
```
## Divergence from the paper
```
).

If the host harness has no sub-agent primitive,

/hard-cheese

is the wrong skill — the gate cannot run without a fresh judge. Recommend

/hard-cheese --no-judge

for users who still want the explanation captured as telemetry without the grading step.

每次调用均使用全新上下文。同一上下文的评判会对其协助编写的代码产生偏见。
通过共享Agent解析器获取无工具或只读权限的
```
reviewer
```
，设置为
```
default
```
算力和
```
high
```
工作量。通用Worker仅在满足“仅提示、无写入权限”且
```
degraded: true
```
时符合要求。
```
references/judge-prompt.md
```
为系统提示。评判者读取提供的diff摘要、规范片段和解释内容，返回JSON且不写入仓库。
JSON输出会被解析。若解析失败，该尝试会被记录为
```
ERROR
```
，关卡开放失败（详见
```
## 与论文的差异
```
）。

若宿主工具链无子Agent原语，则

/hard-cheese

不适用——没有全新评判者的话，关卡无法运行。对于仍希望捕获解释内容作为遥测但无需评分步骤的用户，建议使用

/hard-cheese --no-judge

模式。

Attribution

引用来源

Sankaranarayanan, S. (2026). Mitigating 'Epistemic Debt' in Generative AI-Scaffolded Novice Programming using Metacognitive Scripts. Proceedings of the 13th ACM Conference on Learning at Scale. https://arxiv.org/abs/2602.20206

The implementation reference (intercept-at-acceptance, SOLO rubric, Socratic retry) is the open-source VS Code extension by the paper's author:

https://github.com/sreecharansankaranarayanan/vibecheck

The attribution appears in this

SKILL.md

, in

references/judge-prompt.md

, and in every

.cheese/hard-cheese/<slug>.md

artifact so the citation travels with the audit trail.

Sankaranarayanan, S. (2026). Mitigating 'Epistemic Debt' in Generative AI-Scaffolded Novice Programming using Metacognitive Scripts. Proceedings of the 13th ACM Conference on Learning at Scale. https://arxiv.org/abs/2602.20206

实现参考（验收拦截、SOLO评分标准、苏格拉底式重试）来自该论文作者开发的开源VS Code扩展：

https://github.com/sreecharansankaranarayanan/vibecheck

该引用会出现在本

SKILL.md

、

references/judge-prompt.md

及每个

.cheese/hard-cheese/<slug>.md

产物中，确保引用随审计追踪同步。

Divergence from the paper

与论文的差异

Hard-cheese departs from vibecheck in exactly one place, and the divergence is called out explicitly so it stays legible:

Vibecheck fails closed on judge error. If the Judge LLM cannot produce a verdict, the modal blocks code application until the judge recovers or the user retries with a different model.

Hard-cheese fails open on judge error. If the fresh-context judge sub-agent crashes, times out, or returns malformed JSON, the gate writes an

ERROR

attempt, prints a clear warning, and exits

— the user is allowed to proceed.

Rationale: judge invocation is per-PR-attempt and per-retry, and a strict fail-closed policy creates a worse experience under API hiccups than the epistemic-debt cost it averts. New divergences must be added here.

Hard-cheese与vibecheck仅在一处存在差异，且该差异已明确标注以保持可读性：

Vibecheck在评判错误时关闭失败。若评判LLM无法生成结论，模态框会阻止代码提交，直到评判恢复或用户更换模型重试。

Hard-cheese在评判错误时开放失败。若全新上下文的评判子Agent崩溃、超时或返回格式错误的JSON，关卡会记录

ERROR

尝试，输出明确警告并返回

——允许用户继续操作。

理由：评判调用针对每次PR尝试和重试，严格的关闭失败策略在API故障时带来的体验问题，超过了它所能避免的认知债务成本。新增差异必须在此处标注。

Composition with

--auto

与

--auto

的组合使用

--hard

and

--auto

may coexist. The gate punctures auto exactly once inside terminal

/plate --hard

, after

/plate

verifies final artifacts and before publication. The user responds, then PASS permits publication, FAILED halts, and ERROR follows the documented fail-open behavior.

Commit-only

/plate --hard

does not fire because nothing is shared. For a new PR under auto,

/plate

honors explicit topology, infers an obviously cohesive single, and asks when stacked is recommended or shape is ambiguous. Non-TTY behavior lives in

references/composition.md

--hard

和

--auto

可共存。关卡会在终端

/plate --hard

内部精准触发一次，即在

/plate

验证最终产物之后、发布之前。用户做出响应后，PASS允许发布，FAILED终止流程，ERROR遵循文档中定义的开放失败行为。

仅提交的

/plate --hard

不会触发，因为没有内容需要分享。对于自动模式下的新PR，

/plate

会遵循显式拓扑，推断出明显连贯的单一任务，在推荐堆叠或形状不明确时询问用户。非TTY行为请参考

references/composition.md

。

Output

输出

When the gate ends, print:

Hard-cheese artifact: .cheese/hard-cheese/<slug>.md
Status: PASS | FAILED | LOGGED | ERROR
Attempts: <n>

Followed by:

On PASS:
```
Ready to share for review.
```

On FAILED:

Cap exhausted. Improve understanding of the change before sharing.

On LOGGED:

Telemetry only — judge skipped via --no-judge.

On ERROR: a one-line warning naming the failure mode and

Fail-open divergence active — gate exited 0; you may share for review at your discretion.

关卡结束时，输出：

Hard-cheese artifact: .cheese/hard-cheese/<slug>.md
Status: PASS | FAILED | LOGGED | ERROR
Attempts: <n>

随后输出：

PASS时：
```
Ready to share for review.
```
（可提交评审）
FAILED时：
```
Cap exhausted. Improve understanding of the change before sharing.
```
（重试次数耗尽，在分享前请加深对变更的理解）
LOGGED时：
```
Telemetry only — judge skipped via --no-judge.
```
（仅遥测模式——通过--no-judge跳过了评判）
ERROR时：单行警告，说明失败模式，并输出
```
Fail-open divergence active — gate exited 0; you may share for review at your discretion.
```
（开放失败差异生效——关卡返回0；您可自行决定是否提交评审）

Preferred tools and fallbacks

首选工具与备用方案

Need	Prefer	Fallback
Diff inspection for the user-facing summary	`delta`	`git diff --unified=3`
Reading the spec (when present)	bounded file read per `code-intelligence-routing.md`	host file read
Spawning the judge	host sub-agent primitive ( `Agent()` or harness equivalent)	none — without sub-agent spawn, run `--no-judge` mode and tell the user the judge is unavailable
GitHub / PR context (out of scope here)	n/a	n/a

需求	首选工具	备用方案
面向用户的diff摘要检查	`delta`	`git diff --unified=3`
读取规范（若存在）	按 `code-intelligence-routing.md` 进行有限文件读取	宿主文件读取
启动评判Agent	宿主子Agent原语（ `Agent()` 或工具链等效功能）	无——若无启动子Agent的能力，运行 `--no-judge` 模式并告知用户评判不可用
GitHub / PR上下文（本工具不涉及）	n/a	n/a

Rules

规则

The judge sub-agent runs in fresh context. Do not let the same conversation that wrote the code grade the human's understanding of it.
Do not coach the user before they answer. The explanation is the artifact under test. Socratic questions appear only after a FAIL, and only the questions returned by the judge — no extra hints from the parent.
Do not paraphrase the user's explanation before passing it to the judge. The judge grades what the user wrote, verbatim.
Do not skip the freshness check. Re-invoking after HEAD has moved must trigger a fresh attempt sequence — prior comprehension is stale once the code changes.
Do not silently drop ERROR attempts. The fail-open divergence requires that every judge failure is recorded in the artifact and surfaced to the user as a warning.
Do not invoke
```
/gh
```
or any specific PR-creation tool. The gate's contract is "before code is shared for review" — implementation-agnostic.
Apply the shared voice kernel (lives at
```
../age/references/voice.md
```
): say what the gate result was, flag residual risk as
```
certain | speculating | don't know
```
, do not soften FAILED into "almost passing".

评判子Agent必须在全新上下文运行。不得让编写代码的同一对话来评估人类对代码的理解。
用户作答前不得提供指导。解释内容即为待测试的产物。苏格拉底式问题仅在FAIL后展示，且仅展示评判者返回的问题——父Agent不得额外提供提示。
将用户解释传递给评判者前不得改写。评判者需对用户的原文进行评分。
不得跳过新鲜度检查。HEAD更新后重新调用必须触发全新的尝试序列——代码变更后，之前的理解即过期。
不得静默丢弃ERROR尝试。开放失败差异要求所有评判失败都记录到产物中，并以警告形式告知用户。
不得调用
```
/gh
```
或任何特定的PR创建工具。关卡的契约是“代码提交评审前”——与实现无关。
应用共享语音内核（位于
```
../age/references/voice.md
```
）：说明关卡结果，将剩余风险标记为
```
certain | speculating | don't know
```
，不得将FAILED软化表述为“几乎通过”。

References

参考文档

```
references/judge-prompt.md
```
— SOLO Taxonomy rubric, judge sub-agent system prompt, JSON output shape.
```
references/composition.md
```
— the full
```
--hard
```
/
```
--auto
```
matrix and the single puncture point.
```
skills/hard-cheese/scripts/hard-cheese.pyz freshness-check
```
— checks whether a previous PASS is still fresh for the current HEAD and passing score (step 2).
```
skills/hard-cheese/scripts/hard-cheese.pyz append-attempt
```
— atomically appends an attempt row to the audit trail (step 6).

```
references/judge-prompt.md
```
— SOLO分类法评分标准、评判子Agent系统提示、JSON输出格式。
```
references/composition.md
```
— 完整的
```
--hard
```
/
```
--auto
```
矩阵及精准触发点。
```
skills/hard-cheese/scripts/hard-cheese.pyz freshness-check
```
— 检查之前的PASS结果对于当前HEAD和合格分数是否仍有效（步骤2）。
```
skills/hard-cheese/scripts/hard-cheese.pyz append-attempt
```
— 原子化地将尝试记录行追加到审计追踪中（步骤6）。

Agent resolution

Agent解析

Resolve the fresh judge through

../cheese/references/agent-resolution.md

Work	Preferred types	Permissions/isolation	Minimum power	Effort	Fallback
Grade the explanation	reviewer	no-tool or read-only, fresh-context	default	high	compatible reviewer, then general

The canonical hard-cheese audit carries the shared

agent_resolution

block.

通过

../cheese/references/agent-resolution.md

解析全新评判者。

任务	首选类型	权限/隔离	最低算力	工作量	备用方案
评分解释内容	reviewer	无工具或只读权限，全新上下文	default	high	兼容的reviewer，再到通用Agent

标准的hard-cheese审计会包含共享的

agent_resolution

模块。

hard-cheese

Original

Translation

/hard-cheese

/hard-cheese

Inputs

输入参数

Invocation modes

调用模式

Flow

流程

Artifact

产物

Sub-agent contract — fresh judge

子Agent契约——全新评判者

Attribution

引用来源

Divergence from the paper

与论文的差异

Composition with
`--auto`

与
`--auto`
的组合使用

Output

输出

Preferred tools and fallbacks

首选工具与备用方案

Rules

规则

References

参考文档

Agent resolution

Agent解析

hard-cheese

Original

Translation

/hard-cheese

/hard-cheese

Inputs

输入参数

Invocation modes

调用模式

Flow

流程

Artifact

产物

Sub-agent contract — fresh judge

子Agent契约——全新评判者

Attribution

引用来源

Divergence from the paper

与论文的差异

Composition with --auto

与--auto的组合使用

Output

输出

Preferred tools and fallbacks

首选工具与备用方案

Rules

规则

References

参考文档

Agent resolution

Agent解析

Composition with
`--auto`

与
`--auto`
的组合使用