From fb847c6aded783c1c4a67ec54bfc588fd44e91ab Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Tue, 28 Apr 2026 10:17:37 +0100 Subject: [PATCH] Refactor skill references and documentation for grill-with-docs skill - Updated skill reference from domain-model to grill-with-docs in plugin.json and README.md - Added detailed descriptions and context for grill-with-docs in its SKILL.md - Created ADR-FORMAT.md and CONTEXT-FORMAT.md for grill-with-docs to standardize decision recording - Adjusted references in improve-codebase-architecture to align with new grill-with-docs structure --- .claude-plugin/plugin.json | 2 +- README.md | 26 +++++++++++++++---- skills/engineering/README.md | 2 +- skills/engineering/github-triage/SKILL.md | 18 ++++++------- .../ADR-FORMAT.md | 0 .../CONTEXT-FORMAT.md | 0 .../SKILL.md | 2 +- .../improve-codebase-architecture/SKILL.md | 6 ++--- 8 files changed, 36 insertions(+), 20 deletions(-) rename skills/engineering/{domain-model => grill-with-docs}/ADR-FORMAT.md (100%) rename skills/engineering/{domain-model => grill-with-docs}/CONTEXT-FORMAT.md (100%) rename skills/engineering/{domain-model => grill-with-docs}/SKILL.md (99%) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index a72150b..1369ae2 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -2,7 +2,7 @@ "name": "mattpocock-skills", "skills": [ "./skills/engineering/diagnose", - "./skills/engineering/domain-model", + "./skills/engineering/grill-with-docs", "./skills/engineering/github-triage", "./skills/engineering/improve-codebase-architecture", "./skills/engineering/tdd", diff --git a/README.md b/README.md index 32a9018..fa71919 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,27 @@ My agent skills that I use every day to do real engineering - not vibe coding. +Developing real applications is hard. Approaches like GSD, BMAD, and Spec-Kit try to help by owning the process. But while doing so, they take away your control and make bugs in the process hard to resolve. + +These skills are designed to be small, easy to adapt, and composable. They're based on decades of engineering experience. Hack around with them. Make them your own. Enjoy. + If you want to keep up with changes to these skills, and any new ones I create, you can join ~60,000 other devs on my newsletter: [Sign Up To The Newsletter](https://www.aihero.dev/s/skills-newsletter) -## Engineering +## Why These Skills Exist + +I built these skills as a way to fix common failure modes I see with AI. + +### Failure Mode #1: It Didn't Do What I Wanted + +The most common failure mode is misalignment. You think the AI knows what you want. Then you see what it's built - and you realize it didn't understand you at all. + +The fix for this is a **grilling session** - getting the AI to ask you detailed questions about what you're building. + +## Skill Reference + +### Engineering Skills I use daily for code work. @@ -16,10 +32,10 @@ Skills I use daily for code work. npx skills@latest add mattpocock/skills/diagnose ``` -- **[domain-model](./skills/engineering/domain-model/SKILL.md)** — Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates `CONTEXT.md` and ADRs inline. +- **[grill-with-docs](./skills/engineering/grill-with-docs/SKILL.md)** — Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates `CONTEXT.md` and ADRs inline. ``` - npx skills@latest add mattpocock/skills/domain-model + npx skills@latest add mattpocock/skills/grill-with-docs ``` - **[github-triage](./skills/engineering/github-triage/SKILL.md)** — Triage GitHub issues through a label-based state machine. @@ -58,7 +74,7 @@ Skills I use daily for code work. npx skills@latest add mattpocock/skills/zoom-out ``` -## Productivity +### Productivity General workflow tools, not code-specific. @@ -80,7 +96,7 @@ General workflow tools, not code-specific. npx skills@latest add mattpocock/skills/write-a-skill ``` -## Misc +### Misc Tools I keep around but rarely use. diff --git a/skills/engineering/README.md b/skills/engineering/README.md index 63882e7..ecb23f8 100644 --- a/skills/engineering/README.md +++ b/skills/engineering/README.md @@ -3,7 +3,7 @@ Skills I use daily for code work. - **[diagnose](./diagnose/SKILL.md)** — Disciplined diagnosis loop for hard bugs and performance regressions: reproduce → minimise → hypothesise → instrument → fix → regression-test. -- **[domain-model](./domain-model/SKILL.md)** — Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates `CONTEXT.md` and ADRs inline. +- **[grill-with-docs](./grill-with-docs/SKILL.md)** — Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates `CONTEXT.md` and ADRs inline. - **[github-triage](./github-triage/SKILL.md)** — Triage GitHub issues through a label-based state machine. - **[improve-codebase-architecture](./improve-codebase-architecture/SKILL.md)** — Find deepening opportunities in a codebase, informed by the domain language in `CONTEXT.md` and the decisions in `docs/adr/`. - **[tdd](./tdd/SKILL.md)** — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time. diff --git a/skills/engineering/github-triage/SKILL.md b/skills/engineering/github-triage/SKILL.md index c25b8af..283847a 100644 --- a/skills/engineering/github-triage/SKILL.md +++ b/skills/engineering/github-triage/SKILL.md @@ -97,13 +97,13 @@ Tell the maintainer: Then wait for the maintainer's direction. They may: - Agree and ask you to apply labels → do it -- Want to flesh it out → start a /domain-model session +- Want to flesh it out → start a /grill-with-docs session - Override with a different state → apply their choice - Want to discuss → have a conversation ### Step 3: Bug reproduction (bugs only) -If the issue is categorized as a bug, attempt to reproduce it before starting a /domain-model session. This will vary by codebase, but do your best: +If the issue is categorized as a bug, attempt to reproduce it before starting a /grill-with-docs session. This will vary by codebase, but do your best: - Read the reporter's reproduction steps (if provided) - Explore the codebase to understand the relevant code paths @@ -112,11 +112,11 @@ If the issue is categorized as a bug, attempt to reproduce it before starting a - If reproduction fails, report that too — the bug may be environment-specific, already fixed, or the report may be inaccurate - If the report lacks enough detail to attempt reproduction, note that — this is a strong signal the issue should move to `needs-info` -The reproduction attempt informs the /domain-model session and the agent brief. A confirmed reproduction with a known code path makes for a much stronger brief. +The reproduction attempt informs the /grill-with-docs session and the agent brief. A confirmed reproduction with a known code path makes for a much stronger brief. -### Step 4: /domain-model session (if needed) +### Step 4: /grill-with-docs session (if needed) -If the issue needs to be fleshed out before it's ready for an agent, interview the maintainer to build a complete specification. Use the /domain-model skill. +If the issue needs to be fleshed out before it's ready for an agent, interview the maintainer to build a complete specification. Use the /grill-with-docs skill. ### Step 5: Apply the outcome @@ -133,9 +133,9 @@ Depending on the outcome: When the maintainer explicitly tells you to move an issue to a specific state (e.g. "move #42 to ready-for-agent"), trust their judgment and apply the label directly. -Still show a confirmation of what you're about to do: which labels will be added/removed, and whether you'll post a comment or close the issue. But skip the /domain-model session entirely. +Still show a confirmation of what you're about to do: which labels will be added/removed, and whether you'll post a comment or close the issue. But skip the /grill-with-docs session entirely. -If moving to `ready-for-agent` without a /domain-model session, ask the maintainer if they want to write a brief agent brief comment or skip it. +If moving to `ready-for-agent` without a /grill-with-docs session, ask the maintainer if they want to write a brief agent brief comment or skip it. ## Needs Info Output @@ -155,7 +155,7 @@ When moving an issue to `needs-info`, post a comment that captures the interview - question 2 ``` -Include everything resolved during the /domain-model session in "established so far" — this work should not be lost. The questions for the reporter should be specific and actionable, not vague ("please provide more info"). +Include everything resolved during the /grill-with-docs session in "established so far" — this work should not be lost. The questions for the reporter should be specific and actionable, not vague ("please provide more info"). ## Resuming Previous Sessions @@ -165,4 +165,4 @@ When triaging an issue that already has triage notes from a previous session: 2. Parse what was already established 3. Check if the reporter has answered any outstanding questions 4. Present the maintainer with an updated picture: "Here's where we left off, and here's what the reporter has said since" -5. Continue the /domain-model session from where it stopped — do not re-ask resolved questions +5. Continue the /grill-with-docs session from where it stopped — do not re-ask resolved questions diff --git a/skills/engineering/domain-model/ADR-FORMAT.md b/skills/engineering/grill-with-docs/ADR-FORMAT.md similarity index 100% rename from skills/engineering/domain-model/ADR-FORMAT.md rename to skills/engineering/grill-with-docs/ADR-FORMAT.md diff --git a/skills/engineering/domain-model/CONTEXT-FORMAT.md b/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md similarity index 100% rename from skills/engineering/domain-model/CONTEXT-FORMAT.md rename to skills/engineering/grill-with-docs/CONTEXT-FORMAT.md diff --git a/skills/engineering/domain-model/SKILL.md b/skills/engineering/grill-with-docs/SKILL.md similarity index 99% rename from skills/engineering/domain-model/SKILL.md rename to skills/engineering/grill-with-docs/SKILL.md index afc63fa..4b68b97 100644 --- a/skills/engineering/domain-model/SKILL.md +++ b/skills/engineering/grill-with-docs/SKILL.md @@ -1,5 +1,5 @@ --- -name: domain-model +name: grill-with-docs description: Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions. disable-model-invocation: true --- diff --git a/skills/engineering/improve-codebase-architecture/SKILL.md b/skills/engineering/improve-codebase-architecture/SKILL.md index 3345198..734b84b 100644 --- a/skills/engineering/improve-codebase-architecture/SKILL.md +++ b/skills/engineering/improve-codebase-architecture/SKILL.md @@ -26,7 +26,7 @@ Key principles (see [LANGUAGE.md](LANGUAGE.md) for the full list): - **The interface is the test surface.** - **One adapter = hypothetical seam. Two adapters = real seam.** -This skill is _informed_ by the project's domain model — `CONTEXT.md` and any `docs/adr/`. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate. See [CONTEXT-FORMAT.md](../domain-model/CONTEXT-FORMAT.md) and [ADR-FORMAT.md](../domain-model/ADR-FORMAT.md). +This skill is _informed_ by the project's domain model — `CONTEXT.md` and any `docs/adr/`. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate. See [CONTEXT-FORMAT.md](../grill-with-docs/CONTEXT-FORMAT.md) and [ADR-FORMAT.md](../grill-with-docs/ADR-FORMAT.md). ## Process @@ -70,7 +70,7 @@ Once the user picks a candidate, drop into a grilling conversation. Walk the des Side effects happen inline as decisions crystallize: -- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `/domain-model` (see [CONTEXT-FORMAT.md](../domain-model/CONTEXT-FORMAT.md)). Create the file lazily if it doesn't exist. +- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `/grill-with-docs` (see [CONTEXT-FORMAT.md](../grill-with-docs/CONTEXT-FORMAT.md)). Create the file lazily if it doesn't exist. - **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there. -- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See [ADR-FORMAT.md](../domain-model/ADR-FORMAT.md). +- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See [ADR-FORMAT.md](../grill-with-docs/ADR-FORMAT.md). - **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md).