Add sentry issue investigator agent and update related documentation - #6
Open
bsuchecki wants to merge 9 commits into
Open
Add sentry issue investigator agent and update related documentation#6bsuchecki wants to merge 9 commits into
bsuchecki wants to merge 9 commits into
Conversation
…ntation based on how DA, Locafy and Neustar were introduced
…ntation based on how DA, Locafy and Neustar were introduced
…it, dashboard, plan-only) Add a failed-submissions admin dashboard phase; split frontend from backend into separate tickets and surface the aggregator in the LM edit-page Aggregators section (not Connections); require each ticket to carry a description + acceptance criteria + dependency ordering; add a Phase 1 endpoint-to-role mapping step (ask when the API doc is ambiguous); and reframe the skill as plan-and-tickets only (never implements or asks to start implementation). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…tecture, tech stack, and key integrations
There was a problem hiding this comment.
Pull request overview
This PR primarily adds a new sentry-issue-investigator agent (plus supporting configs/scripts) for triaging Tools Sentry issues with evidence from Elasticsearch and optional read-only DB inspection, and wires the agent trigger into the workspace CLAUDE.md. It also includes additional, seemingly unrelated scope: a new Connected Locations “new aggregator integration planner” Skill and expanded product context docs for Tools and ListingSyncer.
Changes:
- Add
agents/sentry-issue-investigator/(orchestrator, Sentry/Elasticsearch/Jira cookbooks, ticket templates, and a guarded read-only DB query helper script). - Update workspace routing (
CLAUDE.md) and permissions (.claude/settings.json) for agent usage. - Add a new product skill for planning end-to-end aggregator integrations, plus its reference map; expand Tools/ListingSyncer product context docs.
Reviewed changes
Copilot reviewed 14 out of 15 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
CLAUDE.md |
Adds trigger routing and scope notes for the new sentry-issue-investigator agent. |
.claude/settings.json |
Replaces wildcard MCP allowance with an explicit allowlist. |
.gitignore |
Ignores .plans/. |
agents/sentry-issue-investigator/CLAUDE.md |
Agent orchestrator: modes A–G, gating rules, evidence discipline, and operational guardrails. |
agents/sentry-issue-investigator/README.md |
End-user documentation for capabilities, setup, limits, and escalation path. |
agents/sentry-issue-investigator/config/sentry.md |
Verified Sentry project/org scoping and query cookbook. |
agents/sentry-issue-investigator/config/elasticsearch.md |
Verified ES index/field map, log sources, and safe query recipes. |
agents/sentry-issue-investigator/config/jira.md |
Jira project/type conventions, dedup workflow, and formatting verification guidance. |
agents/sentry-issue-investigator/config/ticket-templates.md |
Templates for Jira ticket descriptions and fix-plan comments (wiki markup). |
agents/sentry-issue-investigator/config/db.env.example |
DSN template + rationale for requiring a SELECT-only DB grant. |
agents/sentry-issue-investigator/scripts/db-select.py |
Guarded SQL runner enforcing read-only usage (single statement, allowlist/blocklist, read-only transaction, rollback). |
products/Tools/CONTEXT.md |
Expands Tools product/tech context and build/test commands. |
products/ListingSyncer/CONTEXT.md |
Expands ListingSyncer product/tech context and build/test commands. |
skills/product/cl-new-aggregator-integration-planner/SKILL.md |
New planning skill describing an 8-phase, multi-repo aggregator integration plan and Jira ticketing workflow. |
skills/product/cl-new-aggregator-integration-planner/references/reference-map.md |
Reference file map (paths/branches) to model new integrations on existing ones. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+11
to
+20
| "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" |
| ## Repository | ||
|
|
||
| `/home/lenovo/brightLocal/ListingSyncer` (or `github.com/BrightLocal/ListingSyncer`) | ||
| `/home/bartek/IdeaProjects/ListingSyncer` (or `github.com/BrightLocal/ListingSyncer`). |
| > campaigns, and monitor local search rankings. | ||
| ## Repository | ||
|
|
||
| `/home/bartek/IdeaProjects/Tools` (`github.com/BrightLocal/Tools`). |
| - **Project** — default **`LM`** (Connected Locations); ask if different. | ||
| - **Parent** — create a parent **Task/Story** "Integrate <X> aggregator" summarizing the effort (paste the | ||
| plan / attach `plan.md`), or link under an existing epic if the user names one. | ||
| w- **Issue type & labels** — child tickets as `Task` (or sub-tasks of the parent if the project uses them); |
Comment on lines
+1
to
+5
| --- | ||
| name: cl-new-aggregator-integration-planner | ||
| description: >- | ||
| Plans the FULL end-to-end integration of a NEW listing aggregator / directory syncer across | ||
| BrightLocal Tools + ListingSyncer — the same scope we followed for DataAxle, Locafy and Neustar. |
Khutorny
approved these changes
Aug 25, 2026
dubenyuk
approved these changes
Aug 27, 2026
…instrumentation proposal guidelines
…ns and structured logging details
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request introduces a new agent,
sentry-issue-investigator, designed to investigate and triage Sentry issues in the Tools codebase, with supporting documentation and configuration. The agent integrates with Sentry, Elasticsearch, and Jira, and follows a strict, gated escalation path for error investigation, ticket creation, and implementation handoff. It also adds detailed configuration and guardrails for production database and log access, ensuring safety and transparency.The most important changes are:
New Agent: Sentry Issue Investigator
sentry-issue-investigatoragent, which investigates Sentry issues in the Tools Location and API modules, corroborates with production logs and optionally database data, and can escalate findings through Jira ticket creation and implementation handoff, each requiring explicit user confirmation. The agent never writes application code itself. (agents/sentry-issue-investigator/README.md,CLAUDE.md) [1] [2]Documentation and Usage
agents/sentry-issue-investigator/README.md)CLAUDE.mdwith trigger phrases and operational scope for the new agent. (CLAUDE.md)Production Database Access Guardrails
db.env.exampleas a template for safe, read-only database access, with strong warnings and instructions to ensure only SELECT queries are possible, and explaining the rationale and limits of the SQL guard layers. (agents/sentry-issue-investigator/config/db.env.example)Elasticsearch Configuration and Safety
elasticsearch.mddetailing production log index patterns, field mapping, query recipes, correlation strategies, and strict read-only usage discipline for the agent. (agents/sentry-issue-investigator/config/elasticsearch.md)Access Control Updates
.claude/settings.jsonto enumerate specific allowed MCP servers for the agent, replacing the previous wildcard. (.claude/settings.json)