@sentry/junior-github 0.20.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/junior-github",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "private": false,
   "publishConfig": {
     "access": "public"

package/skills/github/SKILL.md

@@ -73,7 +73,12 @@ Load the type-specific template and rules:
 
 Follow [references/research-rules.md](references/research-rules.md) for cross-type research standards.
 
-- Generalize conversation context: replace user names, slash-command invocations, channel references, and session-specific fragments with the underlying technical problem.
+- Use a short descriptive title for bugs, short imperative title for tasks and features.
+- Mention who raised the issue when clear from the thread.
+- Attach screenshots from the thread as image links when present.
+- Prefer flat bullet lists over headed sections for simple issues.
+- Do not add desired outcome or expected behavior unless the thread explicitly states one.
+- Generalize conversation context: replace channel references, slash-command invocations, and session-specific fragments with the underlying technical problem.
 - Use [references/issue-examples.md](references/issue-examples.md) to calibrate structure and depth.
 - Include code snippets, related issues, and related PRs only when they materially improve the issue.
 

package/skills/github/references/issue-examples.md

@@ -8,32 +8,42 @@ Bad title: "Error in auth"
 Good title: "OAuth token refresh fails during long-running operations"
 
 Bad summary:
+
 > Something is broken with auth tokens. Users are seeing errors.
 
 Good summary:
+
 > The SDK sets a dedup key before acquiring the per-thread lock. When the lock is contended, the message is permanently lost because the dedup slot is already consumed.
 
 Bad structure — generic catch-all:
+
 > ## Analysis
+>
 > - There's an auth error
 > - It happens sometimes
 > - We should fix it
 
 Good structure — problem-specific sections:
+
 > ## Root cause
-> The dedup key is set *before* the lock is attempted. When a second message arrives...
+>
+> The dedup key is set _before_ the lock is attempted. When a second message arrives...
 >
 > ## Reproduction
+>
 > 1. Two users @-mention the bot in the same thread while processing
 > 2. First message acquires the lock
 > 3. Second message sets its dedup key, fails lock acquisition
 >
 > ## Expected behavior
+>
 > Either:
+>
 > - **Option A**: Acquire lock before setting dedup key
 > - **Option B**: Clear dedup key on lock failure
 >
 > ## Workaround
+>
 > Retry wrapper that catches LockError and clears the dedup key (PR #32).
 >
 > Action taken on behalf of Jane Doe.
@@ -44,36 +54,43 @@ Bad title: "Clean up some code"
 Good title: "Remove 7 monkey-patches made unnecessary by SDK v2.1"
 
 Bad scope:
+
 > We have some patches we should clean up.
 
 Good scope — quantified and specific:
+
 > We maintain patches on **8 of 9 `process*` methods**. 7 exist solely to keep `waitUntil` offload behavior consistent while `processMessage` is customized for durable workflow routing. The 8th has two additional behavioral fixes.
 >
-> | Method | Patch reason |
-> |--------|-------------|
-> | `processReaction` | scheduling only |
-> | `processAction` | scheduling only |
-> | `processMessage` | scheduling + thread ID normalization + lock retry |
+> | Method            | Patch reason                                      |
+> | ----------------- | ------------------------------------------------- |
+> | `processReaction` | scheduling only                                   |
+> | `processAction`   | scheduling only                                   |
+> | `processMessage`  | scheduling + thread ID normalization + lock retry |
 >
 > Action taken on behalf of Jane Doe.
 
 ## Feature example
 
 Bad framing:
+
 > It would be nice to have better config reloading.
 
 Good framing — current state, gap, options:
+
 > ## Current behavior
+>
 > Workers read config at startup. Changes require a full restart.
 >
 > ## Gap
+>
 > Config changes during incidents require redeploying, adding 2-3 minutes to mitigation.
 >
 > ## Options
-> | Approach | Tradeoff |
-> |----------|----------|
-> | File watch + hot reload | Simple, but no atomicity guarantee |
-> | Config service with polling | Consistent, but adds a dependency |
+>
+> | Approach                    | Tradeoff                           |
+> | --------------------------- | ---------------------------------- |
+> | File watch + hot reload     | Simple, but no atomicity guarantee |
+> | Config service with polling | Consistent, but adds a dependency  |
 >
 > Action taken on behalf of Jane Doe.
 
@@ -88,8 +105,11 @@ Good framing — current state, gap, options:
 
 ## Anti-patterns
 
-- Overlong, sprawling body with no clear sections
+- Over-structured issues: using ## Summary, ## Impact, ## Root Cause headings for a 3-line bug
+- Adding "Expected behavior" or "Desired outcome" when the thread didn't state one
+- Restating the title as the first sentence of the body
 - Confident fix claims without root-cause evidence
 - Speculative detail mixed into verified facts
+- Dumping a list of URLs without inline context
 - Session-specific content (user names, slash commands, channel references)
 - Missing delegated attribution footer on user-requested issue creation

package/skills/github/references/issue-quality-checklist.md

@@ -4,12 +4,13 @@ Run this checklist before create/update mutation.
 
 ## External Quality Signals
 
-- Does the issue contain user names, slash commands, or channel references from the originating conversation? If so, generalize.
+- Does the issue contain slash commands, channel references, or user names that are not relevant to the issue itself? If so, generalize.
 - Is the issue concise and still actionable?
 - Are unknowns called out instead of guessed?
 - Are concerns included only when material?
 
 Useful external guidance:
+
 - GitHub docs, creating and structuring issues: https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/creating-an-issue
 - GitHub docs, issue templates: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates
 - Stack Overflow, minimal reproducible example standard: https://stackoverflow.com/help/minimal-reproducible-example
@@ -18,17 +19,22 @@ Useful external guidance:
 ## Internal Quality Bar
 
 - Issue type chosen and stated (`bug`, `feature`, or `task`).
-- Title is specific and <= 60 characters.
+- Title is specific and <= 60 characters. Descriptive for bugs, imperative for tasks/features.
 - Summary is short and clear.
 - Analysis depth matches the issue type.
 - Verified claims have sources.
 - Timeline statements use exact dates when known.
 - Confidence is explicit when certainty is low.
 - Concerns are included only when meaningful.
+- Reporter is mentioned when clear from the originating conversation.
+- Screenshots from the thread are attached as image links when present.
+- No headed sections that could be flat bullets instead.
+- No desired outcome or expected behavior section unless the thread explicitly stated one.
 
 ## Negative Calibration
 
 Avoid these anti-patterns:
+
 - Overlong, sprawling issue bodies with no clear sections
 - Confident solution claims that are weakly evidenced
 - Speculative detail mixed into verified sections

package/skills/github/references/issue-template-bug.md

@@ -1,29 +1,37 @@
 # Bug Issue Template
 
-Use as a starting structure. Adapt headings to fit the specific bug.
+Use as a starting structure. A few bullets often suffice — use headed sections only when complexity demands them.
 
 ## Summary
-Up to 3 sentences describing the failure and its impact.
 
-## Suggested sections (use what fits, rename freely)
+Up to 3 sentences describing the failure and its impact. Use a short descriptive title (e.g. "OAuth token refresh fails in long-running operations").
 
-- **Root cause** — technical explanation of why the bug occurs, with code snippets if relevant
+## Suggested sections (use only what fits)
+
+- **Root cause** — technical explanation with code snippets if relevant
 - **Reproduction** — numbered steps any developer can follow independently
-- **Expected behavior** — what should happen, with concrete options if multiple fixes exist
-- **Workaround** — current mitigation if one exists, with links to relevant PRs
-- **Versions affected** — specific versions or environments confirmed
+- **Expected behavior** — include only when the thread explicitly states what should happen
+- **Workaround** — current mitigation if one exists
+
+For simple bugs, skip sections entirely and use flat bullet lists.
+
+## Attribution
 
-Remove sections that don't apply. Add sections the problem needs.
+- Mention who reported the issue when clear from the originating conversation.
+- Attach screenshots from the thread as image links when present.
 
 ## Delegated action footer
+
 When creating a new issue on behalf of a user, append a final line:
 
 `Action taken on behalf of <name>.`
 
 ## Constraints
+
 - Title hard max: 60 characters (target 40-60).
 - Summary max 3 sentences.
-- Remove empty sections.
-- Adapt section headings to fit the issue, not the reverse.
+- Remove empty sections. Prefer flat bullets over headed sections for simple bugs.
+- Do not add expected behavior or desired outcome unless the thread explicitly states one.
 - Do not include acceptance criteria unless explicitly requested.
-- Keep the delegated action footer as the last line in the body when applicable to newly created issues.
+- Use terse, specific language — no filler, no restating the title in the body.
+- Keep the delegated action footer as the last line in the body when applicable.

package/skills/github/references/issue-template-feature.md

@@ -1,28 +1,36 @@
 # Feature Issue Template
 
-Use as a starting structure. Adapt headings to fit the specific feature.
+Use as a starting structure. A flat bullet list is fine for simple features — use headed sections only when tradeoffs need detailed framing.
 
 ## Summary
-Up to 3 sentences describing the desired improvement and user outcome.
 
-## Suggested sections (use what fits, rename freely)
+Up to 3 sentences describing the improvement. Use a short imperative title (e.g. "Support SAML SSO for enterprise orgs").
 
-- **Current behavior** — how the system works today, with code snippets if relevant
+## Suggested sections (use only what fits)
+
+- **Current behavior** — how the system works today
 - **Gap** — why current behavior is insufficient, with concrete impact
-- **Options** — viable approaches with tradeoffs
-- **Recommendation** — preferred direction with rationale
+- **Options** — viable approaches with tradeoffs (include only when the thread discusses alternatives)
+
+For simple features, skip sections and use flat bullets describing the gap and desired capability.
+
+## Attribution
 
-Remove sections that don't apply. Add sections the feature needs.
+- Mention who raised the request when clear from the originating conversation.
+- Attach screenshots from the thread as image links when present.
 
 ## Delegated action footer
+
 When creating a new issue on behalf of a user, append a final line:
 
 `Action taken on behalf of <name>.`
 
 ## Constraints
+
 - Title hard max: 60 characters (target 40-60).
 - Summary max 3 sentences.
-- Remove empty sections.
-- Adapt section headings to fit the issue, not the reverse.
+- Remove empty sections. Prefer flat bullets for simple features.
+- Do not add desired outcome unless the thread explicitly states one.
 - Do not include acceptance criteria unless explicitly requested.
-- Keep the delegated action footer as the last line in the body when applicable to newly created issues.
+- Use terse, specific language — no filler, no restating the title in the body.
+- Keep the delegated action footer as the last line in the body when applicable.

package/skills/github/references/issue-template-task.md

@@ -1,28 +1,35 @@
 # Task Issue Template
 
-Use as a starting structure. Adapt headings to fit the specific task.
+A task can be just a title + 2-3 bullets. Use headed sections only when scope is complex.
 
 ## Summary
-Up to 3 sentences describing the task and intended result.
 
-## Suggested sections (use what fits, rename freely)
+Up to 3 sentences describing the task. Use a short imperative title (e.g. "Remove deprecated legacyAuth middleware").
 
-- **Background** — why this task exists, with code snippets showing current state
+## Suggested sections (use only when complexity warrants)
+
+- **Background** — why this task exists, with code snippets if relevant
 - **Scope** — what's included and excluded, quantify when possible
-- **Implementation** — concrete steps or approach
-- **Dependencies** — related issues, PRs, or external blockers
 
-Remove sections that don't apply. Add sections the task needs.
+For simple tasks, skip sections and use flat bullets for scope and next step.
+
+## Attribution
+
+- Mention who raised the task when clear from the originating conversation.
+- Attach screenshots from the thread as image links when present.
 
 ## Delegated action footer
+
 When creating a new issue on behalf of a user, append a final line:
 
 `Action taken on behalf of <name>.`
 
 ## Constraints
+
 - Title hard max: 60 characters (target 40-60).
 - Summary max 3 sentences.
-- Remove empty sections.
-- Adapt section headings to fit the issue, not the reverse.
+- Remove empty sections. Prefer flat bullets for simple tasks.
+- Do not add desired outcome unless the thread explicitly states one.
 - Do not include acceptance criteria unless explicitly requested.
-- Keep the delegated action footer as the last line in the body when applicable to newly created issues.
+- Use terse, specific language — no filler, no restating the title in the body.
+- Keep the delegated action footer as the last line in the body when applicable.

package/skills/github/references/issue-type-bug.md

@@ -6,46 +6,25 @@ Use this file only when issue type is `bug`.
 
 Produce a high-signal bug issue that drives root-cause discovery, not premature solutioning.
 
-## Required Research Shape
+## Research Guidance
 
-1. Capture concrete evidence:
-- reproducible steps or explicit non-repro statement
-- exact error or symptom
-- impacted surface and scope
+Use these steps to investigate — they inform what goes into the issue, but do not dictate issue structure. The issue should be terse; research justifies what's included.
 
-2. Build a timeline with exact dates when known:
-- first observed
-- known regressions or relevant deploy/release windows
+1. Capture concrete evidence: reproducible steps or explicit non-repro statement, exact error or symptom, impacted surface and scope.
+2. Build a timeline with exact dates when known.
+3. Separate verified facts from unknowns — label each explicitly.
+4. Form root-cause hypotheses linked to evidence, with confidence (`high`, `medium`, `low`).
 
-3. Separate known from unknown:
-- verified facts contain only directly supported claims
-- unknown details stay explicit
-
-4. Form root-cause hypotheses:
-- each hypothesis must link back to evidence
-- include confidence (`high`, `medium`, `low`)
-
-## Fix Guidance
-
-- You may include tentative fix options.
-- Label options as tentative unless root cause is directly evidenced.
-- If root cause is not verified, include next RCA steps before or alongside fix options.
-- Do not present one fix as certain without explicit evidence.
+Include fix suggestions only when the thread discusses fixes. Do not present a fix as certain without explicit evidence.
 
 ## Context Generalization
 
 When deriving bug content from conversation, generalize to the technical problem.
 
 Before (session-specific):
+
 > @alice ran `/github create` in #ops-alerts and saw "token refresh failed" when the OAuth token expired mid-thread
 
 After (generalized):
-> OAuth token refresh fails during long-running operations, producing "token refresh failed" errors
-
-## Completion Bar
 
-A `bug` issue is ready when it has:
-- clear symptom and scope
-- evidence-backed facts
-- explicit unknowns
-- root-cause hypotheses with confidence
+> OAuth token refresh fails during long-running operations, producing "token refresh failed" errors

package/skills/github/references/issue-type-feature.md

@@ -6,36 +6,22 @@ Use this file only when issue type is `feature`.
 
 Propose an intentional improvement with clear current-state analysis and practical options.
 
-## Required Research Shape
+## Research Guidance
 
-1. Analyze how the system works today:
-- current behavior
-- known constraints
-- why current behavior is insufficient
+Use these steps to investigate — they inform what goes into the issue, but do not dictate issue structure.
 
-2. Gather prior art:
-- target a couple relevant examples when available
-- include links and what each example proves
-- if none found, explicitly say no strong prior art was found
-
-3. Frame options:
-- at least one viable path, preferably multiple when tradeoffs are meaningful
-- include implementation and operational tradeoffs
+1. Analyze current behavior and why it's insufficient.
+2. Gather prior art when available — include links and what each proves. If none found, omit rather than stating "none found."
+3. Frame options with tradeoffs when the thread discusses alternatives.
 
 ## Context Generalization
 
 When deriving feature content from conversation, generalize to the capability gap.
 
 Before (session-specific):
+
 > @carol mentioned in the standup thread that she has to manually restart the worker every time the config changes
 
 After (generalized):
-> Workers do not pick up config changes without a restart, requiring manual intervention
 
-## Completion Bar
-
-A `feature` issue is ready when it has:
-- clear problem framing and objective
-- current-state analysis
-- prior-art section (or explicit none found)
-- concise option tradeoffs
+> Workers do not pick up config changes without a restart, requiring manual intervention

package/skills/github/references/issue-type-task.md

@@ -6,29 +6,20 @@ Use this file only when issue type is `task`.
 
 Create a concise execution ticket for maintenance, cleanup, docs, refactors, or operational chores.
 
-## Research Standard
+## Research Guidance
 
-- Minimal research by default.
-- Prefer first-party repository context when available.
-- No required external prior-art scan unless user asks for it.
-
-## Required Content
-
-- explicit goal
-- scope boundaries
-- concrete implementation steps
-- dependencies or risks only when material
+- Minimal research by default. Prefer first-party repository context when available.
+- Include implementation steps only when the thread discusses approach. Otherwise, state the goal and scope.
+- Include dependencies or risks only when material.
 
 ## Context Generalization
 
 When deriving task content from conversation, generalize to the goal and scope.
 
 Before (session-specific):
+
 > @bob asked in #eng-chat to clean up the unused `legacyAuth` middleware that he noticed while reviewing PR #312
 
 After (generalized):
-> Remove unused `legacyAuth` middleware to reduce maintenance surface
-
-## Completion Bar
 
-A `task` issue is ready when it is short, actionable, and testable without extra discovery.
+> Remove unused `legacyAuth` middleware to reduce maintenance surface

package/skills/github/references/research-rules.md

@@ -1,6 +1,7 @@
 # Research and Verification Rules
 
 Use this file for cross-type rules. Then apply the matching type-specific file:
+
 - `bug`: [issue-type-bug.md](issue-type-bug.md)
 - `feature`: [issue-type-feature.md](issue-type-feature.md)
 - `task`: [issue-type-task.md](issue-type-task.md)
@@ -8,6 +9,7 @@ Use this file for cross-type rules. Then apply the matching type-specific file:
 ## Source Priority
 
 1. First-party repository evidence:
+
 - Source code and tests
 - Existing issues and PRs
 - Release notes/changelog
@@ -26,8 +28,9 @@ Use this file for cross-type rules. Then apply the matching type-specific file:
 
 ## Output Expectations
 
-- Clearly distinguish verified facts from unknowns. Weave evidence naturally into the issue structure rather than forcing separate sections.
-- Include source links/paths for each verified fact.
+- Research depth should not translate into verbose issue output. The issue should be terse; research justifies what goes in, not how much.
+- Clearly distinguish verified facts from unknowns. Weave evidence naturally into the issue rather than forcing separate sections.
+- Include source links/paths inline for verified facts.
 - Use exact dates for timeline claims.
 - Avoid absolute language when confidence is low.
-- For `feature` issues, target a couple prior-art examples when available; if not found, explicitly say none were found.
+- For `feature` issues, include prior-art examples when found and relevant; omit the section entirely if none exist.