Add sentry issue investigator agent and update related documentation

.claude/settings.json

@@ -8,7 +8,16 @@
       "Write(products/**/codebase/**)",
       "Write(personal/**)",
       "Write(agents/jira-to-pr/workspace/**)",
-      "mcp__*"
+      "mcp__atlassian",
+      "mcp__claude_ai_Atlassian_Rovo",
+      "mcp__claude_ai_Google_Calendar",
+      "mcp__claude_ai_Gmail",
+      "mcp__claude_ai_Google_Drive",
+      "mcp__claude_ai_BrightLocal_MCP",
+      "mcp__claude_ai_BrightLocal_Design_System",
+      "mcp__claude_ai_Firecrawl",
+      "mcp__claude_ai_Metabase",
+      "mcp__metabase"
     ],
     "deny": [
       "Write(shared/**)",

.gitignore

@@ -5,6 +5,7 @@ agents/*/personal/
 # In-flight work — local only
 products/*/working/
 products/*/codebase/
+.plans/
 
 # Environment files
 .env

CLAUDE.md

@@ -102,6 +102,47 @@ Triggers on any of:
 On match: read `agents/jira-to-pr/CLAUDE.md` and execute the full pipeline from Jira analysis
 through to PR creation.
 
+### sentry-issue-investigator (`agents/sentry-issue-investigator/`)
+
+Triggers on any of:
+- A Sentry issue short ID (e.g. `TOOLS-BACKEND-B77`) or a `sentry.bll-i.co.uk` URL
+- "investigate [Sentry ID]" / "why is [error] happening?"
+- "list sentry issues for the location module" / "for the API module"
+- "top / most frequent Sentry issues in Tools" / "ordered by occurrences"
+- "what's breaking in Tools right now?"
+- "find production logs for this error" / "trace this in elasticsearch"
+- "create a Jira ticket for this Sentry issue" / "propose a fix plan for it"
+- "what would we need to log to know?" / "propose logging changes"
+
+On match: read `agents/sentry-issue-investigator/CLAUDE.md`, then its
+`config/sentry.md` and `config/elasticsearch.md` before issuing any query — they
+carry verified filter syntax and documented dead ends. For ticket/plan/implement
+work also read `config/jira.md` and `config/ticket-templates.md`.
+
+Requires the `sentry-selfhosted`, `elasticsearch` and `atlassian` MCP servers,
+plus the BrightLocal VPN with Engineer permissions **at runtime** — without the
+VPN, queries return empty rather than erroring. Setup and troubleshooting:
+`agents/sentry-issue-investigator/config/mcp-setup.md`.
+
+A weekday-morning Mode A triage digest can run unattended via a systemd user
+timer (`config/scheduling.md`). It is **read-only by construction** — the
+scheduled run never files, resolves or snoozes anything, because the three
+confirmation gates need a human.
+
+Scope is Tools' **Location** and **API** modules. The agent investigates and
+plans; it never writes application code itself. It is **falsification-first**:
+every causal claim carries a verdict (`OBSERVED` / `CONFIRMED` / `REFUTED` /
+`UNTESTABLE`) backed by a query, negatives require passing controls, and when
+the logs cannot decide a claim it proposes the instrumentation that would —
+which takes precedence over a speculative fix. It can escalate through three
+**independently confirmed** gates — create a Jira ticket (`LM`, type
+`Internal Bug`), attach a fix plan as a ticket comment, then hand off to
+`jira-to-pr` for implementation and PR. Never chain those gates on one approval,
+and always dedupe against existing Jira tickets before creating one.
+
+Production DB inspection is opt-in (user exports `TOOLS_PROD_DB_DSN`) and goes
+exclusively through `scripts/db-select.py`, which is SELECT-only.
+
 ## Working with product codebases
 
 Each product in `products/` has a `codebase/` directory containing a symlink (or clone)