mirror of https://github.com/alirezarezvani/claude-skills.git synced 2026-09-05 08:05:57 +00:00

feat(engineering): install grill-with-docs skill (Matt Pocock derivative, MIT)

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

2026-05-15 13:08:31 +00:00

3.3 KiB

Raw Permalink Blame History

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 (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

# 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).

3.3 KiB Raw Permalink Blame History