grill-with-docs

name	grill-with-docs
description	Grilling session that challenges your plan against the existing domain model. Sharpens terminology and updates CONTEXT.md and ADRs inline. Use when user says "grill with docs", "challenge my plan", "domain review", or wants to refine a plan against existing documentation.

Grill With Docs

A grilling session — but grounded in the project's domain model. You challenge the user's plan against existing documentation, sharpen vague terminology, and update docs inline.

Before you start

1. Read CONTEXT.md (or equivalent domain glossary) if it exists
2. Read docs/adr/ for existing architectural decisions
3. Understand the domain vocabulary before asking questions

The Grill

Rules

1. One question at a time. Don't front-load.
2. Challenge terminology. If the user uses a term not in CONTEXT.md, stop and clarify:
   • "You said 'sync' — do you mean real-time replication or periodic batch update?"
   • Then propose a CONTEXT.md entry for the agreed definition
3. Discuss concrete scenarios. "What happens when X fails?" / "Walk me through a user doing Y."
4. Cross-reference with code. "The current UserService already handles Z — is this replacing it or extending it?"
5. Identify decisions. When a trade-off emerges, name it:
   • "This is a decision: eager vs lazy loading. Want me to draft an ADR?"

Inline documentation updates

As the conversation clarifies things:

• New term agreed -> Propose a CONTEXT.md addition (see CONTEXT-FORMAT.md)
• Trade-off resolved -> Offer to create an ADR (see ADR-FORMAT.md)
• Contradiction found -> Flag it: "CONTEXT.md says X but you're describing Y"

When to stop

Stop when:

• Every branch of the decision tree has been resolved
• The user has a clear next action
• All new terms are proposed for CONTEXT.md
• Hard-to-reverse decisions have ADR drafts

When you hit a wall (gap → learn → resume)

When the user (or you) hits something not understood mid-grill, do NOT let it derail the session or pollute the grill context. Classify the gap first, then route.

Gap classifier (deterministic — not a judgment call)

• Fact gap — the answer is discoverable in the codebase, docs, ADRs, or public sources ("what does UserService.sync actually do?", "what's Kueue's default preemption policy?"). The user does not need to learn it to keep grilling.
• Concept gap — the user wants to genuinely understand a concept to make the decision themselves (Matt Pocock's junior-dev case). Handing them an answer defeats the point.

If discoverable by lookup → fact. Otherwise, and the user signals "I want to understand this" → concept.

Fact path → isolated subagent (keeps grill context clean)

Dispatch the lookup to a subagent so the main grill context stays uncontaminated (this is our harness's replacement for Matt's manual /handoff→learn→return dance — the subagent has its own context window and returns only a brief):

Agent(subagent_type="research" | "general-purpose", model="haiku",
      prompt="Answer ONLY: <fact question>. Search codebase/docs (use codegraph if code). Return a <150-word brief + source paths. No preamble.")

Splice the returned brief into the grill and continue. Never dump the subagent's full transcript into the grill — brief only ([[ecc-token-strategy]] 2K rule, [[subagent-model-routing]] lookup=haiku).

Concept path → anchor, then human learns (teach stays explicit)

The user learns this themselves. teach is disable-model-invocation (deliberately heavyweight) — do NOT auto-invoke it. Instead:

1. Save a resume anchor via the handoff skill's Resume Anchor section (where we stopped, the open grill question, undecided trade-offs). This is the return path Matt's manual flow lacks.
2. Recommend the user run /teach <concept> in a learning workspace, then come back.
3. On return, reload the anchor + the newest learning-records/*.md from the teach workspace and resume the exact grill question — do not restart the grill.

Honest limit: once you notice the gap the main context is already partly polluted, so "clean resume" is only fully true for the fact path (handled by a subagent from the start). The concept path approximates it via anchor + /clear + resume.

Close the loop (learning compounds)

When a concept was learned, route its one-paragraph takeaway into our memory layer (memory/topics/, Lessons) — NOT a new silo ([[memory-hot-loop]]: route, don't duplicate). Then verify the originally-stuck grill item is now resolved before closing ([[close-the-agent-loop]]).

After the Grill

Summarize:

1. Decisions made (with ADR references if created)
2. Terms defined (with CONTEXT.md updates)
3. Open questions (anything still unresolved)
4. Recommended next step