Back to Details

grill-with-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Grill With Docs

基于文档的严苛评审

A grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation inline as decisions crystallize.
这是一场针对现有领域模型挑战方案的严苛评审会议，可明确术语，并在决策成型时同步更新文档。

When to use this skill

适用场景

  • Validating architectural plans against a project's domain language
  • Stress-testing designs before implementation
  • Updating CONTEXT.md terminology as new concepts emerge
  • Preparing issues for implementation (pairs with 
    triage
    )
  • 验证架构方案是否符合项目的领域语言
  • 在实施前对设计进行压力测试
  • 当出现新概念时更新CONTEXT.md中的术语
  • 为实施准备议题（可与
    triage
    技能搭配使用）

When not to use this skill

不适用场景

  • Finding refactoring opportunities → use 
    improve-codebase-architecture
  • Writing implementation tickets → use 
    to-issues
  • General code review → use 
    code-review
  • 寻找重构机会 → 使用
    improve-codebase-architecture
    技能
  • 编写实施工单 → 使用
    to-issues
    技能
  • 常规代码评审 → 使用
    code-review
    技能

Session process

会议流程

1. Explore domain context

1. 梳理领域上下文

Before grilling, read:
  • CONTEXT.md
    — existing domain terminology
  • docs/adr/
    — prior architectural decisions
  • Relevant source files to understand current state
开始评审前，请阅读：
  • CONTEXT.md
    — 现有领域术语文档
  • docs/adr/
    — 过往架构决策记录
  • 相关源码文件以了解当前状态

2. Run the grilling loop

2. 开展评审循环

Interview relentlessly about every decision point. For each question:
  • Provide a recommended answer
  • Ask one question at a time, waiting for feedback before continuing
  • Explore the codebase instead of asking when the answer is findable there
针对每个决策点进行深入质询。针对每个问题：
  • 提供建议答案
  • 一次只提一个问题，等待反馈后再继续
  • 若答案可在代码库中找到，则直接查看代码库而非提问

3. Three stress-test mechanisms

3. 三种压力测试机制

Glossary alignment — When the user uses a term that conflicts with CONTEXT.md, call it out:
"Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
Precision sharpening — When terms are vague or overloaded, propose canonical names:
"You're saying 'account' — do you mean the Customer or the User? Those are different things."
Scenario-based edge-case testing — When domain relationships are discussed, stress-test with concrete scenarios that probe boundaries between concepts.
术语表对齐 — 当用户使用的术语与CONTEXT.md冲突时，及时指出：
"你的术语表将'cancellation'定义为X，但你此处的意思似乎是Y — 到底是哪一个？"
术语精准化 — 当术语模糊或存在歧义时，提出规范名称：
"你提到了'account' — 你指的是Customer还是User？这两者是不同的概念。"
基于场景的边界测试 — 当讨论领域关系时，通过具体场景进行压力测试，探索概念间的边界。

4. Update docs inline

4. 同步更新文档

CONTEXT.md — When a term is resolved, update it immediately. Don't batch updates.
File structure for single-context repos:
/
├── CONTEXT.md
├── docs/
│   └── adr/
│       └── 0001-decision-name.md
For monorepos with 
CONTEXT-MAP.md
at root, each context has its own 
CONTEXT.md
and 
docs/adr/
.
Create files lazily — only when you have something to write.
ADRs — Only create when all three are true:
  1. Hard to reverse (meaningful cost to change later)
  2. Surprising without context (future reader would wonder "why?")
  3. Result of a real trade-off (genuine alternatives existed)
If any condition is missing, skip the ADR.
CONTEXT.md — 当术语确定后，立即更新，不要批量更新。
单上下文仓库的文件结构：
/
├── CONTEXT.md
├── docs/
│   └── adr/
│       └── 0001-decision-name.md
对于根目录下有
CONTEXT-MAP.md
的单体仓库，每个上下文都有自己的
CONTEXT.md
和
docs/adr/
目录。
按需创建文件 — 仅当有内容可写时才创建。
ADRs — 仅当满足以下全部三个条件时才创建：
  1. 难以逆转（后续变更成本高）
  2. 缺乏上下文会令人困惑（未来读者会疑惑"为什么这么做？"）
  3. 是权衡后的结果（存在真正的替代方案）
若任一条件不满足，则无需创建ADR。

Cross-reference with code

与代码交叉验证

When the user states how something works, verify the code agrees. Surface contradictions:
"Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
当用户说明某功能的工作方式时，验证代码是否一致。指出矛盾之处：
"你的代码会取消整个Orders，但你刚才说支持部分取消 — 哪个是正确的？"

File formats

文件格式

  • CONTEXT.md: domain terminology meaningful to domain experts (no implementation details)
  • ADR format: title, status, context, decision, consequences
  • CONTEXT.md：面向领域专家的领域术语文档（不含实现细节）
  • ADR格式：标题、状态、上下文、决策、影响

Instructions

操作说明

  1. Identify the task trigger and expected output.
  2. Follow the workflow steps in this skill from top to bottom.
  3. Validate outputs before moving to the next step.
  4. Capture blockers and fallback path if any step fails.
  1. 识别任务触发条件及预期输出。
  2. 从上到下遵循本技能的工作流程步骤。
  3. 进入下一步前验证输出内容。
  4. 记录阻塞点及步骤失败时的 fallback 路径。

Examples

示例

  • Example: Apply this skill to a small scope first, then scale to full scope after validation passes.
  • 示例：先在小范围内应用此技能，验证通过后再扩展到全范围。

Best practices

最佳实践

  • Keep outputs deterministic and auditable.
  • Prefer small reversible changes over broad risky edits.
  • Record assumptions explicitly.
  • 保持输出可确定、可审计。
  • 优先选择小范围、可逆转的变更，而非大范围、高风险的编辑。
  • 明确记录假设。

References

参考资料

  • Project standards: 
    .agent-skills/skill-standardization/SKILL.md
  • Validator script: 
    .agent-skills/skill-standardization/scripts/validate_skill.sh
  • 项目标准：
    .agent-skills/skill-standardization/SKILL.md
  • 验证脚本：
    .agent-skills/skill-standardization/scripts/validate_skill.sh