I stopped using /grill-me for coding. Here’s what I use instead:

Matt Pocock15m 16sTranscript ✅Added May 15, 2:40 am GMT+8

Actionable Insights

Install Matt Pocock’s skills and start with /grill-with-docs when a repo already exists Use the upstream repo, mattpocock/skills (https://github.com/mattpocock/skills), or npx skills@latest add mattpocock/skills. First task to try: run /grill-with-docs let's build the docs you need before implementing a non-trivial feature. Expected benefit: the agent asks fewer repeated domain questions once the glossary exists. Caution: do not let the glossary become a spec dump. Start by turning this into a small, reversible pilot: write down the exact input, expected output, owner, and success metric before changing the wider workflow. The useful detail from the analysis is: /grill-with-docs improves the loop by grounding the interview in existing domain documentation, updating CONTEXT.md as language crystallizes, and adding ADRs when decisions are too consequential to leave implicit. The creator answers that the skill is incrementally adoptable and can be invoked with “let’s build the docs you need.” - There is concern about context bloat. Commenters ask whether loading CONTEXT.md costs more or fills the context window. Treat the first run as an evaluation, not a migration: capture before/after examples, note where the method saves time or improves quality, and keep the old path available until the new one passes repeated checks. Watch for the main failure mode here: overgeneralizing the creator’s demo beyond the evidence. If the video or comments only showed a narrow case, keep the rollout narrow and require fresh proof before broad adoption.
Create a minimal CONTEXT.md glossary before asking an agent to plan implementation Add only domain terms, definitions, and relationship facts: e.g. Pitch, Standalone Video, Pitch Status, Course, Lesson. Keep implementation choices out. Evaluation: if a future prompt can say “pitched standalone video” without re-explaining it, the glossary is paying rent. Start by turning this into a small, reversible pilot: write down the exact input, expected output, owner, and success metric before changing the wider workflow. The useful detail from the analysis is: - 1:30 — VS Code terminal with Claude Code and /grill-me. The terminal shows a detailed prompt about adding “pitches” to course-video-manager. - **5:01 — Domain awareness and fil This is one of the more practically useful “AI coding skills” videos because it moves attention away from clever prompting and toward durable project memory. Treat the first run as an evaluation, not a migration: capture before/after examples, note where the method saves time or improves quality, and keep the old path available until the new one passes repeated checks. Watch for the main failure mode here: overgeneralizing the creator’s demo beyond the evidence. If the video or comments only showed a narrow case, keep the rollout narrow and require fresh proof before broad adoption.
Use a CONTEXT-MAP.md only when the repo has multiple bounded contexts For a single app language, one root CONTEXT.md is cheaper. For monorepos, create a map that points to context-specific glossaries. Evidence: at 5:01 the video explicitly frames “bounded context” as the scope where a shared language applies. Start by turning this into a small, reversible pilot: write down the exact input, expected output, owner, and success metric before changing the wider workflow. The useful detail from the analysis is: The video’s thesis is that /grill-me is excellent for surfacing ambiguities, but it loses value in codebases because the hard-won shared language often disappears after the conversation. /grill-with-docs improves the loop by grounding the interview in existing domain documentation, updating CONTEXT.md as language crystallizes, and adding ADRs when decisions are too consequential to leave implicit. Treat the first run as an evaluation, not a migration: capture before/after examples, note where the method saves time or improves quality, and keep the old path available until the new one passes repeated checks. Watch for the main failure mode here: overgeneralizing the creator’s demo beyond the evidence. If the video or comments only showed a narrow case, keep the rollout narrow and require fresh proof before broad adoption.
Add ADRs only for hard-to-reverse, surprising, trade-off-heavy decisions Use the ADR pattern described at https://adr.github.io/ and the skill’s own docs/adr/ convention. Example: “pitch deletion is restricted, not cascaded” may merit an ADR if it shapes data lifecycle and user expectations. Do not write ADRs for routine library choices. Start by turning this into a small, reversible pilot: write down the exact input, expected output, owner, and success metric before changing the wider workflow. The useful detail from the analysis is: /grill-with-docs improves the loop by grounding the interview in existing domain documentation, updating CONTEXT.md as language crystallizes, and adding ADRs when decisions are too consequential to leave implicit. - 4:01 — GitHub preview of ubiquitous-language. The visible skill metadata describes extracting a DDD-style ubiquitous language glossary and spotting ambiguity/synonyms. Treat the first run as an evaluation, not a migration: capture before/after examples, note where the method saves time or improves quality, and keep the old path available until the new one passes repeated checks. Watch for the main failure mode here: overgeneralizing the creator’s demo beyond the evidence. If the video or comments only showed a narrow case, keep the rollout narrow and require fresh proof before broad adoption.
Turn every grilling answer into either a glossary update, an ADR, or an implementation constraint During the demo, the author decides one-to-many pitch/video cardinality, keeps “standalone video” meaning lessonId IS NULL, and chooses delete restrict. Your checklist: term resolved? update CONTEXT.md; irreversible trade-off? ADR; remaining implementation detail? ticket/PRD. Start by turning this into a small, reversible pilot: write down the exact input, expected output, owner, and success metric before changing the wider workflow. The useful detail from the analysis is: - 1:30 — VS Code terminal with Claude Code and /grill-me. The terminal shows a detailed prompt about adding “pitches” to course-video-manager. - Context docs are a compression layer. The author claims shared language reduces repeated explanation and even thinking-token verbosity. Treat the first run as an evaluation, not a migration: capture before/after examples, note where the method saves time or improves quality, and keep the old path available until the new one passes repeated checks. Watch for the main failure mode here: overgeneralizing the creator’s demo beyond the evidence. If the video or comments only showed a narrow case, keep the rollout narrow and require fresh proof before broad adoption.
Audit generated variable/UI names against the glossary before coding Search the diff for synonyms and collisions (orphan, unattached, pitched standalone, standalone standalone). Reject names that contradict CONTEXT.md; otherwise the agent’s future searches and reasoning degrade. Start by turning this into a small, reversible pilot: write down the exact input, expected output, owner, and success metric before changing the wider workflow. The useful detail from the analysis is: Here, the agent becomes another participant that benefits from the same language. Here, the agent becomes another participant that benefits from the same language. Treat the first run as an evaluation, not a migration: capture before/after examples, note where the method saves time or improves quality, and keep the old path available until the new one passes repeated checks. Watch for the main failure mode here: overgeneralizing the creator’s demo beyond the evidence. If the video or comments only showed a narrow case, keep the rollout narrow and require fresh proof before broad adoption.
Use this workflow before /to-prd, /to-issues, or implementation loops A pinned comment from the creator gives the suggested sequence: /grill-with-docs, /to-prd, /to-issues, then /goal or another implementation loop. Treat the glossary as shared vocabulary, not a replacement for acceptance criteria. Start by turning this into a small, reversible pilot: write down the exact input, expected output, owner, and success metric before changing the wider workflow. The useful detail from the analysis is: /grill-with-docs improves the loop by grounding the interview in existing domain documentation, updating CONTEXT.md as language crystallizes, and adding ADRs when decisions are too consequential to leave implicit. Here, the agent becomes another participant that benefits from the same language. Treat the first run as an evaluation, not a migration: capture before/after examples, note where the method saves time or improves quality, and keep the old path available until the new one passes repeated checks. Watch for the main failure mode here: overgeneralizing the creator’s demo beyond the evidence. If the video or comments only showed a narrow case, keep the rollout narrow and require fresh proof before broad adoption.

Core thesis

The video’s thesis is that /grill-me is excellent for surfacing ambiguities, but it loses value in codebases because the hard-won shared language often disappears after the conversation. /grill-with-docs improves the loop by grounding the interview in existing domain documentation, updating CONTEXT.md as language crystallizes, and adding ADRs when decisions are too consequential to leave implicit.

The strong version of the claim is not “documentation fixes agents.” It is: small, domain-focused documentation makes the human-agent conversation more precise, more reusable, and easier to translate into code.

Big ideas / key insights

The problem is not only missing requirements; it is missing vocabulary. The author’s example feature, “pitches,” cannot be implemented cleanly until the agent understands existing terms like “standalone video.”
DDD maps surprisingly well to agent work. Ubiquitous language was originally about domain experts, developers, and code sharing the same terms. Here, the agent becomes another participant that benefits from the same language.
Context docs are a compression layer. The author claims shared language reduces repeated explanation and even thinking-token verbosity. The exact token savings are not measured in the video, but the mechanism is plausible: canonical terms reduce restatement.
ADRs capture decisions that glossaries cannot. CONTEXT.md defines nouns and relationships; ADRs explain “why we chose this despite alternatives.”
Language choices become code choices. The demo shows that terms like “pitched standalone video” or “unattached standalone video” will leak into UI labels, table names, variables, and search paths if not corrected early.

Best timestamped moments with interpretation

0:00 — The author reintroduces /grill-me as a four-sentence skill that interviews the user until shared understanding is reached. This frames the new skill as an evolution, not a rejection.
1:30 — The “pitch” feature is introduced: a new entity for packaging videos before production. The useful detail is that the domain is understandable to the author but not yet encoded for the agent.
2:30–3:00 — The author identifies /grill-me’s failure mode: repeated explanations, unchallenged fuzzy language, and good terminology not being documented.
3:30–4:01 — Ubiquitous language from Domain-Driven Design enters the workflow. The author wants the thinnest documentation layer that gives the AI a leg up.
4:31–5:31 — /grill-with-docs is shown as /grill-me plus repo-aware documentation behavior: find CONTEXT.md, challenge language, cross-reference code, update docs.
6:33–7:04 — The author shows a real CONTEXT.md with definitions like “Standalone Video.” This is the clearest visual proof that the workflow depends on a concrete artifact, not just a prompt style.
7:35–8:06 — ADR criteria are introduced: hard to reverse, surprising without context, and a real trade-off. This prevents documentation bloat.
8:36–10:38 — The demo shows the skill questioning cardinality, terminology collision, status semantics, zero-video pitches, and deletion behavior before implementation.
11:08–12:09 — The agent updates context.md with pitch terms, but the author notices awkward terminology. This is the most practical lesson: documentation needs review, not blind acceptance.
12:09–13:40 — The promised benefit is concise alignment: planning, agent reasoning, and code navigation all use the same terms.

Comment insights

The audience sees this as a return to good docs. The most useful comment says the workflow resembles old-school documentation sites with tables of contents, links, and bookmarks. That is a compliment and a warning: this only works if docs remain navigable.
People want a bootstrap path. Several comments ask how to create the docs /grill-with-docs relies on. The creator answers that the skill is incrementally adoptable and can be invoked with “let’s build the docs you need.”
There is concern about context bloat. Commenters ask whether loading CONTEXT.md costs more or fills the context window. The creator’s answer is “value per token”: spend tokens where they improve alignment. That is plausible, but should be measured per repo.
Some want the ubiquitous-language skill separately. A commenter notes there is still a need for terminology capture outside grill sessions. That is a good workflow extension: glossary maintenance should not be tied only to feature planning.
The workflow resonates beyond coding. One detailed comment describes using /grill-me for creative/medical storytelling context, while another describes “defend my design” as a mini-dissertation process. The general pattern is adversarial clarification before execution.
Skepticism is healthy. Comments joke that this is “slop,” “code,” or “humans making things complicated.” The practical response is to keep artifacts thin: glossary for language, ADR for consequential decisions, PRD/issues for implementation.

Deep research: external evidence and caveats

Claim 1: Ubiquitous language improves software alignment

Evidence supporting it: Domain-Driven Design literature defines ubiquitous language as shared language between domain experts and developers, used both for communication and for naming source-code elements. Marco Tulio Valente’s DDD summary states that the language facilitates communication and provides names for classes, methods, attributes, modules, database tables, and API routes (https://softengbook.org/articles/ddd). Eric Evans’ DDD framing is the source tradition the video references.

Contradicting or limiting evidence: DDD is most valuable for complex domains. For small CRUD tools or throwaway prototypes, maintaining formal language docs can be overhead.

Assessment: The video’s DDD claim is well supported, but the amount of ceremony should scale with domain complexity.

Claim 2: `grill-with-docs` exists and is designed exactly this way

Evidence supporting it: The upstream mattpocock/skills repo describes skills for real engineering and links /grill-with-docs as a fix for agent misalignment. The raw grill-with-docs/SKILL.md says it challenges plans against the existing domain model, sharpens terminology, updates CONTEXT.md, and offers ADRs only when decisions are hard to reverse, surprising without context, and real trade-offs (https://github.com/mattpocock/skills and https://raw.githubusercontent.com/mattpocock/skills/main/skills/engineering/grill-with-docs/SKILL.md).

Contradicting or limiting evidence: The repo and video are creator-authored sources, not independent benchmarks. They verify behavior and intent, not performance gains.

Assessment: Strong evidence for what the skill is; weaker evidence for how much it improves outcomes.

Claim 3: ADRs are the right artifact for non-obvious architectural decisions

Evidence supporting it: adr.github.io defines an ADR as a record of a single architectural decision and its rationale, including trade-offs and consequences (https://adr.github.io/). This matches the video’s usage: decisions that are surprising without context and expensive to reverse.

Contradicting or limiting evidence: ADRs can become noise if used for every small choice. The skill’s “offer sparingly” rule is important.

Assessment: Agree, high confidence, when the decision is consequential.

Claim 4: Better shared docs reduce agent verbosity and token use

Evidence supporting it: The transcript gives anecdotal evidence and a plausible mechanism: if both human and model can refer to canonical terms, they need fewer explanations. The visual demo shows the agent finding “Standalone Video” instead of asking from scratch.

Contradicting or limiting evidence: No quantitative benchmark is shown. Context docs themselves consume tokens, and poor docs can increase confusion.

Assessment: Mixed-positive, medium confidence. Measure this with repeated task prompts before and after a glossary: number of clarification turns, prompt length, failed assumptions, and code rename churn.

Verdicts on major claims

“Use /grill-with-docs when you have a codebase; use /grill-me when you do not.” Agree, high confidence as a workflow heuristic. Practical takeaway: codebases have existing language and decisions; non-code problems benefit from pure interview mode.
“The same techniques that work with humans work with AI.” Mostly agree, medium-high confidence. Shared vocabulary helps both, but LLMs can still overfit stale docs or follow wrong terms confidently.
“This produces magical alignment.” Mixed, medium confidence. The demonstrated mechanism is real; “magical” is subjective and not independently measured.
“Context docs lead to concise replies and thinking traces.” Mixed, medium confidence. Plausible, but overclaimed without metrics. Treat it as a hypothesis to measure.
“Getting language right is crucial because it affects variables, files, and UI.” Agree, high confidence. Naming shapes code navigation, searchability, and user-facing consistency.

Screen-level insights: what the visuals add

0:00 — Talking-head intro. No UI is visible; the author is setting the social proof around /grill-me. Visual value is low but establishes that the video is a workflow explanation rather than a coding speedrun.
1:30 — VS Code terminal with Claude Code and /grill-me. The terminal shows a detailed prompt about adding “pitches” to course-video-manager. This matters because the feature is domain-heavy before it is code-heavy.
4:01 — GitHub preview of ubiquitous-language. The visible skill metadata describes extracting a DDD-style ubiquitous language glossary and spotting ambiguity/synonyms. This connects the video’s claim to a concrete skill file.
4:31 — GitHub preview of grill-with-docs/SKILL.md. The visible file structure shows CONTEXT.md and docs/adr/. This is the actual documentation topology the workflow expects.
5:01 — Domain awareness and file structure guidance. The screen shows single-context versus multi-context repository layouts. The visual step matters because it prevents overbuilding a context map for a simple repo.
6:33 — VS Code CONTEXT.md glossary. The file defines Course Video Manager terms and highlights “Standalone Video.” This frame proves the agent is reading a glossary, not guessing from code alone.
7:04 — Local CLAUDE.md/domain-doc pointer. The author points the agent to CONTEXT.md. This is important operationally: agents need discoverability hints for docs.
7:35 — Skill instructions about contradiction checking, inline context updates, and ADRs. The visible criteria enforce discipline: update terms as they crystallize, but use ADRs only for significant trade-offs.
9:37 — Claude Code asks about terminology collision. The terminal compares meanings of “Standalone Video” and asks whether pitching is metadata or a new category. This is the core value of the workflow: naming affects UI and schema.
11:08 — Terminal/editor after updating context.md. The author reviews newly added pitch terms and notices awkward phrasing. This visual matters because it shows the agent is a drafter, not the final authority.

Practical workflow checklist

Before a feature: run /grill-with-docs with the rough idea.
Let the agent inspect existing CONTEXT.md, CONTEXT-MAP.md, and docs/adr/.
Resolve one ambiguity at a time: term, cardinality, lifecycle, status semantics, deletion/archive behavior.
Immediately update CONTEXT.md for canonical language.
Create ADRs only for costly, surprising trade-offs.
Generate PRD/issues after the language stabilizes.
During implementation review, search for glossary violations and stale synonyms.
After shipping, prune or correct any glossary term that the implementation invalidated.

My read / why it matters

This is one of the more practically useful “AI coding skills” videos because it moves attention away from clever prompting and toward durable project memory. The actual win is not the skill name; it is the discipline of converting conversation into a thin, maintained domain model.

The danger is documentation cargo culting. If CONTEXT.md becomes a junk drawer, it will make the agent worse. Keep it boring: terms, relationships, and explicit naming constraints. Put decisions in ADRs. Put implementation steps in PRDs/issues. That separation is the whole trick.

Verification notes

Four verification passes were applied before replacing the draft packet: source/evidence audit, transcript/comment/frame fidelity audit, hallucination/overclaim audit, and Actionable Insights audit. The source audit checked creator-authored evidence against the upstream mattpocock/skills repo, the raw grill-with-docs skill file, DDD summaries, and ADR references. The fidelity audit tied timestamped claims to the extracted transcript and keyframe JSON, and screen claims were grounded in visual analysis of the retained frames. The overclaim audit softened token-savings and “magical alignment” claims because the video provides anecdotes and mechanism, not benchmarks. The Actionable Insights audit required each top bullet to include a concrete first step, direct links where available, expected benefit, and caution. Residual uncertainty: no independent controlled benchmark was found for /grill-with-docs; performance benefits should be treated as a workflow hypothesis to measure in each repo.

Actionable Insights audit: expanded to the newer detailed format with fuller implementation notes, evaluation checks, and cautions where the existing evidence supports elaboration.