grill-with-docs

Interviews users to stress-test plans against domain glossaries and records decisions in CONTEXT.md and ADRs.

11|2|Updated Dec 29, 2025
One-click install
npx skills add https://github.com/oskrgab/petrodb --skill grill-with-docs-oskrgab
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: grill-with-docs
Source: https://github.com/oskrgab/petrodb/tree/main/.agents/skills/grill-with-docs
Command: npx skills add https://github.com/oskrgab/petrodb --skill grill-with-docs-oskrgab

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Plans often embed fuzzy terminology and undocumented decisions that later cause confusion or get silently reversed. This Skill runs a structured interrogation of your plan against your project's existing domain language and architecture decision records, sharpening terms and capturing decisions as they crystallise. ## 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 CONTEXT.md, proposes canonical names for vague language, and updates the glossary inline as terms are resolved. - Decision capture: Offers Architecture Decision Records only when a decision is hard to reverse, surprising without context, and the result of a real trade-off. - Use Case: Before implementing a partial order cancellation feature, run a grilling session to reconcile the plan with the existing Order/Invoice glossary, probe edge cases with concrete scenarios, and record the cancellation semantics in an ADR. ## Quick Start Start a grilling session on my plan for the new billing workflow and update CONTEXT.md and ADRs as we resolve decisions.

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 one question at a time about every branch of the design tree. Each question comes with a recommended answer, and questions answerable from the codebase are resolved by exploring the code directly.

How do I keep domain terminology consistent across a project?

Maintain a CONTEXT.md glossary that defines canonical terms, lists words to avoid, and flags ambiguities. During design discussions, conflicting usage is called out immediately and resolved terms are written into the glossary inline.

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 alternatives. Decisions failing any condition are skipped to avoid documentation noise.

Does this work with multiple bounded contexts in one repo?

Yes. A root CONTEXT-MAP.md lists each context, its location, and its relationships, with per-context CONTEXT.md and docs/adr directories. The session infers which context the current topic belongs to and asks when unclear.

What are the limitations of a questioning-based plan review?

The review depends on the user's answers and existing documentation, so undocumented implicit knowledge may be missed. It also creates files lazily, meaning repos without prior CONTEXT.md or ADRs start with no baseline to challenge against.