grill-with-docs

Challenges plans against domain glossaries and updates CONTEXT.md and ADR documentation inline.

1|Updated Mar 12, 2025
One-click install
npx skills add https://github.com/void2610/dotfiles --skill grill-with-docs-void2610
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: grill-with-docs
Source: https://github.com/void2610/dotfiles/tree/main/.claude/skills/grill-with-docs
Command: npx skills add https://github.com/void2610/dotfiles --skill grill-with-docs-void2610

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Plans often contain fuzzy terminology, contradictions with existing code, and undocumented decisions that cause confusion later. This Skill stress-tests a plan through relentless one-at-a-time questioning while keeping the project's glossary and architecture decision records synchronized as decisions crystallize. ## Core Features & Use Cases - Socratic plan interrogation: Walks each branch of the design tree, asking one question at a time with a recommended answer, and explores the codebase directly when a question can be answered there. - Terminology sharpening: Challenges terms that conflict with CONTEXT.md, proposes canonical vocabulary with Avoid lists, and updates the glossary inline as terms are resolved. - Selective ADR creation: Offers an Architecture Decision Record 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: While planning a partial order cancellation feature, the Skill notices the code cancels entire Orders, surfaces the contradiction, resolves the term 'cancellation' into CONTEXT.md, and records the trade-off as ADR 0003. ## Quick Start Ask the assistant to grill you on your implementation plan for a new feature and update the project's CONTEXT.md and ADRs as decisions are made.

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 implementing it?▼

Run a grilling session that interviews you about every branch of the design tree, one question at a time, with a recommended answer for each. Questions answerable from the codebase are resolved by exploring the code directly instead of asking.

How to keep a project glossary of domain terms consistent?▼

Maintain a CONTEXT.md file with tight one-to-two sentence definitions and _Avoid_ lists for rejected synonyms. Update it inline the moment a term is resolved during discussion rather than batching changes later.

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 record.

Does this approach work with multiple bounded contexts in one repo?▼

Yes. A CONTEXT-MAP.md at the repo root lists each context, its location, and its relationships, while each context keeps its own CONTEXT.md and context-specific docs/adr/ directory. System-wide decisions live in the root docs/adr/.

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

It depends on the user answering questions honestly and on the codebase being explorable for verification. It does not execute or test code, so runtime behavior and performance characteristics remain unvalidated.