Home / All Skills / Workflow & Core Tools / grill-with-docs
English (EN)简体中文 (ZH)日本語 (JA)
Workflow & Core Tools · mattpocock/skills

grill-with-docs

A relentless interview to sharpen a plan or design, which also creates docs (ADRs and glossary) as we go.

L2 Local · Restricted workspaceV1 Commit-PinnedWrite FileDual-pass Audit
Author mattpocockGitHub mattpocock/skills ↗Stars 253833License MITCommit 3cca18b368
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

grill-with-docs itself is a zero-implementation pure orchestration shell: its body consists of only a single sentence, delegating all tasks to two other skills in the same repo (grilling and domain-modeling), which are sequentially loaded by the host's 'Skill tool'.

skills/engineering/grill-with-docs/SKILL.md
Call the Skill tool twice, for "grilling" and "domain-modeling".
The entire SKILL.md consists of just 7 lines (4 lines of frontmatter + 1 sentence in the body). It contains no scripts, references, or templates. Its functionality is 100% provided by the referenced skills, making it a Class-A pure instruction boilerplate.

The interrogation capability comes from grilling: round-based interviews over the design tree frontier—asking all available questions at once in each round, numbered and accompanied by recommended answers, and computing the next frontier only after the user responds, until no hidden assumptions remain.

skills/productivity/grilling/SKILL.md
Map this as a **design tree**: every decision branches into the decisions that hang off it. Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled... Ask the whole frontier in one round: number each question and give your recommended answer.
grilling is an interview primitive reused across 5+ skills in the repository (grill-me, grill-with-docs, triage, wayfinder, improve-codebase-architecture, as explicitly stated in the README); it can be triggered autonomously by the model based on description (no disable-model-invocation).

The capability to generate documentation during interviews comes from domain-modeling: terms are written directly into the CONTEXT.md glossary as soon as they are finalized, ADRs are generated only when decisions meet three strict criteria, and directories are created lazily.

skills/engineering/domain-modeling/SKILL.md
When a term is resolved, update `CONTEXT.md` right there. Don't batch these up: capture them as they happen.
Formatting is supplied by CONTEXT-FORMAT.md and ADR-FORMAT.md in the same directory (internally linked within this skill as ./CONTEXT-FORMAT.md and ./ADR-FORMAT.md). ADRs are minimalist: they can be as short as 1–3 sentences.

Triggering is double-locked to 'explicit user invocation only': both the SKILL.md frontmatter and agents/openai.yaml explicitly disallow implicit invocation, preventing the interview workflow from being spontaneously disrupted by the model.

skills/engineering/grill-with-docs/SKILL.md
disable-model-invocation: true
CLAUDE.md confirms the repo convention: user-invoked skill = disable-model-invocation: true + agents/openai.yaml with policy.allow_implicit_invocation: false (both are present in this skill). The two delegated skills do not have these flags (allowing autonomous model invocation).

Artifact discipline is built directly into the referenced skills rather than the shell: CONTEXT.md must remain a pure glossary, and an ADR is written only if it simultaneously satisfies all three criteria: 'hard to reverse / surprising without context / genuine trade-off'.

skills/engineering/domain-modeling/SKILL.md
Only offer to create an ADR when all three are true: 1. **Hard to reverse**... 2. **Surprising without context**... 3. **The result of a real trade-off**...
ADR-FORMAT.md echoes this principle: "The value is in recording *that* a decision was made and *why*, not in filling out sections." Documentation is a byproduct of the interview rather than an afterthought.

2Core Capabilities

01Round-based design tree interrogation: exhausts the current frontier in each round, numbering questions and including recommended answers, advancing only after the user answers
02Self-checking facts without disturbing the user: dispatches sub-agents to discover environment facts required by frontier questions, avoiding asking the user for discoverable information
03Immediate correction of terminology conflicts: flags discrepancies on the spot whenever user terminology clashes with the CONTEXT.md glossary
04Refining vague language: proposes more precise canonical terms and forces users to clarify conceptual boundaries
05Scenario stress testing and code cross-checking: probes domain relationships with edge-case scenarios and validates user claims against the codebase
06Instant glossary persistence: updates CONTEXT.md immediately once a term is finalized, prohibiting batching
07Restrained ADR logging: proposes recording an ADR only when all three criteria are met, with templates as concise as 1–3 sentences and sequentially numbered

4Recommended Governance & Evidence

Suggested Controls for Safe Operation
For Agent Runtime
Restrict working directory
For Administrators
Retain operation logs
Evidence & Triggers (File Paths & Excerpts)
  • 本地工作目录: File read/write and artifact output: The model writes to the user project according to domain-modeling instructions: CONTEXT.md (created/updated when the first term is settled), CONTEXT-MAP.md (in multi-context scenarios),
Audit Notes: Verbatim inspection of all files across the three directories (SKILL.md × 3, agents yaml × 3, two FORMAT templates): no scripts, no network calls, no credential reading, and no hidden files or symlinks. The sole 'action' is the model writing CONTEXT.md/ADR documents in the user's project per instructions, which constitutes the skill's core functionality. Triggers are double-locked to explicit user invocation only.

5Second-Pass Verification

  • [ok] grill-with-docs 目录仅 SKILL.md + agents/openai.yaml — find 全目录 + 隐藏文件/符号链接扫描：确无 scripts/references/数据文件，无 dotfile
  • [ok] 正文引用 'grilling' 与 'domain-modeling' 真实存在于本 repo 且 frontmatter name 精确匹配 — skills/productivity/grilling/SKILL.md name: grilling；skills/engineering/domain-modeling/SKILL.md name: domain-modeling；无外部缺失引用
  • [ok] 外部依赖为零的结论 — 对 grill-with-docs + grilling + domain-modeling 全部 8 个文件 grep 网络/CLI/凭证/执行特征词：0 命中。无任何第三方包、API、端点
  • [ok] 触发控制双锁一致 — SKILL.md 有 disable-model-invocation: true，agents/openai.yaml 有 allow_implicit_invocation: false，两清单一致；被委托的 grilling/domain-modeling 均无此标志（可模型自触发），CLAUDE.md 对 user-invoked/model-invoked 的 repo 约定与实况吻合
  • [ok] 功能声明 vs 实际能力：'relentless interview + creates docs (ADR's and glossary) as we go' — 声明成立但有前提：壳本身零自含指令，能力全部来自宿主 'Skill tool' 装载两个兄弟 skill 并叠加模型判断；若宿主无跨 skill 调用机制、兄弟 skill 未安装、或模型只调了一个，则行为降级/空转，壳无任何兜底或自查提示。README 定位（L101/L131：'same as grill-me, but adds more goodies'、'grilling session... build a shared language... document hard-to-explain decisions in ADR's'）与声明一致
  • [ok] 组合语义是否写明（'Call the Skill tool twice' 之后如何交织 interview 与写文档） — 未写明交织时序：文档化节奏靠 domain-modeling 的 inline 指令（'capture them as they happen'）与模型临场判断自然浮现，壳不保证两流程并发执行。复核认定为设计取舍而非缺陷，但稳定性依赖宿主行为
  • [ok] 安全结论反例搜索（漏网的隐藏执行/网络/凭证面） — 未找到反例：无可执行文件、无 base64/混淆内容、无 URL、无环境变量读取。文件写入面即 CONTEXT.md/ADR（设计意图，相对路径 lazy 创建）
  • [ok] 形态演化历史 — git log 证实：2026-04-30 曾移除 disable-model-invocation；2026-05-31 221ffca 把自含长 prompt 重构为委托式壳并重引入该标志；2026-08-15 系列 commit 把跨 skill 措辞统一为 'Call the Skill tool ... with "name"' 的多工具调用写法。当前 pin（2026-09-04）为最新稳定形态

6Verdict & Scenarios

  • Compositional reuse over duplication: a one-line shell reuses a repo-level interview primitive; grilling simultaneously serves five skills (grill-me, grill-with-docs, triage, wayfinder, improve-codebase-architecture), centralizing maintenance
  • Strong interview output discipline: numbered rounds coupled with mandatory recommended answers transform 'grilling' into an actionable, structured dialogue rather than rambling conversation
  • Deliberately minimalist and restrained documentation artifacts: ADRs can be just 1–3 sentences and CONTEXT.md excludes implementation details, minimizing long-term maintenance overhead so documentation remains a byproduct rather than an extra burden
  • Triggering is entirely under user control (double-locked against implicit invocation), preventing spontaneous activation by the model from interrupting workflows during unrelated conversations
    • Best for: Scenarios involving engineering changes, designs, or plans requiring deep alignment before execution, suitable for individuals or small teams willing to curate domain glossaries and decision records throughout dialogue; works out-of-the-box on Claude Code-based hosts (featuring the cross-skill Skill tool mechanism); provides maximum value to long-evolving repositories prone to terminology drift.
    Not for: Hosts lacking Skill tool capabilities (the shell contains no self-contained instructions, resulting in a no-op if executed directly); minor tweaks requiring only quick confirmation (overkill); non-coding personal tasks, which should use grill-me or grilling instead; scenarios that do not require documentation artifacts, where omitting the domain-modeling layer is advised.
    Install Agent-Ready
    ① Verified Mirror 2026-09-06
    Option A · Direct DownloadDownload grill-with-docs.tar.gz
    sha256: aabd3027347e47eb…
    Option B · Copy Guide for Agent
    install.json
    Agents automatically download and verify mirrors from this JSON guide.
    ② Upstream GitHub
    GitHub Repo ↗
    Pinned to commit 3cca18b368.