grill-with-docs

Interviews users to sharpen plans and generates ADRs and glossary documentation.

1|2|Updated Nov 25, 2017
One-click install
npx skills add https://github.com/asarchami/dotfiles --skill grill-with-docs-asarchami
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: grill-with-docs
Source: https://github.com/asarchami/dotfiles/tree/main/dot_config/opencode/skills/grill-with-docs
Command: npx skills add https://github.com/asarchami/dotfiles --skill grill-with-docs-asarchami

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Plans and designs often contain fuzzy language, unresolved trade-offs, and undocumented decisions that cause confusion later. This Skill conducts a relentless one-question-at-a-time interview to pin down every aspect of a plan while capturing decisions and terminology as durable documentation. ## Core Features & Use Cases - Structured Requirements Interview: Walks down each branch of the design tree, asking one question at a time with a recommended answer, and explores the codebase directly when answers live in the code. - Living Glossary: Maintains spec/glossary.md with opinionated domain terminology, flagged ambiguities, and relationship definitions, updated inline as terms are resolved. - Selective ADRs: Creates Architecture Decision Records in spec/adr/ only when a decision is hard to reverse, surprising without context, and the result of a real trade-off. - Use Case: While designing a trading bot, the Skill challenges whether "bar" means OHLCV data or a tick, records the resolution in the glossary, and offers an ADR when you choose a specific message bus over alternatives. ## Quick Start Ask the AI to grill you on your current design plan and document the decisions and terminology as you go.

Frequently Asked Questions about grill-with-docs

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

FAQPage Schema
How do I turn a vague design discussion into documented decisions?

Run a structured interview that asks one question at a time, provides a recommended answer for each, and records resolved trade-offs as Architecture Decision Records in spec/adr/ while capturing terminology in spec/glossary.md.

What is an Architecture Decision Record and when should I write one?

An ADR is a short document recording that a decision was made and why. Write one only when the decision is hard to reverse, surprising without context, and the result of a genuine trade-off between alternatives.

How do I maintain a domain glossary for a software project?

Keep a spec/glossary.md file with one-sentence definitions, aliases to avoid, term relationships, and flagged ambiguities. Update it inline as terms are resolved during discussions rather than batching changes.

Does this interview process check answers against the actual codebase?

Yes. When a question can be answered by exploring the codebase, the Skill explores instead of asking, and it cross-references user statements against the code to surface contradictions.

When should I not create an ADR?

Skip the ADR if the decision is easily reversible, obvious to a future reader, or had no real alternatives. Trivial or self-evident choices do not belong in spec/adr/.