grill-with-docs

Stress-tests plans against domain glossaries and records decisions in CONTEXT.md and ADR files.

Updated Jun 30, 2026
One-click install
npx skills add https://github.com/santoshkal/chezmoi --skill grill-with-docs-santoshkal
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: grill-with-docs
Source: https://github.com/santoshkal/chezmoi/tree/main/private_dot_config/opencode/skills/grill-with-docs
Command: npx skills add https://github.com/santoshkal/chezmoi --skill grill-with-docs-santoshkal

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Plans often embed fuzzy terminology and undocumented trade-offs that later confuse teams or get silently reversed. This Skill runs a structured interrogation of your plan against your project's existing domain language and documented decisions, capturing resolved terms and hard-to-reverse choices as documentation while the discussion happens. ## Core Features & Use Cases - Socratic plan review: Asks one question at a time, walking each branch of the design tree and providing a recommended answer for every question. - Terminology enforcement: Challenges terms that conflict with the project glossary in CONTEXT.md, sharpens vague language into canonical terms, and updates the glossary inline as terms are resolved. - Decision recording: Offers Architecture Decision Records only when a decision is hard to reverse, surprising without context, and the result of a real trade-off, using sequential numbering in docs/adr/. - Use Case: Before implementing a new billing feature, run a grilling session to reconcile your plan with the existing CONTEXT.md definitions of Invoice and Customer, then capture the decision to use domain events instead of synchronous HTTP as ADR 0003. ## Quick Start Ask the assistant to grill your implementation plan for a new feature against the project's CONTEXT.md and existing ADRs before writing any code.

Frequently Asked Questions about grill-with-docs

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I stress-test a software design plan before implementation?▼

Run a grilling session that interviews you about every aspect of the plan, one question at a time, with a recommended answer for each. Questions that can be answered by exploring the codebase are resolved through code exploration instead of asking you.

What is a CONTEXT.md file in a software project?▼

CONTEXT.md is a domain glossary at the repo root defining project-specific terms with one or two sentence definitions and avoided synonyms. It contains no implementation details and is updated inline whenever a term is resolved during design discussions.

When should I write an Architecture Decision Record?▼

Write an ADR only when all three conditions hold: the decision is hard to reverse, it is surprising without context, and it resulted from a real trade-off between genuine alternatives. If any condition is missing, skip the ADR.

How do I handle multiple bounded contexts in one repository?▼

Create a CONTEXT-MAP.md at the repo root listing each context, its location, and its relationships, with a separate CONTEXT.md per context directory. System-wide ADRs live in the root docs/adr folder while context-specific decisions live beside each context.

What are the limitations of documentation-driven plan review?▼

The session depends on existing documentation being accurate, so contradictions between code and docs must be surfaced and resolved manually. It also deliberately avoids recording easy-to-reverse or obvious decisions, so it is not a substitute for full design specifications.