personal-grill-with-docs

Interviews design decisions in rounds and writes agreed terms to CONTEXT.md and ADRs.

Updated Apr 25, 2026
One-click install
npx skills add https://github.com/kosako/agent-tools --skill personal-grill-with-docs-kosako
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: personal-grill-with-docs
Source: https://github.com/kosako/agent-tools/tree/main/shared/skills/personal-grill-with-docs
Command: npx skills add https://github.com/kosako/agent-tools --skill personal-grill-with-docs-kosako

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Design discussions often lose agreed terminology and hard-to-reverse decisions once the conversation ends. This Skill conducts a rigorous round-based design interview while persisting the agreed domain model into repo-local documents, so glossaries and architectural decisions survive as CONTEXT.md and docs/adr entries. ## Core Features & Use Cases - Round-based frontier interviewing: Groups independent questions into numbered rounds with recommended answers, recomputing the frontier after each reply and challenging vague or contradictory responses. - Inline glossary growth: Detects conflicts between user wording and existing CONTEXT.md definitions, proposes canonical terms, and updates the glossary immediately following CONTEXT-FORMAT.md. - Sparing ADR proposals: Suggests an ADR only when a decision is hard to reverse, surprising without context, and the result of a real trade-off, formatted per ADR-FORMAT.md. - Use Case: While designing an order domain, you mention "cancel" meaning both full cancellation and partial return. The Skill flags the ambiguity, proposes canonical terms, updates CONTEXT.md, and later drafts an ADR when you choose event sourcing for the write model. ## Quick Start Ask the agent to grill your design with docs so the agreed terms go into CONTEXT.md and the key decisions into ADRs.

Frequently Asked Questions about personal-grill-with-docs

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

FAQPage Schema
How do I capture design decisions as ADRs during a discussion?▼

Run a document-producing design interview that proposes an ADR only when a decision is hard to reverse, surprising without context, and the result of a real trade-off. Agreed decisions are written to docs/adr with sequential numbering and a short template.

How to build a ubiquitous language glossary for a domain?▼

Use a glossary-focused interview that flags ambiguous or conflicting terms, proposes canonical wording, and updates CONTEXT.md inline as terms solidify. The file stays a pure glossary with short definitions and avoided synonyms, never implementation details.

When should a design decision become an ADR?▼

A decision becomes an ADR only when all three tests pass: it is hard to reverse, it would surprise a future reader without context, and it resulted from a genuine trade-off between alternatives. Easily reversed or obvious choices like naming conventions are excluded.

What is the difference between personal-grill-with-docs and personal-grill-me?▼

personal-grill-with-docs adds document-producing discipline to the interview, writing agreed terms to CONTEXT.md and decisions to ADRs. personal-grill-me handles artifact-free brainstorming, so use it when no documents should be produced.

Can secrets or private paths be written into generated ADRs?▼

No. Generated CONTEXT.md and ADR files are repo-local public-safe artifacts, so secret paths, absolute paths, internal URLs, and PII are excluded. Only the essence of the decision is recorded, with private material deferred to separate management.