mirror of
https://github.com/alirezarezvani/claude-skills.git
synced 2026-10-10 03:27:56 +00:00
30ea6342e5
Installs Matt Pocock's grill-with-docs skill as the fifth Matt-derived plugin in this repo, following the v2.6.0 hybrid-voice import pattern established by write-a-skill / caveman / grill-me / handoff. Upstream: https://github.com/mattpocock/skills/tree/main/skills/engineering/grill-with-docs License: MIT, © 2026 Matt Pocock. Preserved verbatim per MIT. WHAT THE SKILL DOES Docs-anchored grilling session. Where the existing grill-me skill interrogates a plan in isolation, grill-with-docs interrogates a plan against the project's existing language (CONTEXT.md) and recorded decisions (docs/adr/), updating both inline as terminology and decisions crystallise during the session. Matt's three SKILL.md rules preserved verbatim under MIT: - Interview relentlessly, one question per turn, walking the decision tree depth-first. - When a term is sharpened, update CONTEXT.md right there (don't batch). Use the format in CONTEXT-FORMAT.md. - Offer an ADR only when all three are true: hard to reverse, surprising without context, real trade-off. Use the format in ADR-FORMAT.md. REPO STRUCTURE (mirrors grill-me's 1:1) engineering/grill-with-docs/ ├── .claude-plugin/plugin.json ├── README.md ├── agents/cs-grill-with-docs.md ├── commands/cs-grill-with-docs.md └── skills/grill-with-docs/ ├── SKILL.md ← Matt's voice verbatim ├── ADR-FORMAT.md ← Matt's, verbatim ├── CONTEXT-FORMAT.md ← Matt's, verbatim ├── references/ │ ├── ubiquitous_language.md ← 7 sources │ ├── adr_practice.md ← 7 sources │ └── context_md_as_artifact.md ← 7 sources └── scripts/ ├── context_md_linter.py ← stdlib ├── adr_scanner.py ← stdlib └── glossary_code_consistency.py ← stdlib WRAPPER (additions on top of upstream) 1. context_md_linter.py — validates CONTEXT.md against the CONTEXT-FORMAT.md structure: H1, one-sentence description, Language section with bold terms + `_Avoid_:` aliases, Relationships, Example dialogue, optional Flagged ambiguities. PASS/WARN/FAIL per rule. Smoke-tested: positive case PASS 7/7, negative case (broken file) correctly FAILs with 4 WARNs identifying every missing element. 2. adr_scanner.py — walks docs/adr/, checks NNNN-slug.md filename pattern, surfaces numbering gaps + duplicates, validates H1 + body on each ADR, sanity-checks optional status frontmatter, verifies "superseded by ADR-NNNN" targets exist. Smoke-tested: positive case PASS 12/12 on 3 sequential ADRs; negative case (gap + malformed filename + 2-word body) correctly FAILs and surfaces every issue. 3. glossary_code_consistency.py — extracts bold terms from CONTEXT.md, greps codebase, flags two grilling-question seeds: (a) DEAD GLOSSARY — terms defined but never used in code; (b) CODE-ONLY PROPER NOUNS — frequent capitalized identifiers in code that the glossary doesn't define (filtered against a stop-list of generic programming terms). Tunable threshold via --min-frequency. Smoke-tested: sample correctly flags 'Discount' (dead glossary) and 'Subscription' (code-only, at threshold 2). REFERENCES (each cites 7 authoritative sources) - ubiquitous_language.md — Evans (DDD blue book), Vernon (red book), Khononov (Learning DDD), Wlaschin (DDD Made Functional), Brandolini (EventStorming), Avram & Marinescu (DDD Quickly), Fowler bliki. - adr_practice.md — Nygard (2011 ADR essay), Tyree & Akerman (IEEE Software 2005), Zimmermann Y-statements, MADR template, ThoughtWorks Tech Radar, Joel Parker Henderson adr-tools, Spotify Backstage. - context_md_as_artifact.md — Khononov on language drift, Kernighan on naming, Fowler BoundedContext bliki, Fowler UbiquitousLanguage bliki, Confluent data contracts, Brandolini EventStorming, Evans on Conformist / Anticorruption Layer (DDD ch 14). AGENT + COMMAND - cs-grill-with-docs (engineering, opus model) — docs-aware grill persona. Pre-flights the 3 linters before the first question, uses their findings as opening question seeds, enforces the inline-edit + ADR-3-criteria-gate rules. - /cs:grill-with-docs <path-to-plan> — slash invocation. Six forcing-question patterns surfaced (glossary conflict, ADR contradiction, undefined term, code-vs-claim, ADR 3-criteria gate, boundary check). DIFFERENTIATION FROM SIBLING SKILLS - vs grill-me: grill-me grills a plan in a vacuum; grill-with-docs grills against CONTEXT.md + docs/adr/ + codebase. Both ship as separate plugins. - vs caveman: different concern (depth-against-docs vs compression). - vs handoff: different mode (interrogate vs continuation). VERIFIED CLEAN - All 3 scripts pass `--help`, `--sample`, and JSON-output round-trip. - All 3 scripts correctly FAIL on deliberately broken inputs. - plugin.json parses as valid JSON, schema matches CLAUDE.md constraints (name, description, version, author, homepage, repository, license, skills, attribution — no extra fields). - MIT attribution present in: SKILL.md frontmatter + body header, ADR-FORMAT.md HTML comment, CONTEXT-FORMAT.md HTML comment, all 3 reference doc citations sections, plugin.json attribution block, README.md Attribution + License sections, agent + command footers. - File-tree mirrors grill-me's layout 1:1. TOTAL FOOTPRINT 13 files, 1,747 lines (3 markdown specs verbatim from Matt + 3 references + 3 stdlib scripts + 4 wrapper files). Comparable to grill-me's 11 files / 1,205 lines, larger by the weight of the 2 format files Matt ships upstream (ADR-FORMAT + CONTEXT-FORMAT, ~135 lines) and the heavier linter logic this skill requires. https://claude.ai/code/session_01FEUmeuYhmnxVFq7EZM8ZSw
53 lines
3.3 KiB
Markdown
53 lines
3.3 KiB
Markdown
# grill-with-docs
|
|
|
|
Docs-anchored grilling session. Walks the decision tree of a plan one branch at a time, but does so against the project's existing **language** (`CONTEXT.md`) and recorded **decisions** (`docs/adr/`). Sharpens terminology + records architecturally-significant decisions inline as they crystallise.
|
|
|
|
## Attribution
|
|
|
|
**Derived from [Matt Pocock's grill-with-docs](https://github.com/mattpocock/skills/tree/main/skills/engineering/grill-with-docs)** (MIT, © 2026 Matt Pocock). Matt's interview discipline + domain-awareness rules preserved verbatim per his MIT license — relentless one-question-at-a-time grilling, codebase-and-docs-first exploration, the three-criterion gate for offering an ADR (hard-to-reverse + surprising-without-context + real-trade-off).
|
|
|
|
## How this differs from `grill-me`
|
|
|
|
| Aspect | `grill-me` | `grill-with-docs` |
|
|
|---|---|---|
|
|
| Grounding | Plan text only | Plan + `CONTEXT.md` + `docs/adr/` + codebase |
|
|
| Output | Session notes | Session notes **plus** inline updates to CONTEXT.md and (when warranted) new ADRs |
|
|
| Question source | Decision tree extracted from plan | Decision tree **plus** language conflicts, fuzzy terms, code-vs-glossary contradictions |
|
|
| When to use | Stress-testing a fresh plan | Onboarding a plan into an established codebase with documented language |
|
|
|
|
Both ship as separate plugins; pick whichever matches the situation. The `grill-me` skill is plan-only; `grill-with-docs` is plan + project memory.
|
|
|
|
## What this adds on top of Matt's original
|
|
|
|
| Addition | Where | Why |
|
|
|---|---|---|
|
|
| **3 stdlib Python tools** | `skills/grill-with-docs/scripts/` | Lint CONTEXT.md format · Walk docs/adr/ for numbering + body integrity · Cross-reference bold terms in CONTEXT.md against codebase usage (dead glossary + code-only common nouns) |
|
|
| **3 in-depth references** (7+ sources each) | `skills/grill-with-docs/references/` | Ubiquitous language canon · ADR practice canon · CONTEXT.md as living artifact |
|
|
| **cs-grill-with-docs persona agent** | `agents/cs-grill-with-docs.md` | Docs-aware grill voice; pre-flights the linters before the first question |
|
|
| **`/cs:grill-with-docs` slash command** | `commands/cs-grill-with-docs.md` | Activation + workflow handoff |
|
|
|
|
## Matt's original (preserved)
|
|
|
|
> "Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. Ask the questions one at a time, waiting for feedback on each question before continuing. If a question can be answered by exploring the codebase, explore the codebase instead."
|
|
|
|
> "Only offer to create an ADR when all three are true: hard to reverse, surprising without context, the result of a real trade-off. If any of the three is missing, skip the ADR."
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
# 1. Lint existing CONTEXT.md (if present)
|
|
python skills/grill-with-docs/scripts/context_md_linter.py CONTEXT.md
|
|
|
|
# 2. Scan existing ADRs (if present)
|
|
python skills/grill-with-docs/scripts/adr_scanner.py docs/adr/
|
|
|
|
# 3. Cross-reference glossary terms against codebase
|
|
python skills/grill-with-docs/scripts/glossary_code_consistency.py \
|
|
--context CONTEXT.md --code src/
|
|
|
|
# 4. Use /cs:grill-with-docs to start the session
|
|
```
|
|
|
|
## License
|
|
|
|
MIT (matching Matt's upstream).
|