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
This commit is contained in:
Matt Pocock 2026-04-28 10:17:37 +01:00
parent 51384f4e70
commit fb847c6ade
8 changed files with 36 additions and 20 deletions

View file

@ -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.

View file

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

View file

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

View file

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