Onboard the article of query performance tuning

.github/agents/skill-reviewer/rubric.md

@@ -13,7 +13,7 @@ The single highest-leverage check. The frontmatter `description` is loaded every
 Grade against three questions:
 
 1. **Triggers.** Does it list at least 2–3 concrete situations the user might be in? ("Use when designing a new schema, migrating from SQL, deciding between embedding and referencing…") A description that says only *what* the skill is, not *when* to invoke it, fails this check.
-2. **Differentiation.** Could the description plausibly match another skill in the same kit? If `documentdb-indexing` and `documentdb-query-optimization` could trade descriptions and nothing would change, both descriptions are too generic.
+2. **Differentiation.** Could the description plausibly match another skill in the same kit? If `documentdb-indexing` and `documentdb-query-optimizer` could trade descriptions and nothing would change, both descriptions are too generic.
 3. **Length.** Anthropic's hard limit is 1024 characters. Practical sweet spot is 200–500 characters: long enough to list real triggers, short enough that the routing model reads it cleanly. < 80 chars is almost always too vague. > 800 chars usually means the body leaked into the description.
 
 | Grade | Rule |

AGENTS.md

@@ -58,7 +58,6 @@ These skills each describe a feature area and link to short rule files with inco
 | Skill | Folder | When to use |
 |---|---|---|
 | `documentdb-data-modeling` | `skills/data-modeling/` | Designing schemas, embed vs reference, 16 MB limit, denormalization, schema versioning |
-| `documentdb-query-optimization` | `skills/query-optimization/` | Writing queries that use indexes; reading `explain("executionStats")` |
 | `documentdb-indexing` | `skills/indexing/` | Choosing the right index type (single / compound / multikey / wildcard / hashed / 2dsphere / TTL); ESR ordering; query-pattern → index-shape cookbook; safe index lifecycle (`hideIndex` → `dropIndex`) |
 | `documentdb-driver` | `skills/driver/` | Singleton `MongoClient`, connection reuse fundamentals |
 | `documentdb-vector-search` | `skills/vector-search/` | `cosmosSearch` with DiskANN / HNSW / IVF, PQ, fp16, cosine normalization |
@@ -78,16 +77,21 @@ These skills walk the user (or another agent) through a task end-to-end.
 | `documentdb-azure-deployment` | `skills/azure-deployment/` | Provisioning an Azure DocumentDB cluster (`Microsoft.DocumentDB/mongoClusters`) via Bicep, Azure CLI, Terraform, or portal; firewall rules; connection string retrieval |
 | `documentdb-natural-language-querying` | `skills/natural-language-querying/` | "How do I query…", "filter / group / aggregate…", SQL → MQL translation (read-only queries only) |
 | `documentdb-query-optimizer` | `skills/query-optimizer/` | "Why is this slow?", index review, `explain()`-driven tuning; loads `references/core-indexing-principles.md` |
+| `documentdb-query-performance-tuning` | `skills/query-performance-tuning/` | End-to-end tuning methodology: reading DocumentDB's Postgres-backed `explain("executionStats")`, the ESR rule, index-backed sorts, covered queries, finding slow queries via Log Analytics `VCoreMongoRequests`; loads `references/documentdb-explain-output.md` |
 | `documentdb-connection` | `skills/connection/` | Pool-size / timeout / retry tuning for serverless, OLTP, OLAP, or bursty workloads |
 
 ## Routing hints for agents
 
 These map a task to the best **Route B (text) skill**. (On **Route A** — when the
 user said *"use toolbox"* — route the same task through `knowledge-base/kb-route.sh`
-to a diagnostic script instead.)
+to a diagnostic script instead.) `kb-route.sh` can also deterministically surface
+the best-matching **skill** for these Route-B tasks (`--skills`, or the
+`skill_match` / `recommended` fields in `--json` output) if you want a scored pick
+rather than reading the table below.
 
 - **Writing / generating a query** → `documentdb-natural-language-querying`
 - **"Why is this query slow / how do I index this?"** → `documentdb-query-optimizer`
+- **"How do I read explain output / what is the ESR rule / how do I tune query performance / find slow queries in prod"** → `documentdb-query-performance-tuning`
 - **"Which index type should I use / design this index"** → `documentdb-indexing`
 - **Designing a schema / data model** → `documentdb-data-modeling`
 - **Adding vector search to a RAG app** → `documentdb-vector-search`

README.md

@@ -15,6 +15,8 @@ Skills follow the [Agent Skills](https://agentskills.io/) format and the kit shi
 
 👉 **Capabilities and skill catalog:** [`docs/SKILLS.md`](docs/SKILLS.md)
 
+👉 **New here? 10-minute quick start:** [Find & fix a slow query](docs/quickstart-find-and-fix-slow-queries.md) — run DocumentDB locally, load sample data, and let your AI assistant diagnose a `COLLSCAN` and fix it with one index (a full 50,000-document scan → a tiny index lookup).
+
 ## Diagnostic Toolbox — Quickstart
 
 Beyond the text skills, the kit ships **deterministic diagnostic scripts** and a
@@ -45,10 +47,10 @@ is baked in** — set `DB_PASSWORD` (or pass `--password`).
 
 ```bash
 # 0. start a local DocumentDB container (choose any password; the scripts read it)
+export DB_PASSWORD='<choose-a-password>'   # the scripts require this (or --password)
 docker run -dt --name documentdb-local -p 10260:10260 \
-  -e USERNAME=docdbadmin -e PASSWORD=Test1234 \
+  -e USERNAME=docdbadmin -e PASSWORD="$DB_PASSWORD" \
   ghcr.io/microsoft/documentdb/documentdb-local:latest
-export DB_PASSWORD=Test1234          # the scripts require this (or --password)
 
 # 1. seed demo data
 bash scenarios/ecommerce/seed.sh           # -> "ecommerce"
@@ -60,6 +62,9 @@ bash scripts/index-redundancy-finder.sh --db ecommerce
 
 # 3. or ask in natural language — the router picks the tool (no LLM, no container)
 bash knowledge-base/kb-route.sh --db contoso "why are my aggregations slow even though I have indexes"
+
+# the same router also picks the best text skill for guidance questions
+bash knowledge-base/kb-route.sh --skills   # or: kb-route.sh "how do I read explain output"
 ```
 
 Demo datasets are seeders under [`scenarios/`](scenarios/) (they plant the
@@ -80,7 +85,7 @@ skills/
     SKILL.md             # agent-facing activation + instructions
     references/          # reference docs the skill loads at runtime
 scripts/                 # diagnostic toolbox — read-only analyzers + seeders
-knowledge-base/          # NL → script router (kb.json + kb_route.py) + demo
+knowledge-base/          # NL → script + skill router (kb.json + kb_route.py) + demo
 scenarios/contoso/       # ready-to-run TOAST demo dataset (+ optional scaling-benchmark/)
 testing/                 # fixture-first regression suite for the scripts (pytest)
 token-tests/             # measured token savings of scripts vs text-skill workflows

docs/DIAGNOSTICS.md

@@ -26,15 +26,15 @@ password; the scripts read it from `DB_USER` (default `docdbadmin`) and
 `DB_PASSWORD` — **nothing is baked in**:
 
 ```bash
+# the scripts require a password — export it once (or pass --password each time)
+export DB_PASSWORD='<choose-a-password>'
+
 docker run -dt --name documentdb-local \
   -p 10260:10260 \
   -e USERNAME=docdbadmin \
-  -e PASSWORD=Test1234 \
+  -e PASSWORD="$DB_PASSWORD" \
   ghcr.io/microsoft/documentdb/documentdb-local:latest
 
-# the scripts require a password — export it once (or pass --password each time)
-export DB_PASSWORD=Test1234
-
 # preflight: confirm the engine answers (should print "1")
 docker exec documentdb-local psql -h localhost -p 9712 -U documentdb -d postgres -tAc "SELECT 1"
 ```
@@ -96,7 +96,7 @@ python3 knowledge-base/kb_route_demo.py "which indexes can I drop"
 # apply the schema split the advisor recommends, then re-run the advisor
 docker cp scenarios/contoso/contoso-split-fix.js documentdb-local:/tmp/fix.js
 docker exec -e CONTOSO_DB=contoso documentdb-local mongosh \
-  "localhost:10260/contoso" -u docdbadmin -p Test1234 \
+  "localhost:10260/contoso" -u docdbadmin -p "$DB_PASSWORD" \
   --authenticationMechanism SCRAM-SHA-256 --tls --tlsAllowInvalidCertificates \
   --quiet --file /tmp/fix.js
 bash scripts/document-bloat-advisor.sh --db contoso     # opportunities now clean

docs/SKILLS.md

@@ -19,7 +19,6 @@ why it matters → incorrect example → correct example → references.
 |---|---|---|
 | [`data-modeling/`](../skills/data-modeling/) | `model-` | Embed vs reference, 16 MB limit, denormalization, schema versioning |
 | [`sharding/`](../skills/sharding/) | `sharding-` | When to shard vs stay single-shard, shard-key selection (read-heavy vs write-heavy), logical/physical shard mental model, scale-up vs scale-out, hot-partition diagnosis, `sh.shardCollection` / `sh.reshardCollection`, 4 TB logical-shard budget |
-| [`query-optimization/`](../skills/query-optimization/) | `query-` | `explain("executionStats")`, avoiding `COLLSCAN` |
 | [`indexing/`](../skills/indexing/) | `index-` | Index-type selection (single / compound-ESR / multikey / wildcard / hashed / 2dsphere / TTL), query-pattern → index-shape cookbook, index budget, safe `hideIndex` → `dropIndex` lifecycle |
 | [`driver/`](../skills/driver/) | `driver-` | MongoDB driver/SDK usage (singleton client, pooling) |
 | [`vector-search/`](../skills/vector-search/) | `vector-` | `cosmosSearch` with DiskANN / HNSW / IVF, PQ, fp16 |
@@ -39,15 +38,19 @@ Single-purpose skills the agent loads when its trigger description matches.
 | [`mcp-setup/`](../skills/mcp-setup/) | Configuring the DocumentDB MCP server (connection string, transport, shell profile) |
 | [`azure-deployment/`](../skills/azure-deployment/) | Provisioning an Azure DocumentDB cluster (`Microsoft.DocumentDB/mongoClusters`) — Bicep (with Key Vault), Azure CLI one-shot, Terraform pointer, firewall, connection string, teardown. See also [`examples/azure-deployment/`](../examples/azure-deployment/) for a no-agent ready-to-run deploy. |
 | [`natural-language-querying/`](../skills/natural-language-querying/) | "How do I query…", filter/aggregate/group requests, SQL → MQL translation |
-| [`query-optimizer/`](../skills/query-optimizer/) | "Why is this query slow?", index review, `explain()`-driven tuning (indexing deep-dive lives in its `references/`) |
+| [`query-optimizer/`](../skills/query-optimizer/) | "Why is this query slow?", index review, `explain()`-driven tuning, and **verifying** a query uses an index vs `COLLSCAN` (absorbs the former `query-optimization` rule); indexing deep-dive + explain-verification live in its `references/` |
+| [`query-performance-tuning/`](../skills/query-performance-tuning/) | End-to-end tuning methodology: read DocumentDB's Postgres-backed `explain("executionStats")`, the ESR rule, index-backed sorts, covered queries, and finding slow queries via Log Analytics `VCoreMongoRequests` (explain field glossary lives in its `references/`) |
 | [`connection/`](../skills/connection/) | Connection pool / timeout / retry tuning; serverless vs OLTP vs OLAP patterns |
 
 ## Diagnostic toolbox (scripts + router)
 
 Beyond the text skills, the kit ships **deterministic, read-only diagnostic
 scripts** that inspect a *local* DocumentDB container across both layers (MongoDB
 API + PostgreSQL engine), plus a **knowledge-base router** that maps a natural-
-language question to the exact script — no LLM at routing time. Full guide:
+language question to the exact target — no LLM at routing time. The router scores
+a question against **two spaces**: Route A `tools` (the scripts below) and Route B
+`skills` (the standalone skills above), and reports the best of each plus a
+`recommended` route. Full guide:
 [`DIAGNOSTICS.md`](DIAGNOSTICS.md); catalog: [`../README.md`](../README.md#the-tools-scripts).
 
 | Tool | Answers |
@@ -57,7 +60,7 @@ language question to the exact script — no LLM at routing time. Full guide:
 | [`db-config-advisor.sh`](../scripts/db-config-advisor.sh) | Working set vs cache, TOAST share, cache-hit ratios (evidence-based). |
 | [`perf-advisor.sh`](../scripts/perf-advisor.sh) | Overall health: collection-scan audit, query timing, PG I/O / locks / config. |
 | [`data-integrity-check.sh`](../scripts/data-integrity-check.sh) | Orphaned foreign keys + mixed-type fields (hard structural integrity). |
-| [`knowledge-base/`](../knowledge-base/README.md) | NL question → exact script (deterministic keyword scoring, zero deps). |
+| [`knowledge-base/`](../knowledge-base/README.md) | NL question → exact script (`--list`) **or** skill (`--skills`); deterministic keyword scoring, zero deps. |
 
 Companion to the toolbox: the `data-modeling` skill's
 [`model-large-field-split`](../skills/data-modeling/model-large-field-split.md)