Post

mattpocock/skills, Part 2: From Vague Requirements to Shared Terms

grill-me and grill-with-docs clarify requirements with questions in dependency order; only grill-with-docs writes agreed terms and decisions into the project.

mattpocock/skills, Part 2: From Vague Requirements to Shared Terms

You’re about to add per-seat billing to a subscription service. The meeting notes use “member,” “user,” and “seat” more or less interchangeably, yet nobody has checked whether the three words mean the same thing. Before the team can discuss whether deactivated members should still be charged, it first needs to pin down what is actually being billed: a person, an account, or an entitlement that can be assigned.

I think of a skill, as used in this post, as a set of instructions that tells an AI coding assistant how to do a specific job. mattpocock/skills breaks the work of clarifying requirements into interviewing, vocabulary curation, and re-explaining. This post lays out how five related skills divide the work and what stays in the project once the interview is over.

mattpocock/skills SeriesPart 2

I based this post on version 1.2.3.

1.3.0, released on 2026-10-04, renamed the glossary files this post relies on (checked 2026-10-19):

  • CONTEXT.md became GLOSSARY.md.
  • CONTEXT-MAP.md became GLOSSARY-MAP.md.

From then on, grill-with-docs, domain-modeling, and wait-what only read and write the new names. So when you follow this post, use GLOSSARY.md wherever it says CONTEXT.md. If your project already has the old file, rename it:

1
git mv CONTEXT.md GLOSSARY.md

When I checked, all five skills covered here were still in the latest release, 1.3.1. I plan a full update of this series.

Five Skills: Three Entry Points, Two Internal Flows

These five skills are not a sequence of steps you must run in order. You only pick the starting point that fits your current situation, and the internal flows take over the rest.

grill-me, grill-with-docs, and wait-what are user-invoked entry points; grill-me and grill-with-docs hand the interview to grilling, and grill-with-docs also hands vocabulary curation to domain-modeling Pick the entry point that fits your current situation, and the internal flows take over the rest.

RoleSkillWhat it’s for
Invoked by yougrill-meClarify an idea through an interview when there’s no project folder yet
Invoked by yougrill-with-docsInterview and update documentation at the same time in an existing project
Internal flowgrillingOrder each round of questions by how they depend on each other
Internal flowdomain-modelingKeep project terminology consistent and record key decisions when needed
Invoked by youwait-whatAsk the AI to fill in the background and say it more plainly

grill-me, grill-with-docs, and wait-what only run when you call them by name; the AI won’t use them on its own. grilling and domain-modeling, on the other hand, can be picked up by the AI on its own and can also be called by other skills. The invocation rules document this difference.

The Two Starting Points Differ in Whether They Leave Documents Behind

Both starting points use the same interview approach. The difference is whether project documentation gets updated during the interview.

grill-me only starts the interview. It suits situations where there’s no project folder yet, such as talking through an idea that hasn’t taken shape. It doesn’t build a glossary, and it leaves no files on your machine when the conversation ends.

grill-with-docs starts two internal flows at once: grilling runs the interview, and domain-modeling curates terms and decisions. When a project folder already exists, ask-matt recommends this starting point first; see its routing rules for the exact conditions.

grilling First Asks the Questions That Can’t Be Skipped

grilling starts by working out the order in which questions depend on each other. The skill’s rules call this structure a “decision tree.” If a question depends on the answer to an earlier one, the AI holds it for a later round.

“Should deactivated members be billed?” can’t be answered until the definition of a billable seat is settled. While that definition is still open, the AI shouldn’t guess at the deactivation rule. Each round goes like this:

flowchart TD
  A[Map question dependencies] --> B[List every decidable question]
  B --> C[Number each, suggest answers]
  C --> D[You reply]
  D --> E{All questions handled?}
  E -->|No| B
  E -->|Yes| F[You confirm shared understanding]
  F --> G[Interview ends]

The grilling rules also spell out who answers what. Facts that can be found in files, code, or tools are for the AI to investigate; choices between different approaches are yours to make.

While the AI is looking something up, it doesn’t stall the whole round. Only the questions that need that information wait for the result, and the rest are asked as usual.

domain-modeling Builds a Project Glossary

The “domain” in domain-modeling means the things and rules the project deals with. In this post’s example, that’s workspaces, members, seats, and how billing works. This skill writes confirmed names into CONTEXT.md, a file I think of as a glossary specific to the project.

If you’re only reading the glossary and reusing existing names, you don’t need to invoke domain-modeling explicitly. It only needs to step in when an existing definition might be wrong, a name isn’t clear enough, or an important decision needs to be recorded.

When discussing terms, the AI should do the following:

  • When a word you use conflicts with an existing definition, point out the discrepancy right away.
  • When a name carries more than one meaning, propose a more precise canonical term.
  • When discussing how terms relate to each other, come up with edge cases to test the definitions, so that both sides spell out where one concept ends and another begins. For example: “If a member is deactivated and later reactivated, do they still have their original seat?”
  • When you describe existing behavior, check the code.

If the code disagrees with what you said, you are still the one who decides whether to keep the current behavior or change it.

Once a term is confirmed, domain-modeling updates CONTEXT.md immediately instead of waiting until the interview is over. The file holds only names and definitions, not implementation details.

A large project made up of several subprojects may have a separate glossary for each one. In that case, CONTEXT-MAP.md in the project’s top-level folder works like an index that points to where each glossary lives. The file rules in domain-modeling define these boundaries.

Significant technical choices may be written up as an ADR, short for Architecture Decision Record. It’s a short document that explains what was chosen and why. The skill’s format allows an ADR to be a single paragraph and doesn’t ask you to pad it out just to fill a template.

The AI proposes an ADR only when all three of these conditions hold, and it writes the ADR only after you agree:

  • The decision will be hard to change later.
  • It will be hard to understand without context.
  • It actually involved weighing alternatives.

You can check the three conditions and the format in ADR-FORMAT.md.

Product, finance, and engineering all agree to per-seat billing, but each defines a seat differently; the glossary document on the right records a shared definition of a billable seat Agreeing on the same word is not the same as agreeing on the same thing.

wait-what Re-Explains Only the Message You Didn’t Follow

wait-what is a correction entry point you use mid-conversation. When the AI’s last explanation skips ahead too quickly or leaves out context, you invoke it explicitly.

It asks the AI to re-explain what it just said and add the background needed to understand it. The content must stick to the terms already confirmed in CONTEXT.md; if the project uses multiple glossary files, it first looks up the right one in CONTEXT-MAP.md.

The re-explanation must be worded in English that follows ASD-STE100, a standard that restricts the vocabulary and sentence patterns used in technical English. You don’t need to learn the standard first; its role here is to make the AI use shorter sentences and consistent terms.

The full instruction is a single paragraph; you can check it in wait-what/SKILL.md. It only asks for the previous message to be re-explained; it doesn’t rerun the whole interview. If the problem isn’t a single message you didn’t follow but requirements that are still vague overall, I’d suggest going back to grill-with-docs and continuing the interview.

Interview Results Don’t All Go Into the Same Document

What gets confirmed in the interview is routed to three destinations: canonical terms and definitions go into CONTEXT.md, significant decisions that involved trade-offs become ADRs, and other feature behavior, exceptions, defaults, and acceptance criteria are handed to to-spec Interview results are written to the glossary, an ADR, or a later spec depending on what kind of content they are.

grill-with-docs writes documentation, but that doesn’t mean it stuffs every answer into CONTEXT.md. Interview content goes to one of three places:

ContentDestinationExample
Canonical, project-specific terms with short definitionsCONTEXT.mdWhat “billable seat” and “member” each mean
Decisions that are costly to change, likely to confuse future readers, and involved trade-offsAn ADR, created once you agreeWhy the billing code keeps the seat assignment records
Other feature behavior, exceptions, defaults, and acceptance criteriaStays in the conversation for now, later handed to to-specWhen a deactivated member stops being billed

CONTEXT.md is a glossary, not a requirements document, and ADRs aren’t a running log of every answer. Most answers stay in the conversation at first. Only when you separately invoke to-spec does that skill turn the confirmed requirements into a feature spec for later development.

There’s No Fixed Number of Interview Questions

The two starting points don’t have their own question banks; both hand the interview to grilling, which has no fixed number of rounds or questions either. So how long the interview takes depends on how much is still undecided, not on which skill you used.

Rather than counting how many questions the AI asked, I’d check three things:

  • Which questions already have answers.
  • Which questions are still waiting on earlier answers.
  • Whether terms and ADRs were written to the right place.

Because grill-with-docs modifies project documentation, I think the team still needs to review whether newly added terms are worth adopting, and whether each ADR meets the three conditions. Definitions that haven’t been agreed on shouldn’t be written down early; otherwise, the next person or AI to pick up the work will just be reading another vague definition.

Check Whether You Have a Project First, Then Pick a Starting Point

I’d first ask whether you already have a project folder holding code and docs, then look at what you’re stuck on: the requirements, the vocabulary, or the last explanation.

Current situationChooseWhat not to expect from it
No project folder yet; you just want to test an ideagrill-meIt won’t write results into project documentation
Already in a project and need to record terms or decisions along the waygrill-with-docsIt won’t directly produce a complete requirements document for later development
You only want the round-by-round questioning methodgrillingIt won’t maintain the glossary on its own
You only need to sort out project terminology or key decisionsdomain-modelingIt won’t capture every requirements answer
You didn’t follow the last explanationwait-whatIt won’t rerun the whole interview

This table is for choosing a starting point; it isn’t an order of execution.

grill-with-docs suits requirements that can be fully clarified in a single conversation. If the requirements are too big to clarify in one conversation, the ask-matt routing rules point you to wayfinder instead. wayfinder is a separate skill for exploring large pieces of work first to figure out where to start.

Simulated Scenario: Questioning Seats Until a Spec Can Be Written

What follows is worked out from the skills’ rules. The scenario: you’ve finished the project setup from the previous post, and you’re now working on per-seat billing inside the subscription service’s project folder. The whole conversation goes like this:

sequenceDiagram
  participant U as You
  participant A as AI
  participant P as Project
  U->>A: Invoke grill-with-docs
  A->>P: Read terms, ADRs, and code
  A->>U: Round 1, independent questions
  U->>A: Confirm the seat definition
  A->>P: Write CONTEXT.md right away
  A->>U: Round 2, follow-up questions
  A->>U: Propose an ADR
  U->>A: Agree
  A->>P: Write the ADR
  U->>A: Invoke wait-what to re-explain

Using Codex, an AI coding assistant, as the example, start by entering the requirement and explicitly invoking grill-with-docs:

1
2
3
$grill-with-docs

We want to add per-seat billing to our existing subscription service. Please help me get the requirements clear.

As the AI reads the project, facts it can look up there are for it to investigate, not to toss back to you. One such fact is whether the system currently charges through the payment platform based on the number of active members.

The first round handles questions that don’t depend on any other answer. For example: is billing based on purchased seats, assigned seats, or the number of active members? And does the subscription belong to the workspace or to a single payer?

Suppose the team eventually confirms that a workspace owns a pool of purchased seats, and a member can use paid features only after being given a seat. domain-modeling can then write the terms down right away:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
**Workspace**:
A space made up of multiple members that shares one subscription.
_Avoid_: account, organization

**Billable seat**:
A paid entitlement that the workspace has purchased and that can be assigned to one member.
_Avoid_: user, headcount

**Seat assignment**:
A record of allocating one billable seat to one member for a period of time.
_Avoid_: membership, subscription item

**Member**:
A person who has joined the workspace. Becoming a member and getting a billable seat are two separate things.
_Avoid_: user, seat

This is illustrative content I organized according to CONTEXT-FORMAT.md. Each _Avoid_ line lists names that are easy to mix up and should be avoided from now on.

Only with these definitions in place can the second round follow up on:

  • Whether a pending invitation takes up a seat.
  • What happens to the assignment when a member is deactivated.
  • When adding or removing seats affects the price.

If the existing code bills directly by the number of active members, the AI also has to point out that the new definition differs from the current behavior. Then it asks you to confirm whether to change it.

Suppose the team then decides that the billing code should store the start and end time of every seat assignment, instead of working backward from the current member list to reconstruct past counts. This makes it easy to look up history later, at the cost of having to update billing data every time membership changes.

This choice may meet the three ADR conditions, so domain-modeling should first propose an ADR and write it only after getting your agreement.

Suppose the AI then explains seat changes in a long block of text, but you can’t tell how “seat change” and “seat assignment” are related. That’s the moment to invoke wait-what and ask it to re-explain using the terms it just wrote down.

When this stretch of the flow is done, the requirements still haven’t been turned into a full spec. What you have at this point:

  • The answers confirmed in the conversation.
  • The terms in CONTEXT.md.
  • A few ADRs created with your agreement.

If this feature will take several conversations to build, the next step is to invoke to-spec in the same conversation and have it organize the requirements into a spec.

Reusable Vocabulary Is What’s Most Worth Keeping

At this point, both the invocation rules and the document-keeping rules I’ve described can be checked against the original sources. But the rules themselves can’t prove that a shared vocabulary will necessarily improve how a team works together.

I still think that, once requirements are clarified, what’s most worth leaving behind is vocabulary the next person can reuse directly, plus the few decisions that are hard to understand from the code alone. The Q&A stays in the conversation; the confirmed definitions make it into the project.

This view only applies to projects maintained by several people, or ones that take several conversations to finish. A one-off brainstorm doesn’t need every term documented; finishing the interview with grill-me is enough.

Make the Same Word Mean the Same Thing First

To try this flow, first pick a word like “seat” that is the most likely to be ambiguous in your requirements. Invoke grill-with-docs inside the project and confirm how it relates to “member” first. Then discuss whether inviting a member takes up a seat, and when billing stops after deactivation.

The goal of the interview isn’t to pile up questions, but to make sure the same word always means the same thing throughout the spec that follows. In the next post, I’ll cover how to use to-spec to write the spec, and then to-tickets to break it down into tickets you can start working on right away.

Further Reading

  • grill-me: confirm that it only starts the interview flow.
  • grill-with-docs: see which two internal flows it starts at once.
  • grilling: understand the decision tree, round-by-round questioning, and when it stops.
  • domain-modeling: check where the glossary and ADRs should and shouldn’t be used.
  • wait-what: see how it asks the AI to re-explain its last message.
  • to-spec: confirm how interview content makes it into a formal spec.
This post is licensed under CC BY 4.0 by the author.