mirror of
https://github.com/alirezarezvani/claude-skills.git
synced 2026-09-05 08:05:57 +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 |
||
|---|---|---|
| .. | ||
| cs-grill-with-docs.md | ||