grill-with-docs

name	grill-with-docs
description	Use this skill when > Design review session that stress-tests plans against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallize. Use when validating architecture or plans against a project's language and documented decisions.
allowed-tools	Read Grep Glob Bash Write Edit
compatibility	Works best in codebases with CONTEXT.md and docs/adr/ documentation. Creates these files lazily if absent. Pairs with improve-codebase-architecture for architectural work and triage for issue preparation.
metadata	{"tags":"design-review, architecture, domain-model, documentation, adr, context-map","platforms":"Claude, ChatGPT, Gemini, Codex","version":"1.0","source":"mattpocock/skills"}

Grill With Docs

A grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation inline as decisions crystallize.

When to use this skill

• Validating architectural plans against a project's domain language
• Stress-testing designs before implementation
• Updating CONTEXT.md terminology as new concepts emerge
• Preparing issues for implementation (pairs with triage)

When not to use this skill

• Finding refactoring opportunities → use improve-codebase-architecture
• Writing implementation tickets → use to-issues
• General code review → use code-review

Session process

1. Explore domain context

Before grilling, read:

• CONTEXT.md — existing domain terminology
• docs/adr/ — prior architectural decisions
• Relevant source files to understand current state

2. Run the grilling loop

Interview relentlessly about every decision point. For each question:

• Provide a recommended answer
• Ask one question at a time, waiting for feedback before continuing
• Explore the codebase instead of asking when the answer is findable there

3. Three stress-test mechanisms

Glossary alignment — When the user uses a term that conflicts with CONTEXT.md, call it out:

"Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"

Precision sharpening — When terms are vague or overloaded, propose canonical names:

"You're saying 'account' — do you mean the Customer or the User? Those are different things."

Scenario-based edge-case testing — When domain relationships are discussed, stress-test with concrete scenarios that probe boundaries between concepts.

4. Update docs inline

CONTEXT.md — When a term is resolved, update it immediately. Don't batch updates.

File structure for single-context repos:

/
├── CONTEXT.md
├── docs/
│   └── adr/
│       └── 0001-decision-name.md

For monorepos with CONTEXT-MAP.md at root, each context has its own CONTEXT.md and docs/adr/.

Create files lazily — only when you have something to write.

ADRs — Only create when all three are true:

1. Hard to reverse (meaningful cost to change later)
2. Surprising without context (future reader would wonder "why?")
3. Result of a real trade-off (genuine alternatives existed)

If any condition is missing, skip the ADR.

Cross-reference with code

When the user states how something works, verify the code agrees. Surface contradictions:

"Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"

File formats

• CONTEXT.md: domain terminology meaningful to domain experts (no implementation details)
• ADR format: title, status, context, decision, consequences

Instructions

1. Identify the task trigger and expected output.
2. Follow the workflow steps in this skill from top to bottom.
3. Validate outputs before moving to the next step.
4. Capture blockers and fallback path if any step fails.

Examples

• Example: Apply this skill to a small scope first, then scale to full scope after validation passes.

Best practices

• Keep outputs deterministic and auditable.
• Prefer small reversible changes over broad risky edits.
• Record assumptions explicitly.

References

• Project standards: .agent-skills/skill-standardization/SKILL.md
• Validator script: .agent-skills/skill-standardization/scripts/validate_skill.sh