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

name, description

name	description
grill-with-docs	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.

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.

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.

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.