Grill with Docs — Development

Grill with Docs runs a docs-anchored grilling session that challenges a plan against the project's existing language in CONTEXT.md and recorded decisions in docs/adr/, updating those files inline as terminology and decisions crystallise. It combines Matt Pocock's relentless one-at-a-time interview style with deterministic stdlib validators to keep the glossary and ADRs consistent.

engineering claude-code

📂 View skill on GitHub ↗ 🚀 How to use

✨ What it does

Interviews one question at a time, walking the design tree depth-first.
Challenges terms against CONTEXT.md and sharpens fuzzy language.
Cross-references stated behaviour with the codebase.
Updates CONTEXT.md inline as terms are resolved.
Offers ADRs only when hard to reverse, surprising, and a real trade-off.
Runs stdlib validators: CONTEXT.md linter, ADR scanner, glossary↔code consistency.

🎯 When to use it

When you want to stress-test a plan against the project's documented domain language.
When you mention 'grill with docs' or want a docs-anchored grilling session.
When you need to refine ambiguous terminology and record decisions as ADRs.
When you want to ensure the codebase and documentation stay consistent.

🚀 How to use

Trigger: /cs:grill-with-docs

Trigger with the slash command /cs:grill-with-docs or by asking to 'grill with docs' on a plan. Provide the plan and ensure the repo has CONTEXT.md and docs/adr/ if they exist; the skill will explore the codebase and ask questions one at a time. Example prompts:

/cs:grill-with-docs
Grill my plan for the new billing system with docs.

📄 Output: Updates to CONTEXT.md and docs/adr/ plus a summary of terms added/refined, ADRs written, scenarios discussed, and open items.

📦 Add this skill to Claude Code

# 1. Get the skills repo
git clone --depth 1 https://github.com/alirezarezvani/claude-skills /tmp/claude-skills

# 2. Copy this skill into your project (or ~/.claude/skills for all projects)
mkdir -p .claude/skills
cp -r /tmp/claude-skills/engineering/grill-with-docs/skills/grill-with-docs .claude/skills/grill-with-docs

Skill source: engineering/grill-with-docs/skills/grill-with-docs/SKILL.md

⚠️ Good to know

Requires a codebase with existing documentation (CONTEXT.md and docs/adr/) to be most effective; files are created lazily only when needed.

❓ FAQ

When should an ADR be created?

Only when all three criteria are met: hard to reverse, surprising without context, and the result of a real trade-off.

What does the CONTEXT.md linter do?

It validates CONTEXT.md against the CONTEXT-FORMAT.md structure, reporting PASS/WARN/FAIL per rule.

How does the skill handle multiple contexts?

If a CONTEXT-MAP.md exists, it points to each context's location, and the skill updates the appropriate CONTEXT.md files.

🤖 Overview, features, install steps and FAQ were generated from the project's SKILL.md on Sep 4, 2026. Always check the original source before running commands.