Context Grounding Brief

---
name: context-grounding-brief
description: Use when preparing a non-trivial coding task to send to an AI. Builds the context bundle (schema, types, signatures) that prevents hallucinations. Triggers on "before I prompt", "ground this task", or "what context do I paste".
---

# Context Grounding Brief

The model will invent what it doesn't know. The defense is to make sure it knows. Before sending a non-trivial coding task, assemble the source-of-truth surfaces it'll touch and paste them with the request.

This skill produces that bundle, scoped to the task.

## Required inputs

1. **The task** — what the AI will be asked to build, in 1-3 sentences
2. **The surfaces it touches**, with at least:
   - Database tables / schema (or "none")
   - External APIs / libraries
   - Internal modules it'll call
   - Types/interfaces it'll need to match
3. **Repo conventions** if relevant — naming, patterns, framework version

If a surface is mentioned but no source-of-truth provided, ask before assembling. Don't infer schema fields, don't guess at types.

## Method

For each surface in the task, decide three things:

### 1. What to paste

The minimal, exact source-of-truth the AI needs to write correct code:
- Schema: the relevant fields, not the whole schema
- Library: the exact function signatures it'll call, plus version
- Internal: function signatures, return types, any error contract
- Types: the interface or type, not the whole types file

### 2. What to leave out

Context that's irrelevant just dilutes attention. Strip:
- Unrelated tables / fields
- Types not in the call path
- Framework boilerplate the AI clearly already knows

### 3. What to call out explicitly

Things the AI will not infer from code alone:
- Naming conventions ("we use snake_case for DB columns, camelCase for TS")
- Invariants ("orders.user_id is always set, even for guest checkouts — guests get a synthetic user row")
- Version gotchas ("we're on Stripe API 2024-06-20; `payment_intent.amount_received` doesn't exist before 2023")
- Patterns the codebase prefers ("we wrap all DB calls in withTx; never call pool.query directly")

## Output format

```
## Context

### Schema (relevant fields only)
[fields the task touches, with types]

### Library APIs
[function signatures the task will call, with version]

### Internal functions
[signatures of internal helpers it'll use]

### Conventions
- [invariant]
- [invariant]

### Out of scope (don't touch)
- [files/areas the AI should leave alone]
```

Then a one-line summary of what to paste *after* the context block: "Now write: [the actual task]."

## Anti-patterns

- Pasting the entire schema / types file — buries the signal
- Generic conventions ("write good code") — the AI won't change behavior on this
- Skipping version info — most hallucinations cluster on version-specific APIs
- Asking the AI to "use best practices" — undefined in this codebase

## Tone

- Concise. The bundle is meant to be pasted, not read.
- Concrete. Real signatures, real field names, real versions.
- Pragmatic. Skip what the AI knows; include what it can't infer.