Przejdź do treści
Biblioteka skilli
Zarządzanie i produkt · Planowanie

grill-with-docs

/grill-with-docs

Testuje plan względem języka projektu (CONTEXT.md) i zapisanych decyzji (docs/adr/), aktualizując te pliki na bieżąco, gdy krystalizuje się terminologia i decyzje.

Repozytorium
claude-skills ↗
Licencja
MIT
Ostatnia zmiana repozytorium
23.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
9
Skrypty
3
Komentarze HTML
0
Adresy URL w SKILL.md
2
Przestarzałość

Brak sygnałów. Repozytorium zmienione 23.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co sprawdzić przed instalacją
  • 3 skrypty w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

Skrypty: scripts/adr_scanner.py, scripts/context_md_linter.py, scripts/glossary_code_consistency.py

Co robi i kiedy

Testuje plan względem języka projektu (CONTEXT.md) i zapisanych decyzji (docs/adr/), aktualizując te pliki na bieżąco, gdy krystalizuje się terminologia i decyzje.

Wyzwalacze z opisu

grill with docs
Oryginalny opis (EN)

Docs-anchored grilling session — challenges a plan against the project's existing language (CONTEXT.md) and recorded decisions (docs/adr/), and updates those files inline as terminology and decisions crystallise. Use when user wants to stress-test a plan against documented domain language, or mentions "grill with docs".

Jak działa

  1. Domain awareness
  2. During the session
  3. Wrapper Additions
Sekcje z nagłówków SKILL.md, w oryginale · 133 linii, 861 słów
Podgląd SKILL.md
---
name: grill-with-docs
description: Docs-anchored grilling session — challenges a plan against the project's existing language (CONTEXT.md) and recorded decisions (docs/adr/), and updates those files inline as terminology and decisions crystallise. Use when user wants to stress-test a plan against documented domain language, or mentions "grill with docs".
license: MIT
metadata:
  derived_from: "https://github.com/mattpocock/skills/tree/main/skills/engineering/grill-with-docs"
  original_author: "Matt Pocock (@mattpocock)"
  original_license: MIT
  voice: "Matt Pocock — relentless, one-at-a-time, codebase-and-docs-first, ADRs only when 3 criteria are met"
  version: 1.0.0
---

# Grill with Docs

> 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 + docs-anchored grilling rules preserved verbatim under MIT. Additions in this repo: 3 stdlib validators (CONTEXT.md linter, ADR scanner, glossary↔code consistency check), 3 in-depth references each citing 7+ authoritative sources, `cs-grill-with-docs` agent, `/cs-grill-with-docs` command. See [Wrapper additions](#wrapper-additions) below.

<what-to-do>

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.

</what-to-do>

<supporting-info>

## Domain awareness

During codebase exploration, also look for existing documentation:

### File structure

Most repos have a single context:

```
/
├── CONTEXT.md
├── docs/
│   └── adr/
│       ├── 0001-event-sourced-orders.md
│       └── 0002-postgres-for-write-model.md
└── src/
```

If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:

```
/
├── CONTEXT-MAP.md
├── docs/
│   └── adr/                          ← system-wide decisions
├── src/
│   ├── ordering/
│   │   ├── CONTEXT.md
│   │   └── docs/adr/                 ← context-specific decisions
│   └── billing/
│       ├── CONTEXT.md
│       └── docs/adr/
```

Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.

## During the session

### Challenge against the glossary

When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"

### Sharpen fuzzy language

When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."

### Discuss concrete scenarios

When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.

### Cross-reference with code

When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"

### Update CONTEXT.md inline

When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).

`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.

### Offer ADRs sparingly

Only offer to create an ADR when all three are true:

1. **Hard to reverse** — the cost of changing your mind later is meaningful
2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons

If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).

</supporting-info>

## Wrapper Additions

The additions below are **not** part of Matt's upstream skill. They operationalize the upstream's rules into deterministic, stdlib-only validators that pair naturally with the interview loop.

### Workflow (with wrapper tools)

1. **Pre-flight (before the first question):**
   - Run `scripts/context_md_linter.py CONTEXT.md` if a `CONTEXT.md` exists — confirms the glossary is well-formed before grilling against it.
   - Run `scripts/adr_scanner.py docs/adr/` if `docs/adr/` exists — surfaces numbering gaps, malformed ADRs, status-frontmatter inconsistencies.
   - Run `scripts/glossary_code_consistency.py --context CONTEXT.md --code src/` — flags defined-but-unused terms (dead glossary) and code-only common nouns that may need definitions. Use these flags as opening grill questions.

2. **During the session (Matt's rules apply):**
   - One question per turn, walking depth-first.
   - When a term is sharpened: edit `CONTEXT.md` immediately; re-run `context_md_linter.py` if the edit is structural.
   - When an ADR is warranted: write it under `docs/adr/`; re-run `adr_scanner.py` to confirm numbering.

3. **Closing:**
   - Final `glossary_code_consistency.py` run to confirm no new orphan terms were introduced.
   - Summarize: terms added/refined, ADRs written, scenarios discussed, open items.

### Tools (stdlib-only)

| Tool | One-line role |
|---|---|
| `scripts/context_md_linter.py` | Validate `CONTEXT.md` against the CONTEXT-FORMAT.md structure. PASS/WARN/FAIL per rule. |
| `scripts/adr_scanner.py` | Walk `docs/adr/`, check `NNNN-slug.md` pattern, numbering integrity, body completeness. |
| `scripts/glossary_code_consistency.py` | Cross-reference bold terms in `CONTEXT.md` against codebase usage. Flag dead glossary + code-only common nouns. |

### References (citations behind each rule)

- [`references/ubiquitous_language.md`](references/ubiquitous_language.md) — why a glossary belongs in source control (Evans, Vernon, Khononov, Wlaschin, Brandolini, Avram & Marinescu, Fowler)
- [`references/adr_practice.md`](references/adr_practice.md) — when an ADR earns its keep (Nygard, Tyree & Akerman, Zimmermann Y-statements, MADR, ThoughtWorks Radar, adr-tools, Backstage)
- [`references/context_md_as_artifact.md`](references/context_md_as_artifact.md) — CONTEXT.md as living artifact (Khononov on language drift, Kernighan on naming, BoundedContext bliki, Confluent on data contracts, Brandolini on EventStorming glossary)

### Companion

- Agent: `cs-grill-with-docs` (see `../../agents/cs-grill-with-docs.md`)
- Command: `/cs-grill-with-docs` (see `../../commands/cs-grill-with-docs.md`)

---

**Version:** 1.0.0
**Derived:** Matt Pocock's grill-with-docs (MIT) + this repo's wrapper
Pliki w paczce (9)
  • ADR-FORMAT.md 3 KB
  • CONTEXT-FORMAT.md 3 KB
  • SKILL.md 7 KB
  • references/adr_practice.md 9 KB
  • references/context_md_as_artifact.md 9 KB
  • references/ubiquitous_language.md 7 KB
  • scripts/adr_scanner.py 9 KB
  • scripts/context_md_linter.py 10 KB
  • scripts/glossary_code_consistency.py 10 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · alirezarezvani/claude-skills100MIT
kriegcloud/beep-effect100Apache-2.0
drosam/agents100MIT
drvoss/everything-copilot-cli100MIT
dlebed/rotisserie100MIT
khaledsaeed18/dotclaude100MIT
ayoubben18/ab-method100MIT
lttr/claude-marketplace100MIT
flutter/agent-plugins100BSD-3-Clause

Migawka bazy z 13.11.2026 · wersja paczki ccefb81a5088 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100grill-me
    Testuje plan względem modelu domenowego projektu, doprecyzowuje terminologię i na bieżąco aktualizuje dokumentację (CONTEXT.md, ADR) w miarę podejmowania decyzji.
  • 100grill-po
    Prowadzi sesję doprecyzowania wymagań z Product Ownerem, sprawdza plan względem modelu domenowego i na bieżąco aktualizuje pliki bounded context, cechy Gherkin i DMD.
  • 100domain-model
    Przepytuje plan pod kątem istniejącego modelu domeny, doprecyzowuje terminologię i na bieżąco aktualizuje dokumentację (CONTEXT.md, ADR) w miarę zapadania decyzji.
  • 100domain-model
    Przepytuje plan pod kątem istniejącego modelu domeny, doprecyzowuje terminologię i na bieżąco aktualizuje dokumentację (CONTEXT.md, ADR) w miarę zapadania decyzji.
  • 100domain-model
    Przepytuje plan względem istniejącego modelu domenowego: sprawdza terminologię z CONTEXT.md i ADR i aktualizuje oba pliki na bieżąco, gdy zapadają decyzje.
  • 100grilling
    Przepytuje plan lub decyzję i buduje glosariusz projektu oraz ADR w miarę ustalania kolejnych decyzji.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.