Grill With Docs
Paste the following prompt into your AI chat to install this skill:
Please install @user_3c6cb52e/grill-with-docs according to https://skillhub.cn/install/skillhub.md.
About this skill
Solving "Semantic Drift" and "Doc-Code Disconnect"
In complex system architecture, developers often face fuzzy terminology, missing context, and code implementations that contradict design intent. Traditional design reviews often remain superficial, failing to resolve underlying dependencies. grill-with-docs addresses these specific pain points—unclear decision dependencies, inconsistent domain terms, and doc-code misalignment—by enforcing a rigorous interview process that forces designers to clarify all boundaries before implementation.
Core Capabilities and Key Steps
This skill combines Matt Pocock's interview discipline with deterministic stdlib validators to form a structured workflow:
- Deep, One-by-One Interrogation: Asks only one question per turn, traversing the design tree depth-first. It resolves decision dependencies sequentially and provides recommended answers for each.
- Term Sharpening & Alignment: Continuously cross-references CONTEXT.md. If a user's term conflicts with existing definitions or is vague, it immediately calls it out and proposes a precise canonical term.
- Scenario Stress-Testing & Code Cross-Referencing: Probes boundary conditions by inventing edge-case scenarios. It also explores the codebase to verify the user's claims, surfacing contradictions (e.g., code cancels entire Orders, but the user claims partial cancellation is possible).
- Inline Updates & Cautious ADRs: Resolved terms are updated in CONTEXT.md immediately, keeping it strictly as a glossary (no implementation details). An ADR is only suggested when three conditions are met: it is hard to reverse, surprising without context, and the result of a real trade-off.
- Stdlib Validators: Includes context_md_linter.py, adr_scanner.py, and glossary_code_consistency.py to validate glossary formatting, ADR numbering integrity, and consistency between defined terms and codebase usage.
Boundaries and Caveats
This skill is highly dependent on clear domain models and bounded contexts, making it ideal for the design phase of medium-to-large complex systems. Keep in mind that CONTEXT.md must remain pure; it should never be used as a spec sheet or scratchpad. For simple CRUD applications or one-off scripts, this level of interview depth and documentation constraint may be overkill.
Use Cases
- Before refactoring order cancellation, use one-question-at-a-time interviewing to trace partial cancellation, refunds, and inventory release dependencies.
- When the team mixes up “account,” “user,” and “customer,” sharpen terms against CONTEXT.md and update the glossary inline.
- When code cancels the whole Order while notes claim partial cancellation, cross-reference code to expose the contradiction and decide the correct behavior.
- Before writing an ADR, check whether the decision is hard to reverse, surprising without context, and the result of a real trade-off.
Best For
- Backend engineers designing complex domain models in payments, orders, or inventory, needing to pressure-test each design decision.
- Architects adding features to legacy systems, needing to reconcile existing terminology, code behavior, and documentation before coding.
- Engineers using AI agents for design reviews, needing to prevent agents from jumping into implementation before domain boundaries are clear.
- Tech leads maintaining ADRs and CONTEXT.md, needing to keep the glossary pure and validate its format.
Related Skills
Collects daily conversations, task logs, and errors, then runs a nine-module review to surface blind spots, generate actions, and update memory.
Local long-term memory for AI agents that appends key facts and daily logs, supports cross-session context and search recall, and auto-archives old diaries to gzip files.
Run a grilling session to interact with or test AI agents.
A systematic prompt optimization skill that refines prompts using a four-step distillation framework (diagnose, structure, think, compress) and methodologies from four prompting masters.