How the grill-me Skill Challenges and Validates Design Decisions

The grill-me skill forces architectural plans through a systematic, interview-driven decision-tree interrogation, validating each branch with concrete recommendations and live codebase exploration until every open design question is resolved.

The grill-me skill in the mattpocock/skills repository provides a lightweight framework for stress-testing design choices. Unlike static documentation generators, it implements an interactive loop that treats validation as a conversation, ensuring no ambiguous requirement survives the session. Defined primarily in /grill-me/SKILL.md, the skill is distributed via the Skills CLI and can be embedded into other automation workflows.

The Three-Pillar Architecture

The validation workflow rests on three integrated components that work together to eliminate design drift.

Skill Definition and Behavior Contract

At /grill-me/SKILL.md, the skill declares its behavior in a YAML-style markdown manifest. The definition mandates that the agent must interview the user relentlessly, asking questions one at a time and exploring the codebase whenever a query can be resolved through source inspection. This manifest establishes the strict rule of single-question-per-iteration, preventing the agent from overwhelming the user while ensuring exhaustive coverage of the decision tree.

The Interactive Loop Engine

When invoked, the Skills runtime initiates a continuous validation cycle:

• Prompt Generation – Based on the current plan state, the engine generates one focused question targeting a specific design branch.
• User Input & Recommendation – After the user answers, the agent immediately proposes a recommended answer that serves as the validation step, confirming or correcting the approach.
• Branch Traversal – The confirmed answer determines the next node in the decision tree. The loop repeats until the tree is fully traversed, guaranteeing that no open design choice remains unresolved.

Live Codebase Exploration

If a question can be answered by inspecting source code, the engine executes code-search operations using grep or performs explicit file-read commands. It injects discovered facts—such as existing abstractions, schema definitions, or API signatures—directly into the conversation. This ensures decisions are validated against the actual repository state, not developer assumptions.

Decision Tree Validation in Practice

The grill-me pattern treats design specification as a tree-traversal problem. Each answer resolves a branch, and the agent refuses to conclude the session until every leaf node is addressed and validated.

During the session, the agent maintains a running validation trace. For example, when questioning data source selection, it might recommend reusing an existing OrderRepository abstraction rather than allowing raw SQL queries. This immediate feedback loop catches architectural mismatches before they enter the codebase.

Cross-Skill Integration Patterns

The validation logic is reusable across the Skills ecosystem. In /github-triage/SKILL.md, the github-triage skill explicitly instructs maintainers to "follow the /grill-me pattern" when fleshing out ambiguous issues. It reuses the same one-question-at-a-time workflow and recommendation system, ensuring consistent validation logic whether you are designing a new feature or triaging a bug report.

Usage Examples

Install the skill using the CLI:

npx skills@latest add mattpocock/skills/grill-me

A typical grilling session follows this interrogation structure:

Agent: What is the primary data source for this feature?
User: It will read from the `orders` table in PostgreSQL.
Agent (recommended): ✔️ Use the existing `OrderRepository` abstraction instead of raw queries.

Agent: How should errors be surfaced to the caller?
User: As a typed `ServiceError` enum.
Agent (recommended): ✔️ Define `ServiceError` in `src/errors.ts` and map DB errors to it.

To embed the pattern in another skill, reference the workflow explicitly in your skill definition:

# Inside github-triage/SKILL.md

If the issue needs fleshing out, interview the maintainer to build a complete specification. Follow the /grill-me pattern:
- Ask questions one at a time
- Provide a recommended answer for each question
- If a question can be answered by exploring the codebase, explore the codebase instead

Summary

• The grill-me skill validates design decisions through an exhaustive, interview-driven decision-tree interrogation defined in /grill-me/SKILL.md.
• It enforces a single-question-per-iteration rule, ensuring systematic branch traversal without overwhelming the user.
• Each user answer triggers an immediate recommended validation, converting vague ideas into concrete, testable specifications.
• Built-in code-search (grep) and file-read operations ground decisions in the actual repository state, preventing architectural drift.
• The pattern is reusable; skills like github-triage embed the grill-me workflow to validate issue specifications consistently.

Frequently Asked Questions

What makes grill-me different from a standard checklist?

Unlike static checklists, grill-me implements an adaptive decision-tree traversal that reacts to answers in real-time. It uses the current state to generate the next question dynamically and validates each step with a concrete recommendation, rather than simply marking items complete.

How does grill-me ensure design decisions align with existing code?

The skill mandates codebase exploration whenever a question can be answered through source inspection. By executing grep searches and file reads during the session, it injects actual code facts—such as existing repository patterns—into the validation conversation, ensuring new designs fit the current architecture.

Can I use the grill-me pattern inside my own custom skills?

Yes. The pattern is designed for reuse. As demonstrated in /github-triage/SKILL.md, you can embed the grill-me workflow by instructing your skill to "follow the /grill-me pattern," which activates the one-question-at-a-time interrogation and recommendation system without rewriting the core logic.

Does grill-me support parallel questioning or batch validation?

No. The architecture explicitly forbids parallel questions. The single-question-per-iteration rule in grill-me/SKILL.md ensures that each branch of the decision tree is fully resolved before moving to the next, preventing the validation gaps that often occur with batched inquiries.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}