grill-with-docs

Interrogates plans against domain glossaries and records decisions in CONTEXT.md and ADR files.

Updated Nov 23, 2024
One-click install
npx skills add https://github.com/tokisakiyuu/dotfiles --skill grill-with-docs-tokisakiyuu
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: grill-with-docs
Source: https://github.com/tokisakiyuu/dotfiles/tree/main/home/dot_claude/skills/grill-with-docs
Command: npx skills add https://github.com/tokisakiyuu/dotfiles --skill grill-with-docs-tokisakiyuu

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Plans often embed fuzzy terminology and undocumented trade-offs that later confuse teams. This Skill stress-tests a plan through relentless one-at-a-time questioning, challenges it against the project's existing domain language, and captures resolved terms and decisions as living documentation. ## 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. - Ubiquitous language enforcement: Challenges terms that conflict with CONTEXT.md, sharpens vague wording into canonical terms, and updates the glossary inline as terms are resolved. - Decision capture via ADRs: Offers to write numbered ADRs in docs/adr/ only when a decision is hard to reverse, surprising without context, and the result of a real trade-off. - 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 chosen approach 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 coding?▼

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

How to maintain a ubiquitous language glossary in a repo?▼

Keep a CONTEXT.md at the repo root defining canonical domain terms with aliases to avoid, relationships, and an example dialogue. Update it inline whenever a term is resolved during design discussions rather than batching changes.

When should I write an Architecture Decision Record?▼

Write an ADR only when a decision is hard to reverse, surprising without context, and the result of a genuine trade-off between alternatives. If any of the three conditions is missing, skip the ADR to avoid documentation noise.

Does this 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, with per-context CONTEXT.md and docs/adr/ directories. The Skill infers which context the current topic belongs to and asks when unclear.

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

It depends on the user answering questions honestly and on the codebase reflecting actual behavior; contradictions are only surfaced when code and statements disagree. It also deliberately skips easy-to-reverse or obvious decisions, so it does not produce exhaustive documentation.