Revisiting Superpowers in 2026: When the Lightweight /grill-me Is the Better Choice

1. Seven‑Line Entry, Hidden Behavior

The mattpocock/skills repository treats each Skill as a small, composable unit. The /grill-me entry compresses fact‑checking, decision‑asking, and execution gating into a narrow interface that locks action until shared understanding is achieved.

The entry file skills/productivity/grill-me/SKILL.md contains a single line: Run a `/grilling` session. Its frontmatter sets disable-model-invocation: true, marking it as a user‑invoked entry. The actual interview logic resides in skills/productivity/grilling/SKILL.md. This mirrors a CLI versus library split: /grill-me is user‑facing and starts the process, while /grilling is Skill‑facing and preserves interview discipline. The README restricts calls so a user entry may invoke a model entry but not another user entry.

Line counts (7 for /grill-me, 12 for /grilling, 7 for /grill-with-docs) illustrate interface narrowness but do not prove token savings or performance gains.

2. What /grilling Actually Controls

/grilling

implements a lightweight state machine with five rules that prevent common drift:

Explore facts
→ Find the earliest decision in the dependency chain
→ Pose a question with a recommended answer
→ Wait for user response
→ Update shared understanding
→ User confirms completeness
→ Unlock action

Along the Decision Tree

The Agent must follow the decision tree, resolving upstream decisions before downstream questions, something static questionnaires cannot achieve.

One Question at a Time

The source mandates a single question per turn and waits for feedback, preventing the Agent from assuming independence among multiple simultaneous questions.

Question Must Include a Recommendation

Instead of asking “Describe your system,” the Agent must first analyze and then propose a concrete recommendation for the user to accept, reject, or modify. Example: “I suggest keeping the existing authentication layer because this request only changes the authorization rules. Do you agree?”

Separate Facts and Decisions

Facts that can be verified from the file system or source code are fetched by the Agent; decisions involving product trade‑offs are left to the user. A changelog entry on July 6 2026 split fact‑checking from decision‑making to enforce a human‑in‑the‑loop boundary.

Shared Understanding as an Action Gate

The interview only ends after the user confirms a shared understanding; otherwise execution remains locked. This distinguishes /grill-me from a simple multi‑question flow.

3. Why /grill-with-docs Exists

While /grill-me ensures shared understanding, it does not guarantee a persisted specification. Issue #311 reported difficulty tracing structured decisions after a session. /grill-with-docs composes /grilling with /domain-modeling to add documentation capabilities:

Challenge ambiguous terminology.

Stress‑test domain relationships with boundary scenarios.

Cross‑check source code against verbal descriptions.

Write a CONTEXT.md after terminology is settled.

Generate an Architecture Decision Record (ADR) only when three conditions hold: the decision is hard to reverse, missing background would surprise future readers, and a real trade‑off exists.

The documentation layer is added only when needed; it is not forced by default.

4. Comparing with Superpowers brainstorming

/grill-me

is short; Superpowers brainstorming is longer. Both require context understanding, one‑question‑at‑a‑time interaction, concrete suggestions, and a block on execution until user confirmation. Their divergence lies in the target artifact and process weight.

Key differences:

Target : /grill-me produces a pressure‑test plan or decision; Superpowers aims to produce a reviewable specification.

Default product : shared understanding (no persistence) vs. design document with hand‑off.

Process : fact‑check → decision → gate vs. exploration → clarification → option comparison → staged approval → document review.

Composition : thin interface layered by outer entry vs. built‑in comprehensive lifecycle.

Constraints : few concentrated rules vs. hard gates, checklists, and flowcharts.

Superpowers enforces a checklist after early issues and adds integration testing. Issue #939 shows a conflict where the default output path of brainstorming overwrote a preferred path in CLAUDE.md, illustrating that tighter rules increase coordination overhead.

5. When to Use Which Tool

Installation command (from the README): npx skills@latest add mattpocock/skills Use /grill-me when requirements are vague, boundaries are undefined, or you need a quick human‑in‑the‑loop interview to clarify intent.

Use /grill-with-docs when you need a formal specification, unified terminology, source verification, and ADR recording.

For cross‑system, large‑scale sessions, consider /wayfinder as suggested by the README and changelog.

When the task is fully defined and only mechanical execution remains, skip the full grilling flow.

For auditable processes with checklists and review gates, Superpowers brainstorming aligns better.

6. How to Choose

The 7‑line /grill-me entry hides a design that centers on /grilling: one question at a time, a recommended answer, facts fetched by the Agent, decisions left to the human, and execution locked until shared understanding is confirmed.

When documentation is required, layer /grill-with-docs on top to add domain modeling, CONTEXT.md, and conditional ADRs.

When a full specification and hand‑off are the goal, Superpowers brainstorming provides the necessary weight.

Conclusion: Choose /grill-me for lightweight clarification, /grill-with-docs for documented alignment with code, and Superpowers brainstorming for a complete spec workflow. The tool’s weight should match the desired artifact.

All observations are based on the source code, README, changelog, and public issue discussions as of 15 July 2026. The repository may evolve; always refer to the current SKILL.md for the latest rules.