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 )
When not to use this skill
- Finding refactoring opportunities → use
improve-codebase-architecture
- Writing implementation tickets → use
- General code review → use
Session process
1. Explore domain context
Before grilling, read:
- — existing domain terminology
- — 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
at root, each context has its own
and
.
Create files lazily — only when you have something to write.
ADRs — Only create when all three are true:
- Hard to reverse (meaningful cost to change later)
- Surprising without context (future reader would wonder "why?")
- 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
- Identify the task trigger and expected output.
- Follow the workflow steps in this skill from top to bottom.
- Validate outputs before moving to the next step.
- 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