Merge pull request #5 from vanterx/feat/perf-review-orchestrator-v4-tier1

feat(skills): add mssql-performance-review orchestrator (tier 1 — agentic core)

Author: vanterx

CLAUDE.md

@@ -4,7 +4,7 @@ A Claude Code skills library for SQL Server performance tuning — T-SQL static
 
 ## Purpose
 
-Provides fifteen slash-command skills that Claude uses when asked to review T-SQL source code, `.sqlplan` XML files, STATISTICS IO/TIME output, Profiler/XE trace data, deadlock graphs, index recommendations, wait statistics, Query Store data, procedure/trigger/function runtime stats collected from `sys.dm_exec_procedure_stats`, Always On AG health from `sys.dm_hadr_*` DMVs, Windows Server Failover Cluster log files, SQL Server ERRORLOG files, or SQL Server SPN and Kerberos delegation configuration. No application code — content is Markdown only.
+Provides sixteen slash-command skills — fifteen specialised review skills plus one agentic orchestrator (`mssql-performance-review`) that dispatches the right specialised skill(s) to mixed artifact inputs. Specialised skills cover T-SQL source code, `.sqlplan` XML files, STATISTICS IO/TIME output, Profiler/XE trace data, deadlock graphs, index recommendations, wait statistics, Query Store data, procedure/trigger/function runtime stats collected from `sys.dm_exec_procedure_stats`, Always On AG health from `sys.dm_hadr_*` DMVs, Windows Server Failover Cluster log files, SQL Server ERRORLOG files, and SQL Server SPN and Kerberos delegation configuration. No application code — content is Markdown only.
 
 ## Tech Stack
 
@@ -33,6 +33,7 @@ Provides fifteen slash-command skills that Claude uses when asked to review T-SQ
 | [skills/hadr-health-review/SKILL.md](skills/hadr-health-review/SKILL.md) | Always On AG health analysis: `hadr-health-review`. 22 checks (H1–H22) — replica connectivity, data loss risk, recovery time, throughput, and configuration |
 | [skills/errorlog-review/SKILL.md](skills/errorlog-review/SKILL.md) | SQL Server ERRORLOG analysis: `errorlog-review`. 28 checks (E1–E28) — AG failover events, lease expiry, memory pressure, I/O slow, corruption warnings, login failure bursts, startup/shutdown, and configuration signals |
 | [skills/spn-review/SKILL.md](skills/spn-review/SKILL.md) | SPN and Kerberos delegation analysis: `spn-review`. 30 checks (K1–K30) — MSSQLSvc SPN presence, service account binding, AG listener and alias, permissions, Kerberos delegation, AD account sensitivity |
+| [skills/mssql-performance-review/SKILL.md](skills/mssql-performance-review/SKILL.md) | Agentic offline orchestrator: `mssql-performance-review`. No checks of its own (dispatcher, like `sqlplan-batch`). Routes mixed artifacts to the 15 specialised skills, runs adversarial root-cause check, emits evidence chain + risk-rated fixes + rollback. |
 
 ### Human Reference (references/check-explanations.md — not loaded at runtime by default)
 
@@ -53,12 +54,13 @@ Provides fifteen slash-command skills that Claude uses when asked to review T-SQ
 | [skills/hadr-health-review/references/check-explanations.md](skills/hadr-health-review/references/check-explanations.md) | Plain-English explanation of all 22 H-checks with DMV examples, fix recipes, and Quick Reference table |
 | [skills/errorlog-review/references/check-explanations.md](skills/errorlog-review/references/check-explanations.md) | Plain-English explanation of all 28 E-checks with ERRORLOG examples, fix recipes, and Quick Reference table |
 | [skills/spn-review/references/check-explanations.md](skills/spn-review/references/check-explanations.md) | Plain-English explanation of all 30 K-checks with setspn/AD attribute examples, delegation model tables, and Quick Reference table |
+| [skills/mssql-performance-review/references/check-explanations.md](skills/mssql-performance-review/references/check-explanations.md) | Methodology reference for the orchestrator: dispatch heuristics, symptom-to-probe-sequence map, hypothesis classes, recommendation conflict catalogue, and rationale for the standard analysis order |
 
 ### Root Documentation
 
 | File | Purpose |
 |------|---------|
-| [README.md](README.md) | User-facing guide: triggers, input formats, output samples for all 15 skills |
+| [README.md](README.md) | User-facing guide: triggers, input formats, output samples for all 16 skills |
 | [PERFORMANCE_TUNING_GUIDE.md](PERFORMANCE_TUNING_GUIDE.md) | Decision guide: which skill to use for which scenario, symptom-based routing, artifact capture how-tos, 231-check ID reference |
 | [LLM_COST_ESTIMATION.md](LLM_COST_ESTIMATION.md) | Token and dollar cost breakdown per skill — worked examples, cost control strategies, prompt caching guide |
 | [.claude/docs/architectural_patterns.md](.claude/docs/architectural_patterns.md) | Cross-cutting conventions: check ID namespacing, input polymorphism, output format, companion pipeline, dollar-sign avoidance |
@@ -95,7 +97,7 @@ npx skills add vanterx/mssql-performance-skills -g       # global
 
 **Manual fallback:**
 ```bash
-cp -r skills/* ~/.claude/skills/          # global (all 15 skills)
+cp -r skills/* ~/.claude/skills/          # global (all 16 skills)
 cp -r skills/* .claude/skills/            # project-scoped
 ```
 
@@ -156,8 +158,9 @@ Never use `$0`, `$3`, `$15`, or `$[...]` inside SKILL.md files. The skill loader
 | `L` | `clusterlog-review` |
 | `E` | `errorlog-review` |
 | `K` | `spn-review` |
+| (none) | `mssql-performance-review` — dispatcher; delegates checks to other skills, like `sqlplan-batch` |
 
-New skills must choose an unused single uppercase letter.
+New skills must choose an unused single uppercase letter, or document why they are dispatcher-style (no prefix) like the orchestrator and `sqlplan-batch`.
 
 ### references/check-explanations.md is not loaded at runtime by default
 Only `SKILL.md` is loaded automatically by the Claude Code skill loader. The `references/check-explanations.md` file is human reference and on-demand context — Claude may load it when a user asks "explain check X" or for deeper fix-option detail. Do not put trigger conditions or thresholds there that Claude needs to act on without prompting.

LLM_COST_ESTIMATION.md

@@ -49,6 +49,7 @@ Claude Code's own instructions, tool definitions, CLAUDE.md, and conversation hi
 | `hadr-health-review` | ~2,900 |
 | `errorlog-review` | ~3,100 |
 | `spn-review` | ~3,800 |
+| `mssql-performance-review` | ~7,500 |
 
 ### Your input artifact
 

PERFORMANCE_TUNING_GUIDE.md

@@ -21,12 +21,32 @@ A decision guide for choosing the right skill — or combination of skills — f
 | [`procstats-review`](#procstats-review) | `/procstats-review` | Output from `sql/procstats/04_report_queries.sql` pasted from `collect.proc_stats` | Procedure/trigger/function runtime stats — 20 checks (R1–R20): top consumers, per-execution efficiency, N+1 patterns, parameter sniffing, trend analysis |
 | [`clusterlog-review`](#clusterlog-review) | `/clusterlog-review` | `CLUSTER.LOG` file or inline paste | WSFC cluster log analysis — 25 checks (L1–L25): lease timeouts, health check failures, quorum loss, node eviction, network partition, RHS crashes, AG resource transitions |
 | [`errorlog-review`](#errorlog-review) | `/errorlog-review` | SQL Server ERRORLOG file or inline paste | ERRORLOG operational analysis — 28 checks (E1–E28): AG failover events, lease expiry, memory pressure, I/O slow, corruption warnings, login failure bursts, startup/shutdown, and configuration signals |
+| [`hadr-health-review`](#hadr-health-review) | `/hadr-health-review` | `sys.dm_hadr_*` DMV output | Always On AG health analysis — 22 checks (H1–H22): replica connectivity, data loss risk, recovery time, throughput, and configuration |
 | [`spn-review`](#spn-review) | `/spn-review` | `setspn` output and/or `Get-ADUser`/`Get-ADComputer` AD attribute output | SPN and Kerberos delegation analysis — 30 checks (K1–K30): MSSQLSvc SPN presence, service account binding, AG listener and alias, permissions, Kerberos delegation, AD account sensitivity |
+| [`mssql-performance-review`](#mssql-performance-review) | `/mssql-performance-review` / `/sql-triage` | Mixed artifacts or a symptom description | Agentic offline orchestrator — routes mixed inputs to the right specialised skills, runs an adversarial root-cause check, emits a consolidated report with evidence chain, risk-rated fixes, and rollback. Dispatcher, no checks of its own. |
 
 ---
 
 ## Choose by Scenario
 
+### "I have a pile of mixed artifacts and don't know where to start"
+
+**Use: `/mssql-performance-review`**
+
+The orchestrator classifies every input (`.sqlplan`, `.sql`, stats output, wait stats, trace, Query Store, procstats, deadlock XML, ERRORLOG, CLUSTER.LOG, setspn output, hadr DMVs), forms 2-3 ranked hypotheses, dispatches the relevant specialised skills, runs an adversarial root-cause check, and emits one consolidated report. Strictly offline — never contacts SQL Server.
+
+```
+/mssql-performance-review ./incident-20260517/
+```
+
+Also accepts a symptom description ("CPU is high on prod since 09:00") and tells you which captures to run.
+
+```
+/sql-triage CPU pegged at 95% on PROD-SQL01 since 09:00, no recent deploy
+```
+
+---
+
 ### "I'm writing a new query or stored procedure"
 
 **Use: `/tsql-review`**

README.md

@@ -29,6 +29,7 @@ A collection of Claude Code skills covering the full SQL Server performance tuni
 | [hadr-health-review](#hadr-health-review) | Analyze Always On AG health from `sys.dm_hadr_*` DMVs — 22 checks (H1–H22): replica connectivity, data loss risk, recovery time, throughput, and configuration |
 | [errorlog-review](#errorlog-review) | Analyze SQL Server ERRORLOG for operational issues — 28 checks (E1–E28): AG failover events, lease expiry, memory pressure, I/O slow, corruption warnings, login failure bursts, startup/shutdown |
 | [spn-review](#spn-review) | Analyze SQL Server SPN configuration and Kerberos delegation settings — 30 checks (K1–K30): SPN presence, service account binding, AG listener and alias, permissions, delegation, AD account sensitivity |
+| [mssql-performance-review](#mssql-performance-review) | Agentic offline orchestrator — routes mixed artifacts (or a symptom description) to the right specialised skills, runs an adversarial root-cause check, and emits a single consolidated report with evidence chain, risk-rated fixes, and rollback. Use when you have several artifact types together or are not sure which skill to run. |
 
 ---
 
@@ -1195,6 +1196,53 @@ EXECUTE collect.usp_CollectProcStats;
 
 ---
 
+## mssql-performance-review
+
+Agentic offline orchestrator. Routes mixed SQL Server artifacts to the right specialised skills, runs an adversarial root-cause check, and emits a single consolidated report with explicit evidence chain, risk-rated fixes, and rollback steps for every recommendation.
+
+**Strictly offline.** The orchestrator never contacts a SQL Server. It only reads files you provide and emits scripts you run yourself. Air-gap compatible; no connection strings; no consent prompts.
+
+**Triggers:** `/mssql-performance-review`, `/mssql-perf-review`, `/mssql-full-review`, `/sql-triage`
+
+**Input:**
+
+- A directory containing mixed artifacts (`.sqlplan`, `.sql`, statistics output, wait stats, trace, Query Store, procstats, deadlock XML, ERRORLOG, CLUSTER.LOG, setspn output, hadr DMVs)
+- A list of file paths
+- Inline pasted content blocks with type hints
+- A natural-language symptom description ("CPU is high on prod since 09:00")
+
+**Usage:**
+
+```
+# Artifact-driven (you have files)
+/mssql-performance-review ./artifacts/
+
+# Symptom-driven (you have only a description)
+/sql-triage CPU pegged at 95% on PROD-SQL01 since 09:00 today
+```
+
+**What it does:**
+
+1. Classifies every input against the 15 specialised skills' input patterns.
+2. Generates 2-3 ranked hypotheses (parameter sniffing, missing index, server-wide I/O, AG failover, deadlock, etc.).
+3. Dispatches the specialised skills in the optimal order (cheap source/breadth first, then deep dive).
+4. Builds an evidence chain for every consolidated finding — each Critical finding cites at least 3 check IDs from 2+ skills, with source artifact, observed value, and threshold.
+5. Runs an **adversarial check** that deliberately tries to disprove the primary root cause — surfaces contradicting evidence rather than suppressing it.
+6. Produces ranked fix recommendations with action, effort, blocking window, risk class, side effects, exact rollback step, and post-deployment verification capture.
+7. Detects recommendation conflicts (e.g., one skill says add index X, another says X is unused).
+8. Tier 3 emits a capture bundle for missing artifacts — scripts you run yourself.
+
+**Sample output:** See [`example/mssql-performance-review/mixed-artifacts-analysis.md`](example/mssql-performance-review/mixed-artifacts-analysis.md) for an artifact-first walkthrough; [`example/mssql-performance-review/symptom-first-analysis.md`](example/mssql-performance-review/symptom-first-analysis.md) for the symptom-only triage flow.
+
+**When to use this vs the specialised skill directly:**
+
+- Use this when you have several artifact types or a symptom and are not sure which skill to run.
+- Use the specialised skill directly when you have one artifact and know which skill it needs (e.g., one `.sqlplan` → `/sqlplan-review`).
+
+The orchestrator does not duplicate the specialised skills — it composes them. The full methodology, hypothesis classes, conflict catalogue, and risk rubric are in [`skills/mssql-performance-review/references/`](skills/mssql-performance-review/references/).
+
+---
+
 ## Thresholds Quick Reference
 
 | Metric | Info | Warning | Critical |