@sentry/junior-github 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,11 @@
+# @sentry/junior-github
+
+`@sentry/junior-github` adds GitHub issue workflows to Junior using a GitHub App.
+
+Install it alongside `@sentry/junior`:
+
+```bash
+pnpm add @sentry/junior @sentry/junior-github
+```
+
+For full setup, configuration, and verification steps, see [skills/github/README.md](skills/github/README.md).

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@sentry/junior-github",
+  "version": "0.1.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "files": [
+    "plugin.yaml",
+    "skills"
+  ]
+}

package/plugin.yaml

@@ -0,0 +1,29 @@
+name: github
+description: GitHub issue management via GitHub App
+
+capabilities:
+  - issues.read
+  - issues.write
+  - issues.comment
+  - labels.write
+
+config-keys:
+  - repo
+
+credentials:
+  type: github-app
+  api-domains:
+    - api.github.com
+  auth-token-env: GITHUB_TOKEN
+  auth-token-placeholder: ghp_host_managed_credential
+  app-id-env: GITHUB_APP_ID
+  private-key-env: GITHUB_APP_PRIVATE_KEY
+  installation-id-env: GITHUB_INSTALLATION_ID
+
+target:
+  type: repo
+  config-key: repo
+
+runtime-dependencies:
+  - type: system
+    package: gh

package/skills/github/README.md

@@ -0,0 +1,101 @@
+# github setup
+
+This skill uses host-issued GitHub App installation tokens.
+
+## 1) Create/install GitHub App
+
+In GitHub:
+1. Go to `Settings -> Developer settings -> GitHub Apps -> New GitHub App`.
+2. Set app name and callback URL (any valid HTTPS URL is fine if you do not use web flow).
+3. Under repository permissions, grant:
+- Issues: Read and write
+- Metadata: Read
+4. Create the app and generate a private key.
+5. Install the app on the target org/repo(s).
+
+Install the app on target repos/orgs and collect:
+- `GITHUB_APP_ID`
+- `GITHUB_APP_PRIVATE_KEY` (PEM)
+
+## 2) Configure host runtime
+
+Set on the harness host (never in skill files):
+- `GITHUB_APP_ID`
+- `GITHUB_APP_PRIVATE_KEY`
+- `GITHUB_INSTALLATION_ID`
+
+### Vercel env setup (multiline-safe)
+
+`GITHUB_APP_PRIVATE_KEY` is accepted as:
+- Raw PEM (multiline)
+- Escaped-newline PEM (single-line with `\n`)
+- Base64-encoded PEM
+
+For Vercel, prefer CLI file input so newlines are preserved exactly:
+
+```bash
+vercel env add GITHUB_APP_ID production
+vercel env add GITHUB_INSTALLATION_ID production
+vercel env add GITHUB_APP_PRIVATE_KEY production --sensitive < ./github-app-private-key.pem
+```
+
+If variables already exist, use `vercel env update` instead of `vercel env add`:
+
+```bash
+vercel env update GITHUB_APP_PRIVATE_KEY production --sensitive < ./github-app-private-key.pem
+```
+
+Repeat for `preview` and `development` as needed. After env changes, redeploy so the new deployment picks up updated values.
+
+## 3) Runtime behavior
+
+- Credentials are issued lazily when `jr-rpc issue-credential <capability>` is run.
+- Issued credentials are reused for the rest of the current turn.
+- Sandbox does not receive raw tokens via env; host applies scoped Authorization header transforms for GitHub API calls.
+
+## 4) CLI usage
+
+Run as a regular sandbox `bash` command while this skill is active:
+
+```bash
+jr-rpc issue-credential github.issues.write
+gh issue create --repo owner/repo --title "Example issue" --body-file /vercel/sandbox/tmp/issue.md
+```
+
+`gh` supports either direct `GITHUB_TOKEN` (for local debugging) or sandbox-level header injection.
+Use `github.issues.read` for read-only commands (`view`, comment reads via `gh api`), `github.issues.comment` for comments, and `github.labels.write` for label updates.
+
+Optional: set a default repository once per channel/thread context so `--repo` is not needed each turn:
+
+```bash
+jr-rpc config set github.repo getsentry/junior
+```
+
+## 5) Quick verification
+
+- `pnpm skills:check`
+- Create issue in a test repo.
+- Update/comment/label the same issue.
+- Use read-only commands (`gh issue view`, `gh api .../comments`) for issue inspection.
+
+## 6) Production verification (step-by-step)
+
+1. Confirm host env vars are present in prod:
+   - `GITHUB_APP_ID`
+   - `GITHUB_APP_PRIVATE_KEY`
+   - `GITHUB_INSTALLATION_ID`
+2. Confirm the GitHub App is installed on your test repo with the permissions above.
+3. Deploy `main` to prod.
+4. Run `/github` to create an issue in a safe test repo.
+5. Verify the issue is authored by the GitHub App identity.
+6. Run `/github` to update title/body, add/remove labels, and add a comment.
+7. Verify all mutations succeed and are attributed to the app.
+8. Verify GitHub API calls succeed while this skill is active without writing tokens into sandbox env/files.
+9. Verify raw token values are never printed in output or logs.
+10. Check logs for:
+   - `credential_issue_request`
+   - `credential_issue_success`
+   - `credential_inject_start`
+   - `credential_inject_cleanup`
+11. Verify logs contain no token/private-key values.
+12. Negative test: target a repo without app installation and confirm explicit failure.

package/skills/github/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: github
+description: Manage GitHub issue workflows via GitHub App identity with concise, evidence-backed content. Use when users ask to open, edit, label, comment on, close/reopen, or inspect GitHub issues via /github, especially when command-level CLI guidance is needed.
+requires-capabilities: github.issues.read github.issues.write github.issues.comment github.labels.write
+uses-config: github.repo
+allowed-tools: bash
+---
+
+# GitHub Operations
+
+Use this skill for `/github` workflows in the harness. Issues are the primary supported surface today.
+
+## Workflow
+
+1. Confirm operation and target:
+- Determine `create`, `update`, `comment`, `labels`, `state`, or read-only inspection.
+- Resolve repository (`owner/repo`) and issue number for non-create operations.
+- If repository is not explicit in args, query channel config:
+  - `jr-rpc config get github.repo`
+- If config exists and is valid `owner/repo`, use it as default.
+- If repository is still missing, ask the user for `owner/repo`.
+
+2. Classify issue type before drafting:
+- Use explicit user type when provided (`bug`, `feature`, `task`).
+- Otherwise infer from intent:
+  - `bug`: broken behavior, regression, error, failure.
+  - `feature`: net-new capability or behavioral expansion.
+  - `task`: maintenance, cleanup, docs, refactor, operational chore.
+- Default to `task` when uncertain.
+
+3. Draft issue content:
+- Load the type-specific template:
+  - `bug`: [references/issue-template-bug.md](references/issue-template-bug.md)
+  - `feature`: [references/issue-template-feature.md](references/issue-template-feature.md)
+  - `task`: [references/issue-template-task.md](references/issue-template-task.md)
+- Follow [references/research-rules.md](references/research-rules.md) and the type-specific research rules:
+  - `bug`: [references/issue-type-bug.md](references/issue-type-bug.md)
+  - `feature`: [references/issue-type-feature.md](references/issue-type-feature.md)
+  - `task`: [references/issue-type-task.md](references/issue-type-task.md)
+- Generalize conversation context: replace user names, slash-command invocations, channel references, and session-specific fragments with the underlying technical problem.
+- Include code snippets when they clarify the problem pattern or proposed change.
+- Cross-reference related issues and PRs when they provide context.
+- For quality gates, use [references/issue-quality-checklist.md](references/issue-quality-checklist.md).
+- For structure examples, use [references/issue-examples.md](references/issue-examples.md).
+
+4. Execute operation:
+- Issue credential for the required capability before API calls:
+  - Read-only (`gh issue view`, comment reads via `gh api`): `jr-rpc issue-credential github.issues.read`
+  - Create/update/state changes: `jr-rpc issue-credential github.issues.write`
+  - Comments: `jr-rpc issue-credential github.issues.comment`
+  - Labels: `jr-rpc issue-credential github.labels.write`
+- Resolve command and flags from [references/api-surface.md](references/api-surface.md).
+- Execute using `gh` CLI directly. Use [references/github-issue-api.md](references/github-issue-api.md) for exact command shapes.
+- Use [references/common-use-cases.md](references/common-use-cases.md) for ready-to-run operation patterns.
+- If an operation fails, follow [references/troubleshooting-workarounds.md](references/troubleshooting-workarounds.md) before retrying.
+- Read [references/sandbox-runtime.md](references/sandbox-runtime.md) for credential delivery details.
+
+5. Report result:
+- Return canonical issue URL, issue number, issue type, applied changes, and confidence.
+- Include references used for verified claims.
+
+## Guardrails
+
+- Execute operations as soon as required fields are available. Do not pause for confirmation unless the user explicitly asks for preview/dry-run.
+- Require explicit confirmation only for close/reopen or destructive broad rewrites.
+- Never claim verification without citing sources.
+- For `bug` issues, do not present a fix as definitive unless root-cause evidence is explicit.
+- Do not overwrite issue fields unless explicitly requested. Prefer partial updates over full body replacement.
+- If repository or installation access is missing, stop and return a concrete remediation message.
+- Scope is issue workflows only. Do not execute pull-request or repository admin mutations in this skill.

package/skills/github/references/api-surface.md

@@ -0,0 +1,51 @@
+# GitHub Issue CLI API Surface
+
+This skill supports issue workflows only.
+
+All operations use `gh` CLI.
+
+## Capability to command mapping
+
+| Capability | Commands |
+| --- | --- |
+| `github.issues.read` | `gh issue view`, `gh api /repos/.../comments` |
+| `github.issues.write` | `gh issue create`, `gh issue edit`, `gh issue close`, `gh issue reopen` |
+| `github.issues.comment` | `gh issue comment` |
+| `github.labels.write` | `gh issue edit --add-label/--remove-label` |
+
+## Command matrix
+
+| Operation | Command |
+| --- | --- |
+| Create issue | `gh issue create --repo owner/repo --title "..." [--body-file PATH]` |
+| Update issue fields | `gh issue edit NUMBER --repo owner/repo [--title "..."] [--body-file PATH]` |
+| Close issue | `gh issue close NUMBER --repo owner/repo [--comment "..."]` |
+| Reopen issue | `gh issue reopen NUMBER --repo owner/repo` |
+| Add labels | `gh issue edit NUMBER --repo owner/repo --add-label LABEL [--add-label LABEL2]` |
+| Remove labels | `gh issue edit NUMBER --repo owner/repo --remove-label LABEL [--remove-label LABEL2]` |
+| Add comment | `gh issue comment NUMBER --repo owner/repo --body-file PATH` |
+| Read issue | `gh issue view NUMBER --repo owner/repo --json number,title,state,labels,assignees,author,url,body` |
+| Read comments | `gh api /repos/owner/repo/issues/NUMBER/comments --method GET --header "Accept: application/vnd.github+json"` |
+
+## Credential + config helper commands
+
+Resolve repo default:
+
+```bash
+jr-rpc config get github.repo
+```
+
+Set repo default:
+
+```bash
+jr-rpc config set github.repo owner/repo
+```
+
+Issue scoped credentials:
+
+```bash
+jr-rpc issue-credential github.issues.read
+jr-rpc issue-credential github.issues.write
+jr-rpc issue-credential github.issues.comment
+jr-rpc issue-credential github.labels.write
+```

package/skills/github/references/common-use-cases.md

@@ -0,0 +1,64 @@
+# Common GitHub Issue CLI Use Cases
+
+Use these patterns as direct execution playbooks.
+
+## 1) Create a bug issue
+
+```bash
+jr-rpc issue-credential github.issues.write
+gh issue create --repo owner/repo --title "OAuth token refresh fails in long-running thread" --body-file /vercel/sandbox/tmp/issue.md
+```
+
+## 2) Patch issue title/body
+
+```bash
+jr-rpc issue-credential github.issues.write
+gh issue edit 123 --repo owner/repo --title "Clarify retry semantics for lock contention" --body-file /vercel/sandbox/tmp/revised-issue.md
+```
+
+## 3) Close or reopen issue
+
+```bash
+jr-rpc issue-credential github.issues.write
+gh issue close 123 --repo owner/repo --comment "Fixed in #456"
+```
+
+Reopen:
+
+```bash
+gh issue reopen 123 --repo owner/repo
+```
+
+## 4) Add implementation comment
+
+```bash
+jr-rpc issue-credential github.issues.comment
+gh issue comment 123 --repo owner/repo --body-file /vercel/sandbox/tmp/comment.md
+```
+
+## 5) Apply triage labels
+
+```bash
+jr-rpc issue-credential github.labels.write
+gh issue edit 123 --repo owner/repo --add-label bug --add-label needs-triage
+```
+
+Remove labels:
+
+```bash
+gh issue edit 123 --repo owner/repo --remove-label needs-triage
+```
+
+## 6) Read issue details before mutation
+
+```bash
+jr-rpc issue-credential github.issues.read
+gh issue view 123 --repo owner/repo --json number,title,state,labels,assignees,author,url,body
+```
+
+## 7) Read comment history in JSON
+
+```bash
+jr-rpc issue-credential github.issues.read
+gh api /repos/owner/repo/issues/123/comments --method GET --header "Accept: application/vnd.github+json"
+```

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

@@ -0,0 +1,54 @@
+# GitHub CLI Command Reference
+
+All issue operations should go through `gh` CLI commands.
+
+## Authentication
+
+- Preferred: sandbox network policy injects Authorization headers for `api.github.com`.
+- Optional local fallback: `GITHUB_TOKEN` (short-lived GitHub App installation token).
+- If `GITHUB_TOKEN` is a host placeholder value, rely on header transforms and do not override it.
+
+## Command shapes
+
+### Create issue
+
+`gh issue create --repo owner/repo --title "..." [--body-file /tmp/issue.md]`
+
+### Update title/body
+
+`gh issue edit 123 --repo owner/repo [--title "..."] [--body-file /tmp/issue.md]`
+
+### Close issue
+
+`gh issue close 123 --repo owner/repo [--comment "..."]`
+
+### Reopen issue
+
+`gh issue reopen 123 --repo owner/repo`
+
+### Add labels
+
+`gh issue edit 123 --repo owner/repo --add-label bug --add-label regression`
+
+### Remove labels
+
+`gh issue edit 123 --repo owner/repo --remove-label triage`
+
+### Add comment
+
+`gh issue comment 123 --repo owner/repo --body-file /tmp/comment.md`
+
+### Get issue JSON
+
+`gh issue view 123 --repo owner/repo --json number,title,state,labels,assignees,author,url,body`
+
+### List comments JSON (read-only)
+
+`gh api /repos/owner/repo/issues/123/comments --method GET --header "Accept: application/vnd.github+json"`
+
+## Behavior notes
+
+- Prefer `--json` output for machine-readable parsing where available.
+- Use `gh api` for endpoints not fully covered by `gh issue` subcommands.
+- Commands should be deterministic and non-interactive in harness usage.
+- Return actionable errors for auth, permission, not-found, and validation failures.

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

@@ -0,0 +1,88 @@
+# Issue Examples
+
+Calibrate structure and depth by comparing good and bad patterns.
+
+## Bug example
+
+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...
+>
+> ## 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).
+
+## Task example
+
+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 |
+
+## 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 |
+
+## Principles
+
+- Use problem-specific headings, not generic labels
+- Include code snippets when they clarify the pattern
+- Quantify scope precisely ("8 of 9", not "many")
+- Cross-reference related issues and PRs
+- Show concrete options with tradeoffs, not vague "should be fixed"
+- Use tables for structured comparisons
+
+## Anti-patterns
+
+- Overlong, sprawling body with no clear sections
+- Confident fix claims without root-cause evidence
+- Speculative detail mixed into verified facts
+- Session-specific content (user names, slash commands, channel references)

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

@@ -0,0 +1,34 @@
+# Issue Quality Checklist
+
+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.
+- 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
+- Mozilla Bugzilla, bug writing guidance: https://bugzilla.mozilla.org/page.cgi?id=bug-writing.html
+
+## Internal Quality Bar
+
+- Issue type chosen and stated (`bug`, `feature`, or `task`).
+- Title is specific and <= 60 characters.
+- 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.
+
+## 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

@@ -0,0 +1,23 @@
+# Bug Issue Template
+
+Use as a starting structure. Adapt headings to fit the specific bug.
+
+## Summary
+Up to 3 sentences describing the failure and its impact.
+
+## Suggested sections (use what fits, rename freely)
+
+- **Root cause** — technical explanation of why the bug occurs, 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
+
+Remove sections that don't apply. Add sections the problem needs.
+
+## 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.
+- Do not include acceptance criteria unless explicitly requested.

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

@@ -0,0 +1,22 @@
+# Feature Issue Template
+
+Use as a starting structure. Adapt headings to fit the specific feature.
+
+## Summary
+Up to 3 sentences describing the desired improvement and user outcome.
+
+## Suggested sections (use what fits, rename freely)
+
+- **Current behavior** — how the system works today, with code snippets if relevant
+- **Gap** — why current behavior is insufficient, with concrete impact
+- **Options** — viable approaches with tradeoffs
+- **Recommendation** — preferred direction with rationale
+
+Remove sections that don't apply. Add sections the feature needs.
+
+## 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.
+- Do not include acceptance criteria unless explicitly requested.

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

@@ -0,0 +1,22 @@
+# Task Issue Template
+
+Use as a starting structure. Adapt headings to fit the specific task.
+
+## Summary
+Up to 3 sentences describing the task and intended result.
+
+## Suggested sections (use what fits, rename freely)
+
+- **Background** — why this task exists, with code snippets showing current state
+- **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.
+
+## 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.
+- Do not include acceptance criteria unless explicitly requested.

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

@@ -0,0 +1,51 @@
+# Bug Issue Rules
+
+Use this file only when issue type is `bug`.
+
+## Primary Goal
+
+Produce a high-signal bug issue that drives root-cause discovery, not premature solutioning.
+
+## Required Research Shape
+
+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:
+- first observed
+- known regressions or relevant deploy/release windows
+
+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.
+
+## 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

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

@@ -0,0 +1,41 @@
+# Feature Issue Rules
+
+Use this file only when issue type is `feature`.
+
+## Primary Goal
+
+Propose an intentional improvement with clear current-state analysis and practical options.
+
+## Required Research Shape
+
+1. Analyze how the system works today:
+- current behavior
+- known constraints
+- why current behavior is insufficient
+
+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
+
+## 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

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

@@ -0,0 +1,34 @@
+# Task Issue Rules
+
+Use this file only when issue type is `task`.
+
+## Primary Goal
+
+Create a concise execution ticket for maintenance, cleanup, docs, refactors, or operational chores.
+
+## Research Standard
+
+- 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
+
+## 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.

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

@@ -0,0 +1,33 @@
+# 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)
+
+## Source Priority
+
+1. First-party repository evidence:
+- Source code and tests
+- Existing issues and PRs
+- Release notes/changelog
+- Project docs
+
+2. First-party vendor docs for dependencies/services.
+
+3. Reputable external sources only when needed.
+
+## Verification Standard
+
+- Treat statements as `verified` only when backed by direct evidence.
+- Prefer at least two independent supporting signals for high-impact claims.
+- If signals conflict, state the conflict and lower confidence.
+- If evidence is missing, mark as `unknown`.
+
+## 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.
+- 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.

package/skills/github/references/sandbox-runtime.md

@@ -0,0 +1,38 @@
+# Sandbox Runtime Guidance
+
+This skill runs in the harness sandbox (`node22`) and commands execute via the `bash` tool.
+
+## Runtime environment
+
+- Sandbox OS is Amazon Linux 2023.
+- System packages are installed with `dnf`.
+- Any package install command must run with root privileges (`sudo: true` in sandbox command execution).
+
+## What is currently available
+
+- Node runtime in sandbox (`node22` image).
+- Writable workspace under `/vercel/sandbox`.
+- Outbound network access (default allow-all unless harness sets a network policy).
+- Skill files are synchronized into `/vercel/sandbox/skills/<skill-name>`.
+
+## Important constraint
+
+Credentials should only be injected per command execution scope. Do not rely on global/session-wide environment for privileged tokens.
+
+## Credential strategy
+
+1. Enable credentials with the narrowest capability needed:
+   - `github.issues.read` for `view` and comment reads
+   - `github.issues.write` for create/update/close/reopen
+   - `github.issues.comment` for comments
+   - `github.labels.write` for label mutations
+2. Runtime injects `Authorization` header transforms for `api.github.com`.
+3. Execute `gh` CLI commands directly.
+4. Do not persist tokens in files.
+
+## Operational checks
+
+- Verify CLI availability:
+  - `gh --version`
+- Use non-interactive command flags in automation contexts.
+- If 401/403 appears after credential issuance, reissue once, then stop with remediation guidance if still failing.

package/skills/github/references/troubleshooting-workarounds.md

@@ -0,0 +1,21 @@
+# GitHub Issue CLI Troubleshooting
+
+Use this table to recover quickly while keeping operations deterministic.
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| `unknown command "issue"` from `gh` | CLI version too old or wrong binary. | Verify `gh --version`; ensure GitHub CLI from `gh-cli` repo is installed. |
+| `Missing required option --repo` | Repo not passed and no default was resolved. | Resolve with `jr-rpc config get github.repo`; pass `--repo owner/repo` explicitly when missing. |
+| `GraphQL: Could not resolve to a Repository` | Repo slug is wrong or inaccessible. | Validate `owner/repo` and confirm app installation on target repository. |
+| 401 Unauthorized | Credential not issued for current command scope. | Run `jr-rpc issue-credential <capability>` for the exact command and retry once. |
+| 403 Forbidden | App lacks required permission on repo. | Confirm GitHub App permissions and installation scope. |
+| 404 Not Found | Issue number or repo is wrong. | Validate repo + issue ID with `gh issue view NUMBER --repo owner/repo`. |
+| `sandbox setup failed (dnf install gh failed ...)` | `gh` package not available in default repos. | Configure/install from GitHub RPM repo (`gh-cli`) in sandbox dependency bootstrap, then retry. |
+| `gh issue edit` does not change labels | Wrong flag usage or missing label capability context. | Use repeated `--add-label/--remove-label` flags and issue `github.labels.write` credential first. |
+| Comment command fails with empty body | Body file missing/empty. | Ensure comment file exists and has content before `gh issue comment`. |
+
+## Retry guidance
+
+- Retry once for transient auth/transport failures after reissuing credentials.
+- Do not loop retries on repeated 401/403/404 validation errors.
+- For persistent permission problems, return explicit remediation and stop.