grill-with-docs

Files (1)

• SKILL.md

SKILL.md (first lines)

Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.

Ask the questions one at a time, waiting for feedback on each question before continuing. Asking multiple questions at once is bewildering.

If a question can be answered by exploring the codebase, explore the codebase instead.

# Domain Modeling

Actively build and sharpen the project's domain model as you design. This is the *active* discipline — challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. (Merely *reading* a context file for vocabulary is not this skill — that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.)

## File structure

Treat domain-model files as durable project documentation. For new work, follow `project-layout`: put context files under `docs/domain/`, ADRs under `docs/adr/`, and keep root files only for tool-required controls such as `AGENTS.md` or ecosystem configuration.

Most repos have a single context:

```
/
├── docs/
│   ├── domain/
│   │   └── CONTEXT.md
│   └── adr/
│       ├── 0001-event-sourced-orders.md
│       └── 0002-postgres-for-write-model.md
└── src/
```

If a `docs/domain/CONTEXT-MAP.md` exists, the repo has multiple contexts. The map points to where each one lives:

```
/
├── docs/
│   ├── domain/
│   │   ├── CONTEXT-MAP.md
│   │   ├── ordering/
│   │   │   └── CONTEXT.md
│   │   └── billing/
│   │       └── CONTEXT.md
│   └── adr/
│       ├── 0001-system-wide-decision.md
│       ├── ordering/
│       │   └── 0001-ordering-decision.md
│       └── billing/
│           └── 0001-billing-decision.md
├── src/
│   ├── ordering/
│   └── billing/
```

Create files lazily — only when you have something to write. If no context file exists, create `docs/domain/CONTEXT.md` when the first term is resolved. If no ADR directory exists, create the relevant `docs/adr/` directory when the first ADR is needed.

On an existing repo, recognize legacy root files such as `CONTEXT.md` and `CONTEXT-MAP.md`, or legacy context-local ADR directories, and keep using the established tree rather than creating a parallel canonical one. Migrate only when the user asks or the task includes reorganization.

## During the session

### Challenge against the glossary

When the user uses a term that conflicts with the existing language in the relevant context file, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"

### Sharpen fuzzy language

When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."

### Discuss concrete scenarios

When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.

### Cross-reference with code

When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"

### Update context files inline

When a term is resolved, update the relevant `docs/domain/.../CONTEXT.md` file right there. Don't batch these up — capture them as they happen. Use the format:

# Context file format

## Structure

```md
# {Context Name}

{One or two sentence description of what this context is and why it exists.}

## Language

**Order**:
{A one or two sentence description of the term}
_Avoid_: Purchase, transaction

**Invoice**:
A request for payment sent to a customer after delivery.
_Avoid_: Bill, payment request

**Customer**:
A person or organization that places orders.
_Avoid_: Client, buyer, account
```

## Rules

- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.

## Single vs multi-context repos

**Single context (most repos):** One `docs/domain/CONTEXT.md`.

**Multiple contexts:** A `docs/domain/CONTEXT-MAP.md` lists the contexts, where they live, and how they relate to each other:

```md
# Context Map

## Contexts

- [Ordering](./ordering/CONTEXT.md) — receives and tracks customer orders
- [Billing](./billing/CONTEXT.md) — generates invoices and processes payments

From jwd83/skills, Unlicense.

More from jwd83/skills