@sentry/junior-linear 0.29.0 → 0.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/junior-linear",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "private": false,
   "publishConfig": {
     "access": "public"

package/skills/linear/SKILL.md

@@ -31,39 +31,56 @@ Load references conditionally based on the request:
 - If the request refers to an existing Linear item indirectly, inspect the current thread context for the previously mentioned issue key or URL before asking the user to restate it.
 - Ask one concise follow-up only when a write is blocked after considering both explicit user input and any configured defaults, such as multiple plausible teams, no clear target issue, or no valid team for a new issue.
 
-2. Use the active Linear MCP tools:
+2. Discover and prepare MCP tools:
 
 - `loadSkill` returns `available_tools` for this skill, including the exact `tool_name` values and input schemas exposed in this turn.
 - Call those exact tool names directly. Use `searchTools` only if you need to rediscover or filter the active Linear tools later in the turn.
 - Prefer a short read/search step before mutating when you need to confirm the existing issue, team, project, or workflow state.
-- For create/update operations, classify the work as a `bug`, `feature`, or `task` and shape the title/body accordingly.
-- For issue creation, ground the ticket in the actual engineering problem:
-  - use a short descriptive title for bugs, short imperative title for tasks and features
-  - summarize the problem and impact; include expected outcome only when the thread states one
-  - mention who raised the issue when clear from the thread
-  - attach screenshots from the thread as image links when present
-  - preserve relevant URLs inline (Sentry, GitHub, docs, reproduction links) — do not dump a link list
-  - prefer flat bullet lists over headed sections for simple issues
-  - translate Slack-specific phrasing into product or engineering language
-  - remove channel names, slash commands, and session chatter unless the user explicitly wants them preserved
-- When setting optional fields, stay literal:
-  - use the team's actual workflow states instead of assuming generic names like `Todo` or `In Progress`
-  - use only Linear's standard priority levels: `low`, `medium`, `high`, `urgent`
-  - set project, labels, cycle, estimate, or assignee only when the user asked for them or the thread makes them clear
+
+3. Draft issue content (create or substantial rewrite):
+
+Classify the work as `bug`, `feature`, or `task`. Shape the title and body per [references/issue-writing.md](references/issue-writing.md); calibrate depth via [references/issue-examples.md](references/issue-examples.md).
+
+**Hard constraints — apply to every new issue:**
+
+- Title ≤ 60 characters. Descriptive for bugs, imperative for tasks/features.
+- Summary ≤ 3 sentences. Do not restate the title in the body.
+- Prefer flat bullet lists over headed sections for simple issues.
+- Generalize session framing — strip channel references, slash commands, Slack thread IDs, user @mentions, and transcript fragments; replace with the underlying engineering problem.
+- Compress source material. Research notes, hypotheses, or transcripts become a short summary + scoped bullets — never paste raw investigation into the body.
+- Do not add desired outcome, expected behavior, or acceptance criteria unless the thread explicitly requests them.
+- When the request originated from a Slack thread or any on-behalf-of context, append a final line `Action taken on behalf of <name>.` using the user's real name.
+
+Attribute the reporter by name when clear from the thread (e.g. "Raised by Alice during incident triage") — do not reference Slack channels, threads, or conversation metadata. Attach screenshots from the thread as image links when present. Preserve relevant URLs (Sentry, GitHub, docs, repro links) inline — do not dump a link list.
+
+4. Set optional Linear fields literally:
+
+- Use the team's actual workflow states instead of generic names like `Todo` or `In Progress`.
+- Use only Linear's standard priority levels: `low`, `medium`, `high`, `urgent`.
+- Set project, labels, cycle, estimate, or assignee only when the user asked for them or the thread makes them clear.
+
+5. Verify draft before mutating:
+
+- Title length ≤ 60 characters.
+- Delegated-action footer is the last line when applicable.
+- No session framing remains (channel refs, slash commands, @mentions, Slack thread IDs).
+- Body structure matches complexity — no empty sections, no restated title, no raw research dump.
+
+If any gate fails, revise and re-check before calling the MCP create/update tool.
+
+6. Execute:
+
 - For updates, prefer partial changes over full rewrites. Fetch current issue state first if the mutation could overwrite structured fields or duplicate an existing comment.
 - Check for duplicates silently before creating a new issue when the request appears related to existing work.
-- When the thread clearly indicates the work originated in Slack, mention that succinctly in the Linear ticket or comment if it improves provenance, but do not paste large thread transcripts.
 
-3. Report the result:
+7. Report the result:
 
-- Return the canonical Linear issue URL or key and summarize what changed.
+- Return the canonical Linear issue URL or key and what changed.
 - Report issue type when you created a new issue and it materially clarifies the outcome.
-- Keep routine tool chatter silent. Do not narrate each MCP search or mutation step.
 
 ## Guardrails
 
 - Reuse or update an existing Linear issue when it is clearly the same work instead of creating a duplicate.
-- Do not present guesses as facts. If the thread leaves an important detail uncertain, label it as an assumption in the Linear content.
+- Label uncertain details as assumptions in the Linear content when the thread leaves them unresolved.
 - Prefer concise, durable ticket text over verbatim Slack quotes or long transcript dumps.
 - Do not invent team-specific workflow names, labels, or estimate values without first confirming they exist.
-- If Linear authorization is required, let the MCP OAuth flow pause and resume the thread automatically instead of asking the user to handle credentials manually.

package/skills/linear/references/issue-writing.md

@@ -1,71 +1,35 @@
 # Issue Writing
 
-Use this reference when creating a new Linear issue or substantially improving an existing one.
+Load when creating a new Linear issue or substantially rewriting one. Cross-type rules (title length, delegated footer, generalization, compression) live in `SKILL.md` § Draft issue content — this file covers classification, title phrasing, and Linear-specific fields only.
 
 ## Classify the work item
 
-Infer the issue type before drafting:
-
 | Type      | Use when                                                                    |
 | --------- | --------------------------------------------------------------------------- |
 | `bug`     | Broken behavior, regressions, failures, incidents, or user-visible defects  |
 | `feature` | Net-new capability, product expansion, or workflow improvement              |
 | `task`    | Cleanup, instrumentation, docs, maintenance, follow-up, or operational work |
 
-Default to `task` when the request does not clearly describe a defect or a net-new capability. Structure should match complexity — simple issues need only a few bullets, complex bugs may warrant headed sections.
-
-## Title rules
-
-- Bug: short description of the broken behavior (e.g. "Webhook delivery drops events over 256KB")
-- Task: short imperative command (e.g. "Add rate-limit headers to ingest endpoint")
-- Feature: short imperative describing the capability (e.g. "Support SAML SSO for enterprise orgs")
+Default to `task` when the request does not clearly describe a defect or a net-new capability. Structure matches complexity — simple issues need a few bullets; complex bugs may warrant headed sections.
 
-## Drafting rules
+## Title phrasing
 
-- Use terse, specific language. No filler phrases, no restating the title in the body.
-- Specify who raised the issue when clear from the thread (e.g. "Reported by a customer in #support" or "Flagged by the oncall engineer").
-- Attach screenshots from the thread as image links when present.
-- Link relevant domain info (Sentry issues, GitHub PRs, docs pages, dashboards) inline where context helps — do not dump a link list.
-- Use bullet lists for multi-item details. Omit section headings when a flat list is sufficient.
-- Do not add a desired outcome or expected behavior section unless the thread explicitly states one.
-- Generalize Slack context: remove channel names, slash commands, and session chatter unless the user explicitly wants them preserved.
-- Include code snippets, stack traces, or exact commands only when they materially improve understanding.
+- Bug: short description of the broken behavior — e.g. "Webhook delivery drops events over 256KB"
+- Task: short imperative command — e.g. "Add rate-limit headers to ingest endpoint"
+- Feature: short imperative describing the capability — e.g. "Support SAML SSO for enterprise orgs"
 
 ## Linear-specific field guidance
 
 - Every new issue must belong to a single team. Resolve that before creating the issue.
-- If the request clearly maps to a known team template and the active MCP tools expose template-based creation, prefer the template so the team's default properties are applied consistently.
-- Set optional fields such as project, priority, labels, cycle, estimate, assignee, or status only when the user asked for them, the thread gives clear evidence, or the team's workflow makes the choice obvious.
-- Do not invent a custom status name. If you need a non-default status, read the team's actual workflow states first.
-- Priority should stay within Linear's standard levels: `low`, `medium`, `high`, `urgent`.
-- Estimates are team-configured. Only set one when the thread provides a clear value or the team context already makes the estimate scale unambiguous.
-- Labels may be workspace- or team-scoped. Reuse an existing matching label when possible instead of introducing near-duplicates.
-- If the tool exposes structured link attachments, attach the important URLs there and keep the prose body focused on interpretation rather than raw link dumping.
-
-## Delegated action footer
-
-When creating a new issue on behalf of a user, append a final line:
-
-`Action taken on behalf of <name>.`
-
-## Pre-creation checklist
-
-Before submitting, verify:
-
-- Title is type-appropriate (descriptive for bugs, imperative for tasks/features)
-- Body uses flat bullets where headings aren't needed
-- No desired outcome section unless the thread stated one
-- Reporter is mentioned when known
-- Screenshots and domain links are attached when present in thread
-- No session-specific noise (channel names, slash commands, conversational filler)
+- If the request maps to a known team template and the active MCP tools expose template-based creation, prefer the template so the team's default properties are applied consistently.
+- Do not invent a custom status name. Read the team's actual workflow states first when a non-default status is needed.
+- Priority stays within Linear's standard levels: `low`, `medium`, `high`, `urgent`.
+- Estimates are team-configured. Set one only when the thread provides a clear value or the team context makes the scale unambiguous.
+- Labels may be workspace- or team-scoped. Reuse an existing matching label instead of introducing near-duplicates.
+- If the tool exposes structured link attachments, attach important URLs there and keep the prose body focused on interpretation.
 
 ## Duplicate handling
 
 - Search silently before creating a new issue when the request appears related to existing work.
-- If a clear duplicate exists, prefer updating or commenting on the existing issue instead of creating a new one.
-- If the user explicitly wants a separate tracking issue anyway, state the relationship clearly in the new issue.
-
-## Result reporting
-
-- Report only the final, durable result: issue key, canonical URL, and what changed.
-- Keep routine drafting, search, and mutation steps silent unless they materially affect the outcome.
+- Prefer updating or commenting on a clear duplicate rather than creating a new issue.
+- If the user explicitly wants a separate tracking issue, state the relationship in the new issue.