107 lines
5.8 KiB
Markdown
107 lines
5.8 KiB
Markdown
---
|
|
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>
|