---
title: "Grill With Docs"
description: "Stateful interactive alignment skill that captures domain vocabulary into CONTEXT.md and three-gated decisions into ADRs."
section: "concepts"
type: "concept"
created: "2026-08-30"
updated: "2026-08-30"
confidence: "high"
tags: ["workflow", "agents", "context-engineering", "skills"]
canonical: "https://pyweb.dev/wiki/grill-with-docs"
---
# Grill With Docs

`grill-with-docs` is the stateful head of the main agentic engineering flow (`grill-with-docs -> to-spec -> to-tickets -> implement -> code-review`). Developed by [matt pocock](/wiki/matt-pocock) on the [grilling doctrine](/wiki/grilling-doctrine) primitive, it conducts a conversational interview to establish shared human-agent understanding while progressively persisting domain terminology and architectural decisions directly to repository files.

## Operational Architecture

Unlike ephemeral grilling (`/grill-me`), which leaves alignment only in the transient context window, `grill-with-docs` pairs two underlying primitives:
1. **Interview Driver:** `grilling` — conducts turn-by-turn question loops focused on the decision frontier.
2. **Persistence Engine:** `domain-modeling` — writes resolved vocabulary and architecture decisions to disk lazily as they crystallize.

```mermaid
flowchart TD
    A[Human triggers /grill-with-docs] --> B[Grilling Interview Engine]
    B --> C{Output Type}
    C -->|Domain Term| D[CONTEXT.md Glossary]
    C -->|3-Gated Decision| E[docs/adr/ ADR]
    C -->|Conversational Detail| F[Context Window]
    F --> G[to-spec Synthesis]
    D --> H[Downstream Agent Sessions]
    E --> H
    G --> I[Executable Spec]
```

## The Three Output Tiers

During a session, resolved items are routed strictly according to their artifact class:

| Resolved Artifact | Destination | Criteria & Constraints |
|---|---|---|
| **Domain Term** | `CONTEXT.md` (root or multi-context map) | Written immediately inline as it resolves; strictly pure vocabulary with tight definitions (no spec or scratch notes). |
| **Architecture Decision** | `docs/adr/` (Architecture Decision Record) | Must satisfy all 3 gates: **hard to reverse**, **surprising without context**, and represents a **real trade-off**. |
| **Conversational Decisions** | Context window only | Nuances, defaults, and ordering guarantees that must be handed directly to `to-spec` before session clearing. |

## Selection Matrix

Choosing the right alignment skill depends on repository state and session scope:

| Context & Scope | Recommended Skill |
|---|---|
| No working directory / standalone concept | `grill-me` |
| Repository change settled in a single session | `grill-with-docs` |
| Greenfield build or multi-session initiative | `wayfinder` (decomposes into decision tickets) |
| Undocumented repository with no immediate feature | `grill-with-docs` (paired with `improve-codebase-architecture`) |
| Blocked on external stakeholder knowledge | `to-questionnaire` |

## Failure Modes & Diagnostics

1. **Silent Non-Writing (Wrapper Bug):** When executed within nested orchestration layers, file writes may be suppressed while the interview continues. Requires verifying disk modifications before trusting completion.
2. **Dependency Loading Failure:** If either `grilling` or `domain-modeling` fails to load, the agent either dumps questions in an undifferentiated batch or runs an ephemeral interview without disk persistence.
3. **Downstream Decision Softening:** Because conversational decisions do not land in `CONTEXT.md` or ADRs, relying on memory across sessions without running `to-spec` causes loss of numeric constraints and negative requirements.

## Related
[matt pocock](/wiki/matt-pocock), [grilling doctrine](/wiki/grilling-doctrine), [idea to ship flow](/wiki/idea-to-ship-flow), [context engineering](/wiki/context-engineering), [ai coding taxonomy](/wiki/ai-coding-taxonomy).

---

## Agent Navigation

cluster: person (170 pages) | betweenness: 0

### References (outbound)
- [Matt Pocock](https://pyweb.dev/wiki/matt-pocock.md)

### Evidence (verified primary sources)
- [aihero-skills-grill-with-docs-2026](https://pyweb.dev/wiki/raw/articles/aihero-skills-grill-with-docs-2026.md) | origin: https://aihero.dev/skills-grill-with-docs | ingested: 2026-08-30 | sha256: a1c76c63f7d7976e2392b8f04312e682c38ca86abd8a54d61894ce8e96d887c9
- [aihero-ai-coding-dictionary-2026](https://pyweb.dev/wiki/raw/articles/aihero-ai-coding-dictionary-2026.md) | origin: https://www.aihero.dev/ai-coding-dictionary | ingested: 2026-08-27 | sha256: 52b0a5da7c9f6dd60dfdbf29031bcf6107c2765b6ef5b3a7f96cc607f42b06c7
- [aihero-dev-homepage-2026](https://pyweb.dev/wiki/raw/articles/aihero-dev-homepage-2026.md) | origin: https://www.aihero.dev/ | ingested: 2026-08-22 | sha256: 231157fed45f82922924a050e09b5b81a443891814fc1d72c874d864a6075419

### Machine endpoints
- Knowledge graph: https://pyweb.dev/api/graph.json
- Graph analysis: https://pyweb.dev/api/graph-analysis.json
- Context index: https://pyweb.dev/llms.txt