grill-with-docs

1. Bilingual SKILL.md

左右滑动可直接切换英文版与中文版；两种语言按段落自动对齐。英文中的蓝色虚线词语可点击查看解释。共标记 4 处。

Entry SHA-256: 7de372c13488f1ee96cc11cd8907b56b6809cc93eef776eeddd37de6b6cbe3fe

2. Why This Skill Is Clever

一句话核心机制

这是一个极薄的双技能组合入口：它要求宿主分别加载 grilling 与 domain-modeling，把递进式访谈和术语/决策落盘纪律叠加到同一次设计澄清中。

触发与边界

• Direct source： disable-model-invocation: true 把入口限定为人类显式调用，模型不能自行启动这场高摩擦访谈。
• Supporting context： 配套 agents/openai.yaml 进一步设置 policy.allow_implicit_invocation: false；docs 页面把用户入口写成 /grill-with-docs。
• 适用边界： 它面向需要被追问、澄清，并希望把领域语言和关键取舍写入仓库的计划或设计。
• 不是 strict pure wrapper： 原文要求调用 grilling 和 domain-modeling 两个技能，不满足“把全部工作委托给恰好一个实现技能”的展开条件。因此双语 reader 只展示所选 SKILL.md，两个依赖仅作为分析证据。

信息架构 / 执行顺序

1. 用户显式调用 grill-with-docs。
2. Call the Skill tool twice 要求宿主执行两个独立技能加载动作，而不是猜测“带文档的 grilling”意味着什么。
3. grilling 构建设计树，按当前可回答的 frontier 分轮提问，并为每个问题给出推荐答案。
4. domain-modeling 在同一过程中质疑模糊术语、用场景和代码核验边界，并在术语刚刚确定时更新 CONTEXT.md。
5. 只有难以逆转、缺少背景会显得意外、且来自真实权衡的决定，才有资格进入 ADR。
6. 访谈必须收敛到共享理解；文档则只保存符合各自资格门槛的持久事实。

第 3–6 步来自 supporting context（两个被调用技能及 docs 页面），不是这一行入口自身展开的算法。

最巧妙的设计点

1. 把调用权限写进机器可读元数据 — disable-model-invocation: true
   - Direct source： 入口边界不是软性建议，而是宿主可执行的字段。
   - Interpretation： 密集追问会打断用户当前任务，显式调用可以防止模型擅自进入访谈模式。

2. 把组合关系写成精确的两次工具调用 — Call the Skill tool twice
   - Direct source： 新版本不再用“运行 A，同时使用 B”暗示组合，而是明确要求调用次数与技能名称。
   - Interpretation： 这减少了宿主只加载一个依赖、然后凭名称脑补另一个行为的空间。

3. 复用访谈控制流，而不复制它 — for "grilling"
   - Supporting context： grilling 用 design tree、frontier 和 rounds 管理问题依赖，并把环境事实与用户决策分开。
   - Interpretation： 入口不复制提问算法，避免两套访谈流程逐渐产生不同节奏和完成条件。

4. 把记录纪律作为并列能力加载 — and "domain-modeling"
   - Supporting context： 术语一旦明确便就地更新 CONTEXT.md，ADR 必须同时通过三项门槛。
   - Interpretation： 文档不再是会后可能补写的总结，而是认知收敛过程中的受控副作用。

5. 一句描述同时交代体验、目标和产物 — which also creates docs ... as we go
   - Direct source： 用户在调用前就知道它会持续追问、打磨设计，并写出 ADR 与术语表。
   - Interpretation： 对薄组合技能，描述价值差异比复制底层机制更有效。

防失败机制与 trade-off

明确的不变量

• Direct source： 只能显式调用；必须调用 Skill 工具两次；两个目标分别是 grilling 和 domain-modeling。
• Supporting context： grilling 不把可自行查找的事实甩给用户，也不在共享理解确认前行动；domain-modeling 要求 glossary 不含实现细节，并对 ADR 使用三重门槛。

它预防的失败

• 避免为“带文档的访谈”复制一套会漂移的采访算法。
• 避免只加载访谈能力却遗漏落盘能力，或反过来只写文档而没有充分澄清。
• 避免模型未经邀请就启动高摩擦的连续追问。

代价与可移植性风险

• 入口没有依赖缺失时的降级策略；任一技能未被宿主成功解析，组合行为都会残缺。
• Skill 工具、disable-model-invocation 与 OpenAI policy 文件属于具体 harness 约定，移植时必须重新实现依赖解析和权限边界。
• “边谈边写”会产生真实文件副作用，多人并行时需要额外的冲突、引用和陈旧性治理。
• 薄入口提升复用，却降低局部可读性；只读这一行无法知道访谈轮次、文档格式和 ADR 门槛。

可迁移原则

1. 组合，不复制： 新工作流若只是“既有控制流 + 横切纪律”，用薄入口连接，不要复制双方正文。
2. 把组合动作写成可验证命令： 明确调用次数、目标名称和顺序语义，少依赖自然语言暗示。
3. 副作用必须显式授权： 技能会写文件或打断用户时，把权限边界放进机器可读元数据。
4. 让记录贴近决策时刻： 在认识刚收敛时持久化，减少会后重写造成的信息损耗。
5. 为依赖缺失设计失败模式： 移植到其他 harness 时应增加依赖存在性检查和清晰报错。

今日实践题

如果你要把“代码评审”与“安全威胁建模”组合成一个新技能，薄入口应如何明确两次能力加载、调用边界和文件副作用，而不复制两个底层技能的正文？

Evidence note

• Direct source： 双语 reader 中完整展示的 grill-with-docs/SKILL.md，包括 frontmatter、描述和唯一执行句。
• Supporting context： 仅用于解释架构的 grilling/SKILL.md、domain-modeling/SKILL.md、agents/openai.yaml 与仓库 docs 页面；它们未混入所选原文。
• Interpretation： 关于双技能组合、依赖脆弱性、失真窗口、多人治理和迁移原则的判断，是基于上述证据的工程分析。