grill-my-plan
Skill553 starsChanged 2 months agoMITView on GitHub
Relentlessly interview the user about a plan or proposal (release plans, refactors, model rollouts, architectural changes) until every branch of the decision tree is resolved. Then fold the resolved plan into the right artifact: a decision record, a release roadmap, a PR description, or a tracking issue. USE FOR: stress-testing a plan before execution, pressure-testing scope and trade-offs, surfacing hidden assumptions, drafting MakerWorld/release rollouts, shaping a refactor or migration before code is touched, producing the artifact the plan needs. DO NOT USE FOR: grilling a built model's parameters and geometry (use grill-my-model), writing OpenSCAD code, routine config/version/dependency bumps.
2 other projects use a version of this.
Adopted by
Most recently taken up by
- kellervater/homerackerword for word, first seen Oct 8, 2026
- inspirearun/claude-code-for-non-developerstheir own version, first seen Sep 16, 2026
Other versions2 projects use a version of this.
Word for word · 1
- kellervater/homeracker★ 562100% same
Edited · 0
None found.
Wrote their own version · 1
- inspirearun/claude-code-for-non-developers★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository7 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- decision-recordsSkill
- grill-my-modelSkill
- humanizerSkill
- makerworld-descriptionSkill
- scadfmt-adaptSkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 7 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 47
Before asking anything, read what already exists:
- Distinctive: line 65
Run the interview one question at a time.
- Distinctive: line 71
Wait for the answer before moving on.
- Distinctive: line 73
When an answer reveals a new branch, push onto the agenda and keep going.
- Distinctive: line 121
Only after the relevant branch is resolved, write the plan into the artifact that fits.
- Very specific: line 135
Use HomeRacker emoji headers (📦 What · 💡 Why · 🔧 How · ⚠ Risk · 📊 Trade-offs).
- Distinctive: line 140
Do not spawn new top-level doc files when an ADR, PR body, or issue already fits.
- Very specific: line 146
When the artifact *is* an ADR, follow the decision-records skill verbatim for template, naming, index update, and supersede flow.
- Distinctive: line 156
Every deliverable has a justified existence, acceptance criterion, and place in the sequence, or was dropped from scope.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
🔥 Grill My Plan, homeracker Skill
📌 What
A relentless interview that walks every branch of a plan's decision tree, one question at a time, and challenges every choice (scope, sequencing, trade-offs, risk, definition of done) until the plan is shared and stress-tested. The resolved answers are then folded into the artifact the plan actually needs.
The goal is not to be nice. The goal is the clearest, shortest defensible plan, and the artifact that captures it (ADR, release roadmap, PR description, or tracking issue), nothing more.
🤔 Why
Plans accrete vague goals, optimistic scopes, and hidden assumptions that only hurt at execution time. Grilling surfaces those decisions while they are still cheap to change and captures the rationale where future contributors (and AI agents) will actually read it.
This skill is the plan-shaped sibling of grill-my-model (which grills built OpenSCAD models). Both adopt the same one-question-at-a-time loop from the upstream mattpocock/skills grilling; they differ in what they walk (parameters vs. plan branches) and what they produce (model docs vs. plan artifact).
1. When to Use
| Situation | What the grill produces |
| Release rollout (e.g. shipping a model family to MakerWorld) | A release roadmap: scope per release, ordering, prerequisites, acceptance, captured as a decision record or release plan doc |
| Architectural / tooling change | A decision record (ADR) with the resolved trade-off and rejected alternatives |
| Refactor or migration | A PR description scaffold listing scope, non-goals, sequencing, verification |
| New feature with unclear scope | A tracking issue with crisp acceptance criteria and a phased plan |
It works the same in every case: gather context, grill, then act on the right artifact.
2. Gather Context First (do not ask what you can read)
Before asking anything, read what already exists:
- Any draft, sketch, or thread the user pointed at.
- Code, models, and docs the plan touches, enumerate the surface area concretely.
- Existing ADRs in
docs/decisions/for prior decisions in this area. - Repo conventions: HomeRacker standards (15 mm base unit, 4 mm lock pins, 2 mm walls, 0.2 mm tolerance), markdown instructions, and the relevant model READMEs.
Rule (from the source pattern): if a question can be answered by exploring the codebase, explore the codebase instead. Only ask the human what the code cannot tell you or where it is ambiguous, intent, trade-offs, priorities, and the "why".
Build a checklist of every decision the plan implies. That checklist is your grill agenda.
3. The Grilling Loop
Run the interview one question at a time. Asking several at once is bewildering.
For each question:
- State the decision under scrutiny and why it matters.
- Give your recommended answer with reasoning (so the user can just confirm).
- Wait for the answer before moving on.
- Resolve dependencies first: if decision B depends on A, settle A first.
- When an answer reveals a new branch, push onto the agenda and keep going.
Stay relentless but constructive. Keep each question tight, no walls of text.
4. What to Grill, Plan Question Catalog
Walk these lenses for the plan as a whole and for every distinct deliverable inside it. Skip only what context already answers conclusively.
4.1 Goal & scope
- Problem: What concrete problem does this plan solve? Whose problem is it?
- Definition of done: What does "shipped" look like? What is the user-visible outcome that lets us close it?
- Out of scope: What is explicitly not in this plan, and why? (YAGNI check.)
- Why now: What changed to make this worth doing now over later?
4.2 Every deliverable (ask for each one)
- Existence: Why does this deliverable exist in the plan? Which goal does it serve? What breaks if we drop it?
- Sequencing: What must land before this? What can ride along vs. follow up?
- Size: Is it one PR, one release, or a series? Is it splittable into independently-shippable slices?
- Acceptance: How will we know this deliverable is done, concretely?
- Risk & rollback: What's the worst plausible failure mode? Can we revert?
4.3 Trade-offs & alternatives
- Alternatives: Which approaches were considered and rejected? Why?
- Cost: What does this plan cost in time, complexity, or future maintenance?
- Reversibility: Which decisions are one-way doors vs. easily revisited later?
- Dependencies you don't own: Upstream releases, external services, user action, what's the worst that happens if they stall?
4.4 Audience & rollout
- Who consumes it: Users? Other contributors? MakerWorld visitors?
- How they learn about it: README diff, MakerWorld description, changelog, release notes, which channels actually reach the audience?
- Migration story: What do existing users need to do? Breaking change or drop-in upgrade?
5. Act on the Plan, Pick the Right Artifact
Only after the relevant branch is resolved, write the plan into the artifact that fits. Pick one primary artifact; cross-link the others.
| Plan shape | Primary artifact | Where it lives |
| Architectural / tooling / convention decision | Decision record (ADR) | docs/decisions/<kebab-title>.md, load the decision-records skill |
| Multi-step release rollout (e.g. MakerWorld family) | Release plan doc or ADR | docs/<topic>/release-plan.md if multi-release; ADR if it's mainly the decision |
| Single PR-sized change | PR description scaffold | The PR body; follow .github/pull_request_template.md (What / Why / How) |
| Multi-step feature without a single owner | Tracking issue | A GitHub issue with checklist; one sub-issue per deliverable |
5.1 Writing quality
- Be brief, bullet points over prose, < ~100 lines where possible.
- Capture the why, the non-goals, and the alternatives rejected, never restate what code or commits already say.
- Use HomeRacker emoji headers (📦 What · 💡 Why · 🔧 How · ⚠ Risk · 📊 Trade-offs).
- Cross-link from related docs (ADR ↔ README ↔ issue ↔ PR).
5.2 Don't invent docs
Do not spawn new top-level doc files when an ADR, PR body, or issue already fits. Improve what exists; link rather than duplicate.
6. Decision Record (ADR) Rules
When the artifact is an ADR, follow the decision-records skill verbatim for template, naming, index update, and supersede flow.
A plan grill may surface that an existing ADR is outdated. In that case, prefer superseding the old ADR (per the decision-records skill) over editing it in place, git history then carries the why-it-changed.
7. Completion Criteria
The grill is done when:
- Every deliverable has a justified existence, acceptance criterion, and place in the sequence, or was dropped from scope.
- Trade-offs and rejected alternatives are recorded.
- The chosen artifact (ADR / release plan / PR body / issue) is written and cross-linked from related docs.
- A newbie could read the artifact and predict what will ship, in what order, and why.
📚 References
humanizerskill: run it over any artifact text (ADR, roadmap, PR/issue) this grill writes or edits, to strip AI tellsgrill-my-modelskill: the model-shaped sibling (use it for built OpenSCAD models, not plans)decision-recordsskill: ADR template, index, supersede flow- Markdown guidelines: emoji headers, structure
- Pull request template: What / Why / How sections for PR-shaped artifacts
- mattpocock/skills
grilling: the upstream "grill my plan" pattern this adapts
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

