# How the grill-me Skill Challenges and Validates Design Decisions

> Learn how the grill-me skill systematically challenges and validates your design decisions through an interview-driven decision tree and live codebase exploration.

- Repository: [Matt Pocock/skills](https://github.com/mattpocock/skills)
- Tags: how-to-guide
- Published: 2026-04-04

---

**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`](https://github.com/mattpocock/skills/blob/main//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`](https://github.com/mattpocock/skills/blob/main//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`](https://github.com/mattpocock/skills/blob/main//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:

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

```

A typical grilling session follows this interrogation structure:

```text
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:

```markdown

# 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`](https://github.com/mattpocock/skills/blob/main//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`](https://github.com/mattpocock/skills/blob/main//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`](https://github.com/mattpocock/skills/blob/main/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.