| name | grill-with-docs |
| description | Interrogate a plan against the project's documented decisions and domain language — challenging fuzzy terms, cross-referencing the code, and surfacing where the plan contradicts an existing ADR or canonical contract. Use when the user wants a plan stress-tested against what the project has already decided, rather than in the abstract. Prefer plain grill-me when there is no documented model to test against, and plan-context-loader when the goal is to gather vault context rather than be questioned. |
| allowed-tools | Read, Grep, Glob, Bash, Agent, mcp__obsidian__view, mcp__obsidian__get_workspace_files |
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.
Domain awareness
In this repo the documented model lives in the Obsidian vault under docs/, not in a root
CONTEXT.md. Read from these before challenging anything:
| Authority | Where |
|---|
| Accepted decisions | docs/ADR/ (6-digit files, status: accepted, no inbound supersedes) |
| Canonical contracts | docs/plan/ — e.g. knowledge-trail-core-concept.md |
| Architecture invariants | docs/wiki/architecture/, docs/wiki/HOME.md |
| Known gaps / remediation | docs/review/ |
| Operational constraints | docs/runbooks/ |
docdag resolve <id> gives the current successor of an ADR, so you challenge
against the live decision rather than a superseded one.
There is no glossary file in this repo today. When a term genuinely needs pinning down, resolve it in
the conversation and record it in the relevant docs/plan/ contract — and ask before creating any new
document, since an unrequested glossary file becomes a second source of truth nobody maintains.
During the session
Challenge against the documented language
When the user uses a term that conflicts with how the vault defines it, call it out immediately.
"knowledge-trail-core-concept.md uses 'footprint' for X, but you seem to mean Y — which is it?"
Watch for vocabulary from superseded designs being used as if current — Knowledge Loop terms
(4-bucket, primary surface /loop) are historical per [[000940]] and must not be treated as the
live contract.
Sharpen fuzzy language
When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."
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 code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
Capture resolved terms as you go
When a term gets pinned down, note it in your running summary rather than batching it to the end —
the precision is what the session is for, and it evaporates if you defer it.
Writing it into a docs/plan/ contract is a separate, user-approved edit. Ask first.
Offer ADRs sparingly
Only offer to create an ADR when all three are true:
- Hard to reverse — the cost of changing your mind later is meaningful
- Surprising without context — a future reader will wonder "why did they do it this way?"
- The result of a real trade-off — there were genuine alternatives and you picked one for specific reasons
If any of the three is missing, skip the ADR.
When one is warranted, hand off to the alt-adr-writer skill rather than inventing a format here.
This repo has one ADR convention — 6-digit numbering, docs/ADR/template.md sections, wikilink
[[000NNN]] cross-references, a fixed tag list — and a second format competing with it produces
records that Obsidian's graph and docdag cannot read.
