December 12, 2004
Engineering
Shared engineering practices, standards, and delivery guidance.
Engineering practice
Use this section for engineering standards, development workflow, testing, infrastructure, and technical decision records.
Add nested Markdown or MDX files to create focused routes beneath /handbook/engineering/.
flowchart LR
subgraph subgraph1
direction TB
top1[top] --> bottom1[bottom]
end
subgraph subgraph2
direction TB
top2[top] --> bottom2[bottom]
end
%% ^ These subgraphs are identical, except for the links to them:
%% Link *to* subgraph1: subgraph1 direction is maintained
outside --> subgraph1
%% Link *within* subgraph2:
%% subgraph2 inherits the direction of the top-level graph (LR)
outside ---> top2
Matt Pocock’s /grill-me and /grill-with-docs are AI coding agent skills that act like an intense, interactive “plan mode” to stress-test your ideas before you build. While both use the same core grilling interview loop, they differ fundamentally in whether they touch your filesystem. [1, 2, 3]
Direct Comparison
| Feature | /grill-me | /grill-with-docs |
|---|---|---|
| Primary Purpose | Stress-tests a plan or idea through a back-and-forth interview | Aligns you and the agent around code, domain language, and architecture |
| File Persistence | Stateful in-memory only; writes no files to disk | Stateful on disk; writes real files into your repository |
| Glossary & Jargon | Keeps terms in the session context | Writes resolved terms to a GLOSSARY.md or CONTEXT.md file immediately |
| Decision Records | Design choices stay in the chat history | Captures hard design choices as Architectural Decision Records (ADRs) in docs/adr/ |
| Best Used For | Brainstorming, general-purpose thinking, or projects without a codebase (e.g., writing a eulogy, early conceptualization) | Planning changes inside an existing codebase or establishing domain-driven design (DDD) from day one |
Key Differences## 1. File Persistence and Artifacts
- /grill-me is ephemeral. It asks you deep, challenging questions, sharpens your thinking, and helps you articulate your goals, but everything lives and dies inside your chat session. [1, 3, 4, 5]
- /grill-with-docs is stateful and writes to your repository. As terms get defined, it updates a GLOSSARY.md or CONTEXT.md file. When a major architectural decision passes its criteria, it logs it as an ADR (docs/adr/). [1, 4]
2. Domain-Driven Design (DDD) & Ubiquitous Language
- /grill-with-docs explicitly pairs the grilling interview with domain-modeling skills. It forces you and the AI to agree on a shared, non-ambiguous vocabulary so that future prompts, variable names, and generated code match your domain accurately. [1, 4]
3. Workflow Placement
- /grill-me is a general productivity or early-stage mental sandbox.
- /grill-with-docs sits at the very head of a structured engineering build chain: /grill-with-docs → /to-spec → /to-tickets → implement → code-review → retro. [1, 3]
To learn more about setting up these tools, check out the Matt Pocock Skills Repository. [1] Are you planning to use these skills inside a brand new project or an existing codebase? Tell me what you’re working on, and I can help you pick the right flow.
[1] https://www.aihero.dev [2] https://www.youtube.com [3] https://re-cinq.com [4] https://www.youtube.com [5] https://www.youtube.com