loading…

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 on the 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.

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, grilling doctrine, idea to ship flow, context engineering, ai coding taxonomy.