docs: add /sentry-get-started design brainstorm

[evanpurkhiser]

A working design doc for /sentry-get-started and the Sentry skill architecture behind it — the proposed single entrypoint that walks a user into whatever they actually need from Sentry through an agent, without burning their token budget guessing.

The directory holds three docs. use-cases.md is the user-story catalog (what people ask Sentry to do agentically). index.md captures the design principles (orient cheaply then let the user drive; close the loop by confirming events landed via MCP; aspire to do everything but be honest about current coverage), the cheap orientation probe, and the conditional capability menu. proposed-skills.md is where the skill design lives.

The notable shift in this version: the skill architecture moves from four layered skills (WHY/DO/HOW/USE — sentry-concepts/sentry-setup/sentry-sdk/sentry-workflow) to task-shaped skills plus a shared references/ library. The insight is that discovery (what the agent triggers on) wants to be task-shaped, while content factoring (not duplicating per-signal strategy across 19 platforms) wants to be layered — and we get both by making skills the tasks a user names (sentry-instrument, sentry-debug-issue, …) and demoting concepts and per-SDK code to reference documents. Each built skill is made self-contained by a build-time step: a per-skill references.yml declares which shared references to copy in, and a Python hydrate script copies them with a link-validator backstop, so source stays DRY while every shipped skill is complete.

proposed-skills.md defines the reference-library tree, the per-skill structure and manifest, and the full ~14-skill task set split into a first focus (/sentry-get-started, sentry-instrument, sentry-debug-issue) and a later focus, with an auditable use-case-to-skill coverage map. index.md is annotated where the older four-skill flows are pending a pass to the new shape.

This is a design artifact intended to inform the actual skill/command work, not a final spec. Decisions made and still-open questions are tracked at the bottom of index.md.

[cursor]

MCP path skips orientation probe

Medium Severity

Step 0 requires re-running the full orientation probe after MCP connect/auth, but the master flowchart sends the post-connect path straight to ROUTE instead of back through PROBE. That omits the repo grep and find_projects signals needed for the new-vs-existing branch.

Additional Locations (1)

• GETTING-STARTED-DESIGN/index.md#L119-L120

 

^{Reviewed by Cursor Bugbot for commit c0fc04f. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 3 total unresolved issues (including 2 from previous reviews).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit d545326. Configure here.}

[evanpurkhiser]

We'll tighten this up, it should react the concept for a instrumentation type when it's doing that instrumentation

[sentry]

Bug: The build script only warns about missing reference files instead of failing the build, leading to skills being shipped with broken documentation links.
_{Severity: HIGH}

Suggested Fix

Implement the "backstop" validation described in the design document (proposed-skills.md:155-157) to scan for broken relative links in hydrated skills and fail the build if any are found. Additionally, create the missing search-query-language.md file or remove references to it.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: GETTING-STARTED-DESIGN/proposed-skills.md#L139-L143

Potential issue: The build script `hydrate-references.py` only issues a warning when a
referenced file is missing, instead of failing the build as intended by the design.
Specifically, the `sentry-debug-issue` skill references `search-query-language.md`,
which does not exist. The design also proposed a "backstop" validation to scan for
broken links and fail the build, but this was not implemented. As a result, the skill
will be shipped with broken documentation links, preventing the agent from accessing
required materials and breaking the documented procedure.

Also affects:

• skills-next/skills/sentry-debug-issue/references.yml:2
• skills-next/skills/sentry-debug-issue/SKILL.md
• scripts/hydrate-references.py