grill-with-docs

name	grill-with-docs
description	Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (docs/patterns, docs/architecture, docs/proposals) inline as decisions crystallise. Use when user wants to stress-test a plan against the project's language and documented decisions.

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.

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

Repo documentation map

docs/README.md is the system of record for what goes where. Read it before grilling instead of relying on a duplicated directory map in this skill.

The routes most relevant to a grill session are:

• Established conventions ("how we write Effect", "how we structure boundaries") → docs/patterns/ and the ast-grep rules in rules/effect/ and rules/shared/.
• How to build a new app ("CLI scaffold", "HTTP API scaffold") → docs/templates/.
• Accepted architectural shape ("what the system looks like for app X") → docs/architecture/.
• Unshipped non-trivial changes ("what we plan to change and why") → docs/proposals/active/.
• Feasibility work ("what the prototype proved") → docs/experiments/.
• Repo-level naming (app names, package names, command names) → the tables in AGENTS.md.

This repo does not use a separate docs/adr/ tree. Architectural decisions are captured as rationale inside docs/architecture/ once accepted. Update or extend the docs that already exist; only graduate to a new file when docs/README.md's convention says you should.

During the session

Challenge against established conventions

When the user's plan conflicts with conventions documented in docs/patterns/, the ast-grep rules in rules/, settled shape in docs/architecture/, or the names/responsibilities recorded in AGENTS.md, call it out immediately. Examples:

• "docs/patterns/effect.md requires custom errors to extend Data.TaggedError (and rules/effect/use-tagged-error.yml enforces it). Your plan introduces a plain Error subclass — intentional?"
• "docs/patterns/boundaries.md says external SDKs are wrapped in adapter files; runPromise only appears at entry points. Your plan calls Effect.runPromise inside an interior service — is that a deliberate departure?"
• "docs/patterns/data-validation.md requires Schema.decodeUnknown at boundaries — no as casts on parsed data. Your plan has JSON.parse(body) as Foo — intentional?"
• "You're using the name 'workspace' for what AGENTS.md calls a 'project' — which do you mean?"

Sharpen fuzzy language

When the user uses vague or overloaded terms, propose a precise canonical term grounded in the codebase. "You're saying 'service' — do you mean an Effect Context.Tag service, an adapter wrapping an SDK, or a deployable app under apps/? Pick the one you mean and use it consistently."

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 plan says the adapter swallows network errors, but the existing code in apps/foo/src/http.adapter.ts lets them propagate as a tagged error — which is right?"

Update docs inline

When a convention is sharpened or a name is pinned down, update the relevant doc in place — don't batch. Use the routing in docs/README.md:

• Coding convention (idiom, rule, style — applies across files) → extend the relevant docs/patterns/*.md. If the pattern can be enforced mechanically, mention adding an ast-grep rule under rules/effect/ or rules/shared/ (with a matching test under rule-tests/).
• Accepted system shape, data flow, or process model → docs/architecture/ (create the file if it doesn't exist).
• Unshipped non-trivial design → docs/proposals/active/. Proposals carry status while decisions are still in flight.
• Feasibility notes and demo evidence → docs/experiments/ unless the repo has accepted the design.
• How to build a new app of some kind → extend the matching docs/templates/*.md.
• Repo-level names or command pointers → update AGENTS.md.
• App-specific setup or run instructions → the app's own README.md, not docs/.

Don't couple docs to implementation details. Capture conventions that survive refactors, not specifics of a single function.

If the doc describes code behavior tightly, bind it with drift link <doc> <source-file> so future drift is caught — see docs/README.md and the drift skill.

Capture decisions sparingly

If the decision is already settled and uncontroversial, write it directly into docs/architecture/ or docs/patterns/. Don't invent ceremony where there's no live trade-off.

When a non-obvious architectural decision is already settled, capture it inline in the appropriate docs/architecture/<topic>.md with a short rationale section — see ADR-FORMAT.md for the shape and the criteria for when a decision is worth capturing at all. When the decision is still a proposal, use docs/proposals/active/; when it is accepted, architecture describes the accepted state and the completed proposal keeps the historical decision context.