--- name: grillme description: Socratic plan validation. Grills your plan one question at a time against the project's domain language (CONTEXT.md) and prior decisions (ADRs in docs/adr/), updating both inline as terms resolve. Catches terminology drift, hidden assumptions, and undocumented decisions BEFORE implementation. WRITES to CONTEXT.md and docs/adr/ with per-write confirmation — use --no-write for dry-run. Triggers: "grill my plan", "stress-test this plan", "validate this approach", "is this consistent with our domain", "are there decisions missing", "before I implement", "challenge my assumptions", "/grillme". Example: "/squad:grillme --deep store user notifications in a separate table". For exploring options BEFORE a plan exists, use /brainstorm. For implementation, use /squad:implement. --- # Skill: Grillme ## Objective Take the user's plan (a paragraph, a bullet list, a PRD-ish blurb — whatever) and run a Socratic interview that surfaces contradictions, sloppy terminology, and unstated decisions, **one question at a time**, grounded in the project's domain artefacts. When a term gets resolved or a decision gets made, capture it inline in `CONTEXT.md` and (sparingly) `docs/adr/`. The point is not to write code; it is to harden the plan before code gets written. Position in the workflow: - **`/squad:brainstorm`** — explores _what_ to build (outward research) - **`/squad:grillme`** — interrogates a chosen plan against MY codebase (this skill) - **`/squad:implement`** — writes the change ## Inviolable Rules 1. **This skill writes user files.** Unlike `brainstorm` / `debug` / `question` / `stats` (read-only by rule), `grillme` may mutate `CONTEXT.md`, `CONTEXT-MAP.md`, and files under `docs/adr/`. Every write is preceded by an inline confirmation ("update CONTEXT.md to record this resolution?"). No silent writes. No writes to anything outside those three paths. **Never edits source code.** 2. **No `git commit`, no `git push`.** Read-only git is fine for context (`git log`, `git status`, `git diff`). The user owns the commit. 3. **One question at a time.** No question lists, no batching. Ask, wait for the answer, integrate it, then ask the next. The Socratic value comes from forcing depth on each branch before moving on. 4. **Recommend your answer.** For every question, propose your best current answer so the user can correct rather than invent from scratch. Phrase: "I'd say X — does that match your model?" 5. **No AI attribution in any artifact produced.** `CONTEXT.md` and ADR files must not carry `Co-Authored-By: Claude / Anthropic / Generated with [...]` lines. Consistent with the squad-wide commit-authorship rule. 6. **ADRs are offered sparingly.** Only when **all three** are true: (1) hard to reverse, (2) surprising without context, (3) the result of a real trade-off with rejected alternatives. If any one is missing, skip the ADR. ## Inputs ``` /squad:grillme [--quick | --normal | --deep] [--no-write] [--domain ] ``` | Flag | Default | Description | | ----------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `--quick` | off | Cap at ~3 questions; only flag the most load-bearing inconsistencies. Sub-2-minute session for low-stakes plans. | | `--normal` | default | ~5–8 questions; full glossary + ADR offer flow. Use when the plan touches a non-trivial slice. | | `--deep` | off | ~10+ questions; cross-references code paths; walks every branch of the design tree. Use for architectural plans where misunderstanding is expensive. | | `--no-write` | off | Dry-run: emit proposed `CONTEXT.md` / ADR patches inline but apply nothing. Useful in PR review or read-only environments. | | `--domain ` | auto | When the repo has multiple bounded contexts (`CONTEXT-MAP.md` present), pin the interview to one. Auto-detect from the plan text if omitted. | The user's free-form text after the flags is the plan. **Capped at 16 KB**; truncate and surface `note: plan truncated at 16 KB` if exceeded. ## Phase 0 — Setup Generate a fresh run id following the spec from `skills/squad/SKILL.md`: `Date.now().toString(36) + "-" + 6 chars from [a-z0-9]`. Hold it for the in_flight / terminal telemetry pair. ## Phase 1 — Detect domain artefacts Read-only filesystem probe. **Do not write anything in this phase.** 1. Check for `CONTEXT-MAP.md` at the repo root. - If present → multi-context mode. Parse to enumerate contexts and their `CONTEXT.md` paths. If `--domain` was passed, pin to that one; otherwise infer from the plan text (match nouns against context names; if ambiguous, ask **one** clarifying question before continuing). - If absent → single-context mode. 2. Check for root `CONTEXT.md`. 3. Check for `docs/adr/` directory and enumerate existing ADRs (collect highest number for sequential ID assignment later). **Three possible states**: | State | What you'll find | Entry behaviour | | --------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | | **Established** | `CONTEXT.md` (or map) + at least one ADR present | Read both. Use them as the source of truth to grill against. | | **Partial** | One of the two present | Read what's there; treat the missing artefact as something to create lazily during the session if the need arises. | | **Greenfield** | Neither present | Open with the **3 seed questions** below before starting normal grilling. Create files lazily as resolutions emerge. | ### Greenfield seed questions (only on greenfield state) Ask these three, one at a time, before grilling the plan itself: 1. "In one sentence, what problem does this plan solve, in the user's voice?" 2. "Name the 3 nouns that matter most in this plan. For each, what does it refer to — and is there another word the team has been using for it?" 3. "Is there any decision in this plan that would be expensive to undo six months from now?" These three answers seed `CONTEXT.md` (Q2) and pre-stage potential ADRs (Q3). If the user balks at greenfield setup ("just grill the plan, skip the docs"), respect that and switch to read-only ad-hoc mode for this session — no file creation. ## Phase 1.5 — Write `in_flight` telemetry row Before launching Phase 2's questioning loop, append the in_flight row. Same pattern as `skills/brainstorm/SKILL.md` Step 1.5 and `skills/debug/SKILL.md` Phase A: ``` record_run({ workspace_root: , record: { schema_version: 2, id: , status: "in_flight", started_at: , invocation: "grillme", mode: <"quick" | "normal" | "deep" from flag, default "normal">, mode_source: <"user" if a depth flag was explicit, "auto" otherwise>, git_ref: null, files_count: , agents: [], // grillme runs no subagents by default est_tokens_method: "chars-div-3.5", mode_warning: null, }, }); ``` Non-blocking try/catch per `shared/_Telemetry-Contract.md`: I/O errors log silently; `SquadError` surfaces code + message verbatim. If this write fails, set a flag to skip the Phase 4 finalisation. ## Phase 2 — Question loop The core mechanic. For each iteration: ### 2.1 Pick the next question Prioritise in this order: 1. **Terminology conflicts**: the plan uses a term that contradicts `CONTEXT.md`. Example: "Your glossary defines `Cancellation` as a customer-initiated refund. Your plan uses `cancellation` for an internal admin reversal. Which is it — are these the same concept, or do you mean a different operation?" 2. **Fuzzy nouns**: the plan uses an overloaded word ("account", "user", "session"). Ask the user to disambiguate against the existing glossary. Propose the precise canonical term. 3. **Unspoken decisions**: the plan implies a choice that has alternatives. Surface it: "You're storing this in Postgres — was Redis considered for this hot path? Why Postgres?" 4. **Code contradictions**: read a small slice of the relevant code (`Glob` + `Read`, never `Edit`) and check whether the plan's claim matches reality. If it doesn't, surface: "Your plan says we already debounce this — I see no debounce in `src/foo.ts:42`. Which is right?" 5. **Scenario probes**: invent a concrete scenario that stresses the plan's boundaries. "Customer places an order, then changes their email mid-shipping. Where does the new email live — on the Order, the Customer, or both?" ### 2.2 Ask the question Format: one sentence question, one sentence proposed answer, optional one-line reasoning. ``` Q: Does `Order.cancel()` produce a refund automatically, or is that a separate step the user triggers? My read: separate step — refunds are policy-laden, and the glossary says "Cancellation" is the state change, not the money movement. ``` **Wait for the user's answer before continuing.** Do not stack multiple questions. ### 2.3 Integrate the answer Three possible outcomes per resolution: - **Term resolved** → propose a `CONTEXT.md` update inline. Show the exact diff. Ask: "update CONTEXT.md with this entry?" Apply only on confirmation. Use the format from `CONTEXT-FORMAT.md` (sibling file). - **Decision crystallised** → check the ADR triad (hard to reverse / surprising / real trade-off). If all three are true, propose an ADR. Show the exact file path (`docs/adr/NNNN-short-slug.md`, NNNN = highest existing + 1) and content. Ask before writing. Use the format from `ADR-FORMAT.md` (sibling file). - **Plan revision** → record a note for the final summary; do not touch any file beyond the glossary/ADR. If `--no-write` is set, replace "apply on confirmation" with "emit the patch as a code block for the user to apply themselves." Telemetry still tracks `proposed_writes` count. ### 2.4 Stopping condition End the loop when any of: - The user says "enough", "stop", "done", or equivalent. - The mode budget is hit (`--quick`: 3 Q; `--normal`: 8 Q; `--deep`: 12 Q hard cap). - You've run out of high-value questions — say so explicitly: "I don't have a sharp question left. Want to keep going, or wrap up?" ## Phase 3 — Resolution summary After the loop ends, emit a closing report: ``` # Grill summary — {short topic} ## Terms resolved - **Cancellation**: state change initiated by customer; does NOT trigger a refund. (Added to CONTEXT.md) - **Account**: ambiguous — confirmed to mean **Customer** in the ordering context. (Added to CONTEXT.md "Flagged ambiguities") ## Decisions recorded - ADR-0007: Refunds are a separate flow, not a side-effect of cancellation. (docs/adr/0007-refund-separate-from-cancel.md) ## Plan revisions you mentioned - Stripe webhook handler will treat `payment_intent.canceled` as a no-op when the order is already in `Cancelled` state. ## Open questions (still unresolved) - Does timeout-based auto-cancellation count as "customer-initiated"? (parking lot) ## Next step - `/squad:implement ` — when you're ready to build. - `/squad:grillme --deep ` — if a single thread above needs deeper grilling. ``` If `--no-write` was set, replace "Added to CONTEXT.md" with "Proposed patch (not applied)" and include the patches inline. ## Phase 4 — Finalise telemetry Use the SAME `id` from Phase 1.5: ``` record_run({ workspace_root: , record: { schema_version: 2, id: , status: "completed", // or "aborted" on early stop started_at: , completed_at: , duration_ms: , invocation: "grillme", mode: , mode_source: , git_ref: null, files_count: , agents: [], verdict: null, // grillme runs don't carry a verdict weighted_score: null, // no rubric est_tokens_method: "chars-div-3.5", mode_warning: null, }, }); ``` Same non-blocking try/catch; on `SquadError` write the fallback row per `shared/_Telemetry-Contract.md`. ## Edge Cases - **User says "grill it" but provides no plan text** → ask one clarifying question: "what's the plan? paste it or describe it in 1–2 paragraphs." - **`CONTEXT.md` already exists but means something unrelated** (e.g., onboarding doc) → detect by looking for a `## Language` section. If absent, **do not overwrite**. Ask: "your `CONTEXT.md` looks like an onboarding doc, not a glossary. Want me to use a different file (`docs/CONTEXT.md`?) or rename the existing one?" - **Plan is purely tactical** (one-line bug fix, naming change) → most plans don't need a glossary update. Say so: "this is a tactical change; CONTEXT.md isn't load-bearing here. Want a one-question sanity check instead, or skip?" - **User confirms a term update but the glossary entry already matches** → no-op write; report "no diff, glossary already says this." - **ADR triad not met** → skip the ADR offer entirely. Do not weaken the criteria. - **Multi-context plan touches two domains** → ask the user up front which one is in scope. Don't grill across boundaries in one session — that's two sessions. - **Repo has `CONTEXT-MAP.md` but listed paths don't exist** → flag the stale map as an open question; offer to update it once the session resolves which context applies. ## Boundaries - This skill never edits source code. - This skill never runs state-mutating git commands. - This skill never writes outside `CONTEXT.md`, `CONTEXT-MAP.md`, and `docs/adr/`. - This skill never invents glossary entries — every entry must come from a resolved exchange with the user. - This skill never carries AI attribution into the artefacts it writes. ## Considerations ### Cost vs depth Question counts per mode are in the Inputs table. Token ballpark: `--quick` ~5-10K, `--normal` ~20-40K, `--deep` ~60-100K. Same `--quick` / `--normal` / `--deep` vocabulary as the other squad skills. ### When to use vs alternatives - Use `/squad:grillme` when: you have a plan and want to stress-test it against your project's own language and decisions before building. - Use `/squad:brainstorm` when: you're upstream of a plan — comparing approaches, surveying industry, deciding what to build. - Use `/squad:question` when: you need to look up how the codebase currently works (no plan validation, no Socratic interview). - Use `/squad:implement` when: the plan is hardened and you're ready to build. ### Origin The interview mechanic, the `CONTEXT.md` / ADR file structure, and the ADR triad criteria are adapted from Matt Pocock's `grill-with-docs` skill (MIT, [github.com/mattpocock/skills](https://github.com/mattpocock/skills)). The squad-mcp adaptation adds: telemetry integration, the `--no-write` dry-run mode, the greenfield seed questions, and explicit write-authority gating. See `NOTICE` for attribution.