agentic-dev/.claude/skills/grill-with-docs/SKILL.md

---
name: grill-with-docs
description: Stress-test a plan against this repo's domain glossary, ADRs, conformance rules, and feature manifests. Update docs/glossary.md inline as terms crystallize; offer ADRs sparingly. Use when the user wants to harden a plan before it becomes a PRD.
---

<what-to-do>

Interview the user relentlessly about every aspect of this plan until you 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 before continuing.

If a question can be answered by exploring the codebase, explore the codebase instead of asking. The repo has fast feedback loops — run `pnpm work status`, grep manifests, read feature `feature.manifest.ts`, check ADRs. Speculation is a last resort.

</what-to-do>

<supporting-info>

## Repo doc map

This repo uses a **single context** with these doc locations:

```
/
├── docs/
│   ├── glossary.md                 ← lazy-create when first term resolves
│   ├── decisions/                  ← ADRs (adr-NNN-<slug>.md, 3-digit zero-pad)
│   │   ├── adr-001-monorepo-tool.md
│   │   ├── adr-018-audit-and-compliance.md
│   │   └── ...
│   ├── architecture/               ← long-form specs + workflow design
│   ├── work/                       ← PRDs, epics, stories, tasks
│   └── guides/                     ← how-to runbooks
└── packages/<feature>/src/feature.manifest.ts   ← per-feature contract
```

There is **no `CONTEXT.md` or `CONTEXT-MAP.md`** — this repo uses `docs/glossary.md` (create lazily) plus the per-feature `feature.manifest.ts` files for machine-readable domain shape. Don't create the multi-context layout (`CONTEXT-MAP.md`) unless this becomes a polyrepo.

## During the session

### Challenge against the glossary + manifests

When the user introduces a term that conflicts with `docs/glossary.md` (if it exists) or with a `feature.manifest.ts` entry, call it out immediately:

> "Your glossary defines `cancellation` as the act of voiding an unsent invoice, but you seem to mean the user-initiated subscription teardown — which is it?"

> "`auth.signIn` exists in `packages/auth/src/feature.manifest.ts` with that exact slug — are you adding a new use case or extending the existing one?"

### Sharpen fuzzy language

When the user uses vague or overloaded terms, propose a precise canonical term:

> "You're saying `account` — do you mean a `User` (entity in `packages/auth`) or a Payload-collection record? Those are distinct."

### Discuss concrete scenarios

When domain relationships are being discussed, stress-test them with specific scenarios. Invent edge cases that force precision about boundaries between concepts. Lean on the existing feature set — auth, blog, media, marketing-pages, navigation — for grounding examples.

### Cross-reference with code

When the user states how something works, verify it against the code. Look at:

- The feature's `feature.manifest.ts` for declared use cases, audits, publishes, consumes
- `packages/<feature>/src/application/use-cases/` for the actual shape
- `packages/<feature>/src/di/bind-production.ts` for what's wired
- `docs/decisions/adr-NNN-*.md` for the decision history

If you find a contradiction, surface it:

> "You said cross-feature reactions happen through the bus, but `packages/auth/src/feature.manifest.ts` shows `publishes: []` — has this been wired yet?"

### Cross-reference with ADRs

Before recommending an approach, scan `docs/decisions/` for relevant ADRs. If your recommendation contradicts a current-status ADR, surface that explicitly:

> "You're proposing direct cross-feature imports, but `adr-006-vertical-feature-packages.md` plus rule R20 in the ESLint config forbid that — events (`core-events`) are the sanctioned path. Want to use events, or do you want to reopen the ADR?"

### Cross-reference with conformance rules

The conformance system (`docs/architecture/agent-first-workflow-and-conformance.md`) defines hard contracts:

- Every use case has a manifest entry → contracts → tests → impl (in that order)
- TS brands (`Instrumented`, `Captured`, `Audited`) attached at DI bind time
- ESLint rules enforce manifest ↔ code alignment
- `pnpm conformance` enforces cross-feature event closure

If the plan would violate any of these, flag it.

### Update `docs/glossary.md` inline

When a term is resolved during the conversation, append it to `docs/glossary.md` right then — don't batch. Lazy-create the file when the first term is resolved. Use the format in [glossary-format.md](./glossary-format.md).

Only include terms meaningful to **this repo's domain** (template / monorepo / agent-first workflow / clean architecture / vertical features). Skip general programming concepts. Skip implementation details — those belong in code or ADRs.

### Offer ADRs sparingly

Only offer to create an ADR when all three are true:

1. **Hard to reverse** — the cost of changing your mind later is meaningful
2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
3. **Result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons

If any is missing, skip the ADR. The repo's ADRs follow a long-form `Context → Decision → Alternatives considered → Consequences → Related` shape (see `docs/decisions/adr-015-events-and-jobs.md` for a representative example). Number is next-highest in `docs/decisions/` zero-padded to 3 digits (`adr-020-...`, `adr-021-...`).

If the grill produced a major refactor decision rather than a new feature, lead the user to an ADR; if it produced a feature plan, lead to a PRD via `to-prd`.

</supporting-info>