grounding

What this skill does

# Grounding

Plans built on wrong assumptions create the worst class of refactor — the kind discovered only after the work is mostly done. This skill probes the assumptions in the current discussion against real evidence (codebase, MCPs, CLIs, registered repo SMEs, docs) and surfaces what holds, what doesn't, and what's still unclear, **iteratively** — walking down the decision tree branch by branch — so the plan can be corrected while it's still cheap, AND so the surfaced decisions persist in the project's own documentation.

The goal is **not** to be exhaustive. It's to find the load-bearing assumptions, verify them, and capture what was learned.

## Usage

```
/grounding [idea to ground] [--deep] [--background]
```

- `[idea to ground]` *(string, optional)* — the plan, claim, or approach to pressure-test. When omitted, grounds the most recent plan, claim, or proposed approach in the conversation.
- `--deep` *(flag, optional)* — force delegation to the `grounding-investigator` agent (out-of-thread probing) even for a small decision tree. Also triggered by phrasing like "deeply" or "really pressure-test this".
- `--background` *(flag, optional)* — run the investigator in the background and report when it lands, rather than blocking the thread.

## How grounding works

Grounding follows the **grill-with-docs protocol** (canonical at `docs/protocols/grill-with-docs.md` at the marketplace root; a copy ships with this skill at `references/grill-with-docs.md`). Read that file first — it owns the seven-phase mechanic:

1. **Restate** the plan or idea in 1-2 sentences
2. **Decompose, then map the decision tree** — split compound claims into atomic ones, state each in falsifiable IF/THEN form, order branches by how load-bearing they are (downstream fan-out × blast-radius-if-wrong)
3. **Probe before asking** — try to resolve from evidence (codebase, SME repos, MCPs, CLIs, docs) before going to the user; a branch is resolved only when its chain bottoms out in a real artifact, not another unverified claim
4. **Ask one question at a time** — only for branches that genuine intent/domain/constraint queries can resolve; always include a recommended answer
5. **Sharpen vocabulary along the way** — challenge terms against `CONTEXT.md`, propose canonical names, cross-reference user claims with code
6. **Write decisions where they belong** — `CONTEXT.md` for terms, `docs/adr/` for hard-to-reverse decisions, inline as they crystallise
7. **Report** in a compact resolved / open / contradictions structure

This skill is the **grounding-specific layering** on top of that protocol — what evidence sources to rank, what assumption shapes to look for, and how to handle no-source-available cases.

## When this skill runs

Trigger proactively when the discussion shows any of these signals:

- **Planning language** — "I think we should...", "we'll need to...", "the approach is...", "let's just...", "I'll wire X to Y..."
- **Claims about external systems** — "the Linear API supports cycles", "Resend allows webhook signing", "the library handles retry"
- **Claims about the codebase** — "we already have a User model", "the auth middleware does X"
- **Architectural assertions** — "we can run this on a single instance", "Postgres handles this fine at our scale"
- **A plan-mode plan is being finalized** — verify before approval
- **Explicit invocation** — `/ground`, "ground this", "pressure-test this", "what am I missing", "is this real", "grill me", "stress-test this"

Do **not** run when:

- The user is asking a direct factual question — just answer it, do not turn it into an investigation
- The user is mid-edit on uncontroversial code
- The same plan has already been grounded earlier in this session and hasn't materially changed
- The user is brainstorming divergent options — wait until they converge on a direction
- The idea is small enough that probing is more expensive than just trying it

## Grounding-specific layer

The protocol gives you the mechanic. The pieces below are what makes the mechanic effective for the kind of grounding this plugin does — verifying technical claims against real-world evidence, fast.

### Start with a source inventory

Before probing individual branches, run the bundled inventory script once to learn what evidence this environment actually offers:

```bash
bash scripts/inventory-sources.sh
```

It reports, in a single pass: which probe CLIs are installed (`gh`, `linear`, `az`, `node`, `git`, …), what `package.json` scripts the project exposes, whether the project has a `CONTEXT.md` / `CONTEXT-MAP.md` / `docs/adr/`, whether any SME repos are registered under `~/.claude/repo-sme/`, and whether the user's global (`~/.claude/grounding/tripwires.md`) or project (`<repo>/.claude/grounding/tripwires.md`) tripwire files have live entries.

Probing from a known inventory beats rediscovering sources branch by branch — and it tells you *up front* which branches are headed for **⚠ No source available**, so you don't burn a probe finding that out. The script is filesystem-only by design: MCP tools aren't visible to it, so check the session's tool list for those yourself. Its output is a working aid — read it, act on it, but never paste it into the report.

### Evidence-source ranking

When Phase 3 of the protocol says "probe before asking," grounding ranks sources in this order:

| Rank | Source | When to reach for it |
|---|---|---|
| 1 | **Skills listed in the system reminder** (`repo-sme:*`, `microsoft-docs:*`, `azure:*`, `project-manager:*`) | First-class probes — invoke them rather than reinventing |
| 2 | **MCP tools** wired into this session (Linear, Figma, Slack, Azure, Microsoft Learn) | Use `ToolSearch` to load schemas before calling |
| 3 | **CLI tools** — `gh`, `linear`, `az`, project-local CLIs in `package.json` scripts | `command -v <tool>` to probe availability |
| 4 | **Registered SME repos** at `~/.claude/repo-sme/` | Cloned external library sources, or use the `repo-sme-expert` agent |
| 5 | **Project filesystem** — Read, Grep, Glob | For codebase-state claims |
| 6 | **Git history** — `git log`, `git blame`, `git grep` | For past-decision claims |
| 7 | **Web** — `WebFetch` / `WebSearch` | **Last resort.** Local sources are more authoritative |

If a critical assumption has **no available source**, surface that as part of the report (see "No source available" below) rather than silently skipping it.

### Assumption taxonomy

Grounding-shaped claims tend to fall into a small set of categories. Use this table to make sure you're not missing one when mapping the decision tree in Phase 2 of the protocol:

| Category | Example | Where to verify |
|---|---|---|
| External API behavior | "GitHub's API returns commits in author-date order" | MCP / CLI / SME repo / docs |
| Library / SDK semantics | "nodemailer supports OAuth2 token refresh" | SME repo / source / docs |
| Codebase state | "we already have a `Subscription` model" | Read / Grep / git log |
| Schema / data shape | "users have at most one billing address" | Schema files / data sample |
| Past attempt history | "we tried this approach last quarter" | git log / PR history / project notes |
| Constraint validity | "we can't change the database engine" | User / docs / decision records |
| Compatibility | "this works with Node 20" | package.json engines / runtime docs |
| Domain rule | "every order has a customer" | User / domain docs / `CONTEXT.md` |
| Capacity / scale | "Postgres handles this at our load" | Metrics dashboard / past benchmarks |
| Integration availability | "the Slack workspace has the right scopes" | MCP test call / admin |

### Personal tripwires

Tripwires capture patterns this user has been burned by before. Treat tripwire matches as **priority branches** — verify them even when they look unimportant.

The live tripwire list lives **outside the plugin tree** so it survives plugin updates — read the **union** of two user-owned files, whichever exist:

- **`~/.claude/grou