Grill-with-Docs: Making Planning and Documentation Inseparable
Why relentless interrogation during design sessions should produce ADRs and glossaries as a byproduct, not separate work.
The Documentation Deference Problem
Here's how most planning sessions go:
You discuss the design. You nod along. You approve it. Then someone says, "We should document this," and that work gets deferred. A week later, nobody remembers why certain decisions were made. Three months later, someone asks, "Wait, why did we choose this approach?" and the only answer is a two-line commit message.
This isn't a discipline problem. It's a workflow problem. Documentation doesn't happen after planning—it never happens at all.
What Grill-with-Docs Does
Matt Pocock's skill flips the workflow. Instead of planning then documenting, it grills while documenting.
During the design interrogation, the skill simultaneously:
- Asks relentless questions: What happens if X? Have you considered Y? What breaks if Z?
- Surfaces assumptions: Why this database? Why not that one? What's the trade-off?
- Forces precision: Vague terms become precise. Hasty decisions get stress-tested.
- Writes artifacts: Architecture Decision Records. Domain glossary. Deployment model. All emerge as byproducts.
By the time the session ends, you haven't just made better decisions—you've also produced the reference documentation that will explain those decisions to the next person reading the code.
Why This Works
Documentation is hardest to write weeks after the decision. You've moved on. Context has evaporated. You're reconstructing from memory instead of capturing from thought.
But in the heat of the decision, when you're defending your choice against hard questions, you're doing the intellectual work that documentation should capture. The insight worth stealing: documentation is most useful when written in the moment of maximum understanding.
The Deeper Lesson
Most teams treat documentation and planning as sequential: plan first, document later. But planning is the documentation work—it's just happening in a conversation instead of in prose. Collapsing that gap is the optimization.
The specific tool isn't the point. The principle is: wherever decisions crystallize, documentation should crystallize alongside them. Make that automatic, and you've solved the documentation debt problem that haunts every engineering organization.