Knowledge Grounding -- Source Discovery and Answer Provenance
Overview
Discovers available knowledge sources, produces a manifest, routes queries to the best source, and flags ungrounded answers. Companion to env-adoption (which handles tool availability). Two-tier state: persistent manifest (~/.claude/state/sources.json) and volatile session state ($XDG_RUNTIME_DIR/knowledge-grounding/session-<id>.json).
When to Use
- Session start (after env-adoption) -- discover available knowledge sources
- Before answering factual questions -- check what sources can ground the answer
- On air-gapped / enterprise systems -- detect what is reachable
- When a query returns training-only results -- flag explicitly with tier
- When
strict_airgap: true -- enforce user override for ungrounded answers
When NOT to Use
- Do not replace wiki auto_consult -- this skill composes with
.wiki-link behavior
- Do not use for tool availability -- that is env-adoption
- Do not use for search execution -- that is web-research, wiki, confluence-rest-api
Operations
| Operation |
Command |
Purpose |
| discover |
bash ~/.claude/skills/knowledge-grounding/scripts/discover.sh discover |
Scan local sources, internet canary, write manifest |
| status |
bash ~/.claude/skills/knowledge-grounding/scripts/discover.sh status |
Human-readable knowledge landscape |
| get |
bash ~/.claude/skills/knowledge-grounding/scripts/discover.sh get <path> |
Shell-friendly accessor (thin jq wrapper) |
discover flags
| Flag |
Effect |
--force |
Re-probe even if manifest is fresh (<24h) |
--remote |
Also probe remote endpoints immediately (adds latency) |
--silent |
No stdout, just write state files |
--json |
Output combined manifest + session as JSON |
get paths
discover.sh get internet_reachable # true/false
discover.sh get grounding_mode # internal-only / full
discover.sh get strict_airgap # true/false
discover.sh get sources.wiki_trading.path # /path/to/wiki
discover.sh get sources.internet.reachable # true/false
discover.sh get session.active_sources # JSON array
Routing Logic (per-query priority)
When answering a factual question, check sources in this order. Stop at the first tier that produces a match. Combine if multiple tiers contribute.
| Priority |
Source Type |
Check |
Skill/Tool |
| 1 |
Wiki (auto_consult first) |
grep for keywords |
wiki skill |
| 2 |
Project docs (local) |
grep docs/, PROJECT.md, COMPONENT.md |
Read/Grep |
| 3 |
Git repo docs (local) |
grep configured doc_paths |
Read/Grep |
| 4 |
Vector store |
semantic search if configured |
research-vectorization |
| 5 |
Confluence (remote, lazy) |
CQL search |
confluence-rest-api |
| 6 |
Jira (remote, context) |
JQL search |
jira-rest-api |
| 7 |
Internet |
web search |
web-research (only if internet_reachable: true) |
| 8 |
Training data |
always available |
flag explicitly as tier 4 |
Manifest provides facts only. This routing logic decides per-query.
Grounding Tiers
| Tier |
Label |
Meaning |
When to use |
| 1 |
verified |
Direct match in wiki, Confluence, or git docs with citation |
Source found, content matches query |
| 2 |
grounded |
Partial match or semantic similarity from vector/multi-source |
Related content found, synthesized |
| 3 |
inferred |
Cross-referenced from multiple weak signals |
No direct match, patterns align |
| 4 |
training-only |
No internal source -- model training knowledge only |
Nothing found; flag explicitly |
Every answer should include grounding metadata:
[Grounding: verified | source: wiki_trading/page-name][Grounding: training-only | no internal sources matched]
In strict_airgap mode (opt-in), tier 4 answers require explicit user override: "No internal source found. This would use model training data (cutoff May 2025). Proceed? [y/n]"
Integration
| Touchpoint |
Behavior |
| CLAUDE.md session start |
After env-adoption, run discover.sh discover --silent |
| forge step 1 |
Read sources.json, include active sources in shared_context |
| web-research |
Check internet_reachable before attempting search; suggest local sources if false |
| wiki auto_consult |
Unchanged -- grounding skill defers to existing .wiki-link behavior |
| All answers |
Append grounding metadata (tier + source citation) when answering factual questions |
See references/integration.md for detailed patterns.
Anti-Patterns
| Don't |
Why |
Do Instead |
| Replace wiki auto_consult |
Breaks existing behavior, two routing paths |
Defer to .wiki-link, augment with sources |
| Probe remote endpoints at session start |
Hangs on air-gapped systems, violates <3s |
Lazy probe on first query needing remote source |
| Bake routing logic into manifest JSON |
Routing rules change, manifest becomes stale policy |
Manifest = facts, SKILL.md = routing logic |
| Score confidence by source type alone |
Stale wiki page is not better than training data |
Consider match quality, freshness, provenance |
| Block on training-only answers by default |
Most systems are not strict air-gap |
strict_airgap is opt-in, default=off |
| Auto-detect enterprise endpoints |
URLs are not discoverable, wrong guesses waste time |
Config file for enterprise, auto-detect for local |
See also
rag-architecture — once a vector store is the chosen source, this covers how to build one that
retrieves the right thing and how to prove it does.llm-api-optimization — the cost of what you ground with, and when a cached corpus beats retrieval.
1---2name: knowledge-grounding3description: Use when checking what knowledge sources are available (wikis, docs, Confluence, Jira, vector stores, internet), determining grounding mode (internal-only vs full), routing queries to the best source, or flagging ungrounded answers. Covers source discovery, air-gap detection, grounding tiers (verified/grounded/inferred/training-only), and strict_airgap enforcement.4---56# Knowledge Grounding -- Source Discovery and Answer Provenance78## Overview910Discovers available knowledge sources, produces a manifest, routes queries to the best source, and flags ungrounded answers. Companion to env-adoption (which handles tool availability). Two-tier state: persistent manifest (`~/.claude/state/sources.json`) and volatile session state (`$XDG_RUNTIME_DIR/knowledge-grounding/session-<id>.json`).1112## When to Use1314- Session start (after env-adoption) -- discover available knowledge sources15- Before answering factual questions -- check what sources can ground the answer16- On air-gapped / enterprise systems -- detect what is reachable17- When a query returns training-only results -- flag explicitly with tier18- When `strict_airgap: true` -- enforce user override for ungrounded answers1920## When NOT to Use2122- Do not replace wiki auto_consult -- this skill composes with `.wiki-link` behavior23- Do not use for tool availability -- that is env-adoption24- Do not use for search execution -- that is web-research, wiki, confluence-rest-api2526## Operations2728| Operation | Command | Purpose |29|-----------|---------|---------|30| **discover** | `bash ~/.claude/skills/knowledge-grounding/scripts/discover.sh discover` | Scan local sources, internet canary, write manifest |31| **status** | `bash ~/.claude/skills/knowledge-grounding/scripts/discover.sh status` | Human-readable knowledge landscape |32| **get** | `bash ~/.claude/skills/knowledge-grounding/scripts/discover.sh get <path>` | Shell-friendly accessor (thin jq wrapper) |3334### discover flags3536| Flag | Effect |37|------|--------|38| `--force` | Re-probe even if manifest is fresh (<24h) |39| `--remote` | Also probe remote endpoints immediately (adds latency) |40| `--silent` | No stdout, just write state files |41| `--json` | Output combined manifest + session as JSON |4243### get paths4445```bash46discover.sh get internet_reachable # true/false47discover.sh get grounding_mode # internal-only / full48discover.sh get strict_airgap # true/false49discover.sh get sources.wiki_trading.path # /path/to/wiki50discover.sh get sources.internet.reachable # true/false51discover.sh get session.active_sources # JSON array52```5354## Routing Logic (per-query priority)5556When answering a factual question, check sources in this order. Stop at the first tier that produces a match. Combine if multiple tiers contribute.5758| Priority | Source Type | Check | Skill/Tool |59|----------|-----------|-------|------------|60| 1 | Wiki (auto_consult first) | grep for keywords | wiki skill |61| 2 | Project docs (local) | grep docs/, PROJECT.md, COMPONENT.md | Read/Grep |62| 3 | Git repo docs (local) | grep configured doc_paths | Read/Grep |63| 4 | Vector store | semantic search if configured | research-vectorization |64| 5 | Confluence (remote, lazy) | CQL search | confluence-rest-api |65| 6 | Jira (remote, context) | JQL search | jira-rest-api |66| 7 | Internet | web search | web-research (only if `internet_reachable: true`) |67| 8 | Training data | always available | flag explicitly as tier 4 |6869**Manifest provides facts only. This routing logic decides per-query.**7071## Grounding Tiers7273| Tier | Label | Meaning | When to use |74|------|-------|---------|------------|75| 1 | **verified** | Direct match in wiki, Confluence, or git docs with citation | Source found, content matches query |76| 2 | **grounded** | Partial match or semantic similarity from vector/multi-source | Related content found, synthesized |77| 3 | **inferred** | Cross-referenced from multiple weak signals | No direct match, patterns align |78| 4 | **training-only** | No internal source -- model training knowledge only | Nothing found; flag explicitly |7980Every answer should include grounding metadata:81- `[Grounding: verified | source: wiki_trading/page-name]`82- `[Grounding: training-only | no internal sources matched]`8384In `strict_airgap` mode (opt-in), tier 4 answers require explicit user override: "No internal source found. This would use model training data (cutoff May 2025). Proceed? [y/n]"8586## Integration8788| Touchpoint | Behavior |89|-----------|----------|90| **CLAUDE.md session start** | After env-adoption, run `discover.sh discover --silent` |91| **forge step 1** | Read sources.json, include active sources in shared_context |92| **web-research** | Check `internet_reachable` before attempting search; suggest local sources if false |93| **wiki auto_consult** | Unchanged -- grounding skill defers to existing `.wiki-link` behavior |94| **All answers** | Append grounding metadata (tier + source citation) when answering factual questions |9596See `references/integration.md` for detailed patterns.9798## Anti-Patterns99100| Don't | Why | Do Instead |101|-------|-----|------------|102| Replace wiki auto_consult | Breaks existing behavior, two routing paths | Defer to .wiki-link, augment with sources |103| Probe remote endpoints at session start | Hangs on air-gapped systems, violates <3s | Lazy probe on first query needing remote source |104| Bake routing logic into manifest JSON | Routing rules change, manifest becomes stale policy | Manifest = facts, SKILL.md = routing logic |105| Score confidence by source type alone | Stale wiki page is not better than training data | Consider match quality, freshness, provenance |106| Block on training-only answers by default | Most systems are not strict air-gap | strict_airgap is opt-in, default=off |107| Auto-detect enterprise endpoints | URLs are not discoverable, wrong guesses waste time | Config file for enterprise, auto-detect for local |108109## See also110111- `rag-architecture` — once a vector store is the chosen source, this covers how to build one that112 retrieves the right thing and how to prove it does.113- `llm-api-optimization` — the cost of what you ground with, and when a cached corpus beats retrieval.
joogy06