npm - @sentry/junior-github - Versions diffs - 0.29.0 → 0.31.0 - Mend

@sentry/junior-github 0.29.0 → 0.31.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (25) hide show

package/{skills/github/README.md → SETUP.md} RENAMED Viewed

@@ -1,6 +1,6 @@
-# github setup
+# GitHub plugin setup
-This skill uses host-issued GitHub App installation tokens.
+This plugin exposes two skills — `github-code` (clone, source-code investigation, pull requests) and `github-issues` (issue workflows) — both authenticated via host-issued GitHub App installation tokens.
 ## 1) Create/install GitHub App
@@ -61,13 +61,13 @@ Repeat for `preview` and `development` as needed. After env changes, redeploy so
 ## 3) Runtime behavior
-- When the GitHub skill is active, authenticated `gh` and `git` commands cause the runtime to inject GitHub credentials automatically for the current turn.
+- When either GitHub skill is active, authenticated `gh` and `git` commands cause the runtime to inject GitHub credentials automatically for the current turn.
 - Issued credentials are reused only within the current turn.
 - Sandbox does not receive raw tokens via env; host applies Authorization header transforms for GitHub API calls.
 ## 4) CLI usage
-Run as a regular sandbox `bash` command while this skill is active:
+Run as a regular sandbox `bash` command while the relevant skill is active:
 Clone a repository with a shallow checkout by default:
@@ -82,8 +82,7 @@ git -C repo fetch --depth=50 origin
 git -C repo fetch --unshallow
 ```
-GitHub operations still require the GitHub skill, but the runtime injects
-credentials automatically when the skill is active:
+GitHub operations still require a GitHub skill to be active; the runtime injects credentials automatically when one is loaded:
 ```bash
 gh issue create --repo owner/repo --title "Example issue" --body-file /vercel/sandbox/tmp/issue.md
@@ -92,7 +91,7 @@ gh issue create --repo owner/repo --title "Example issue" --body-file /vercel/sa
 `gh` supports either direct `GITHUB_TOKEN` (for local debugging) or sandbox-level header injection.
 The runtime uses `github.issues.read` for read-only issue commands, `github.issues.write` for issue edits, comments, and labels, `github.contents.write` for pushes and merge operations, and `github.pull-requests.write` for PR mutations after the branch is already on the remote.
-GitHub capability scoping is a safety rail, not a hard sandbox boundary. It helps prevent accidental write scope and wrong-repo mutations, and the host runtime still decides when to mint credentials. Credential injection is skill-scoped: load the active GitHub skill first, keep repo context explicit, and let the runtime choose the required capability for the command.
+GitHub capability scoping is a safety rail, not a hard sandbox boundary. It helps prevent accidental write scope and wrong-repo mutations, and the host runtime still decides when to mint credentials. Credential injection is skill-scoped: load the relevant GitHub skill first, keep repo context explicit, and let the runtime choose the required capability for the command.
 Be careful with mixed-surface PR commands:
@@ -131,10 +130,10 @@ jr-rpc config set github.repo getsentry/junior
    - `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.
+4. Exercise `github-issues` 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. Push a test branch and run `/github` to create a draft PR using explicit repo targeting and `--head`.
+6. Exercise `github-issues` to update title/body, add/remove labels, and add a comment.
+7. Push a test branch and exercise `github-code` to create a draft PR using explicit repo targeting and `--head`.
 8. Verify all mutations succeed and are attributed to the app.
 9. Verify GitHub API calls succeed while this skill is active without writing tokens into sandbox env/files.
 10. Verify raw token values are never printed in output or logs.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/junior-github",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -8,6 +8,7 @@
   "type": "module",
   "files": [
     "plugin.yaml",
-    "skills"
+    "skills",
+    "SETUP.md"
   ]
 }

package/skills/github-code/SKILL.md ADDED Viewed

@@ -0,0 +1,88 @@
+---
+name: github-code
+description: Clone GitHub repositories, investigate source code, and manage pull requests via GitHub CLI. Use when users ask to inspect implementation details in a repository, clone code, edit files, answer source-code questions from repo evidence, or open/edit/view/merge pull requests. Prefer this skill for repository and code tasks even when the repo concerns Sentry products.
+allowed-tools: bash
+---
+# GitHub Code Operations
+Repository checkout, source-code investigation, and pull request operations via `gh` CLI.
+## Reference loading
+| Operation     | Load                                                                                   |
+| ------------- | -------------------------------------------------------------------------------------- |
+| Any operation | [references/api-surface.md](references/api-surface.md)                                 |
+| On failure    | [references/troubleshooting-workarounds.md](references/troubleshooting-workarounds.md) |
+## Workflow
+### 1. Resolve operation and target
+- Determine whether the task is `clone`, `source-code investigation`, a pull request inspection (`view`, `list`, `diff`, `checks`), or a pull request mutation (`create`, `update`, `close`, `merge`).
+- Resolve repository (`owner/repo`). If not explicit, query channel config with `jr-rpc config get github.repo` before running any `gh` or `git` command. If still missing, ask the user.
+- Resolve the pull request number for operations targeting an existing PR.
+- Keep `--repo owner/repo` explicit on `gh` commands so the command itself targets the intended repository, not a stale default.
+### 2. Execute by operation type
+**Clone** → shallow clone path below.
+**Source-code investigation** → source-code path below.
+**Pull request inspection** → inspection path below.
+**Pull request mutation** → mutation path below.
+---
+### Clone path
+- Default to a shallow clone; deepen incrementally only when the task needs history.
+- Use exact command forms from [references/api-surface.md](references/api-surface.md).
+- After cloning, check for `AGENTS.md` in the repo root (and `.github/AGENTS.md`) before making edits. Treat discovered instructions as hard constraints.
+- Report the local directory and whether the clone is shallow or full.
+---
+### Source-code investigation path
+- Use for questions like "where is this implemented?", "how does this workflow work in code?", "is there already logic for X?", or "verify this from the repo."
+- If the current workspace already contains the target repository, inspect local files directly before cloning.
+- Prefer the narrowest deterministic evidence: local file search, exact file reads, targeted clone inspection, existing issues/PRs, tests.
+- Cite repository evidence in the reply: file paths, symbols, issue/PR numbers, or commit references when known.
+- If evidence is incomplete, say what is unknown instead of guessing.
+---
+### Pull request inspection path
+- Use read-only `gh pr` commands from [references/api-surface.md](references/api-surface.md); skip branch resolution and push logic.
+- Return canonical PR URL, PR number when available, target repository, and the fields the user asked to inspect.
+- If the PR cannot be resolved, report the exact not-found or auth failure and stop.
+---
+### Pull request mutation path
+#### 3. Resolve mutation inputs
+- For PR creation, resolve the base branch (explicit user request wins; otherwise repository default).
+- Resolve the head branch from the current checkout or user request.
+- If the head branch may not exist on the remote yet, push it explicitly before PR creation.
+#### 4. Execute
+- Run `git push` first so `gh pr create` does not trigger hidden push/fork behavior; then `gh pr create --repo owner/repo --head BRANCH ...`.
+- If `git push` returns 401/403 or another auth/permission error, verify the command is targeting the right repository and retry once. If it still clearly indicates bad or revoked credentials, rerun the real GitHub command and let the runtime trigger a reconnect flow.
+- Treat `gh pr merge` as a contents mutation and keep repository context explicit.
+#### 5. Report result
+- Return canonical PR URL, PR number when available, target repository, and applied changes.
+- If PR creation fails after explicit push + explicit repo scoping, report the exact auth or validation failure and stop.
+## Guardrails
+- Require explicit confirmation only for destructive merges or force operations.
+- Answer source-code questions from repository evidence, not product framing or generic memory.
+- Default to shallow clones; do not use a full clone unless the task requires repository history or the user asks for it.
+- If repository or installation access is missing, stop and return a concrete remediation message.
+- Do not execute repository admin mutations.

package/skills/github-code/references/api-surface.md ADDED Viewed

@@ -0,0 +1,51 @@
+# GitHub CLI API Surface — code & pull requests
+All operations use `gh` CLI. Commands must be deterministic and non-interactive.
+## Repo scoping
+When the user omits `owner/repo`, resolve `github.repo` first with `jr-rpc config get github.repo`, then pass the resolved repo explicitly on the actual `gh` or `git` command.
+Treat explicit repo flags as command-targeting safety rails, not as a credential-scoping mechanism.
+## Capability to command mapping
+| Capability                   | Commands                                                                        |
+| ---------------------------- | ------------------------------------------------------------------------------- |
+| `github.contents.read`       | `gh repo clone`, `git fetch`                                                    |
+| `github.contents.write`      | `git push`, `gh api` (create/update file contents), `gh pr merge`               |
+| `github.pull-requests.read`  | `gh pr view`, `gh pr list`, `gh pr diff`, `gh pr checks`                        |
+| `github.pull-requests.write` | `gh pr create --head <branch>` after explicit push, `gh pr edit`, `gh pr close` |
+## Command matrix
+| Operation                          | Command                                                                                   |
+| ---------------------------------- | ----------------------------------------------------------------------------------------- | -------- | ---------- |
+| Clone repository (default shallow) | `gh repo clone owner/repo [DIRECTORY] -- --depth=1`                                       |
+| Deepen shallow clone               | `git -C DIRECTORY fetch --depth=N origin`                                                 |
+| Convert shallow clone to full      | `git -C DIRECTORY fetch --unshallow`                                                      |
+| Push branch before PR creation     | `git -C DIRECTORY push -u origin BRANCH`                                                  |
+| Create pull request                | `gh pr create --repo owner/repo --head BRANCH --base BASE --title "..." --body-file PATH` |
+| Update pull request                | `gh pr edit NUMBER --repo owner/repo [--title "..."] [--body-file PATH]`                  |
+| Close pull request                 | `gh pr close NUMBER --repo owner/repo`                                                    |
+| Merge pull request                 | `gh pr merge NUMBER --repo owner/repo [--merge                                            | --squash | --rebase]` |
+| View pull request                  | `gh pr view NUMBER --repo owner/repo [--json ...]`                                        |
+| List pull requests                 | `gh pr list --repo owner/repo [--state open                                               | closed   | merged]`   |
+| Diff pull request                  | `gh pr diff NUMBER --repo owner/repo`                                                     |
+| Check pull request status          | `gh pr checks NUMBER --repo owner/repo`                                                   |
+## Config helpers
+```bash
+jr-rpc config get github.repo
+jr-rpc config set github.repo owner/repo
+```
+## Behavior notes
+- Prefer `--json` output for machine-readable parsing where available.
+- Pass extra `git clone` flags after `--` (e.g. `gh repo clone owner/repo -- --depth=1`).
+- Before `gh pr create`, push the head branch explicitly, then use `--head` so `gh` does not trigger hidden push/fork behavior. That push requires GitHub write access to the remote.
+- If the explicit `git push` fails with 401/403 or another auth/permission error, verify the repo context and retry once. If the error still clearly indicates bad credentials, rerun the real GitHub command and let the runtime trigger a reconnect flow.
+- `gh pr edit` is not a single-permission command: title/body/base/reviewer changes fit `github.pull-requests.write`; label, assignee, milestone changes fit `github.issues.write` (use the `github-issues` skill); project flags are outside the current GitHub App capability model.
+- `gh pr close --comment` may need `github.issues.write` (use `github-issues`); `gh pr close --delete-branch` needs `github.contents.write`.
+- Return actionable errors for auth, permission, not-found, and validation failures.

package/skills/{github → github-code}/references/troubleshooting-workarounds.md RENAMED Viewed

@@ -1,23 +1,20 @@
-# GitHub CLI Troubleshooting
+# GitHub CLI Troubleshooting — code & pull requests
 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.                                                                       |
-| `unknown flag: --depth` from `gh repo clone`                                    | `git clone` flags were passed before `--`.                                  | Pass clone flags after `--`, for example `gh repo clone owner/repo -- --depth=1`.                                                               |
-| `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.                                                 |
-| GitHub command affects or authenticates against the wrong repo                  | Stale `github.repo` default or authenticated command missing explicit repo. | Pass `--repo owner/repo` to the `gh` command for the target repository, or update `github.repo` before retrying.                                |
-| `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                                                                | Repo context is missing, stale, or the stored GitHub auth needs reconnect.  | Verify `--repo owner/repo` or `github.repo`, then retry the real command once so the runtime can reconnect automatically when needed.           |
-| `git push` fails with 401/403 or auth/permission output                         | Write auth was stale or the command is targeting the wrong repo.            | Verify the remote and repo context, retry the same push once, then confirm app permissions and installation scope if the retry still fails.     |
-| 403 Forbidden                                                                   | App lacks required permission on repo or install scope is too narrow.       | Verify the repo context, then 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`.                                                                         |
-| `gh pr create` fails with auth/permission errors or tries to push interactively | The branch was not pushed first, or repo context is wrong.                  | Push the branch explicitly first, then rerun `gh pr create --repo owner/repo --head BRANCH ...`.                                                |
-| `git blame`, long log history, or old commits are missing after clone           | Repo was cloned shallow by design.                                          | Deepen incrementally with `git -C DIRECTORY fetch --depth=N origin`, or use `git -C DIRECTORY fetch --unshallow` when full history is required. |
-| `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 wrong repo context.                                     | Use repeated `--add-label/--remove-label` flags and keep `--repo owner/repo` explicit.                                                          |
-| Comment command fails with empty body                                           | Body file missing/empty.                                                    | Ensure comment file exists and has content before `gh issue comment`.                                                                           |
+| Symptom                                                                         | Likely cause                                                                | Fix                                                                                                                                         |
+| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `unknown command "..."` from `gh`                                               | CLI version too old or wrong binary in the plugin runtime.                  | Verify `gh --version`; if it is unavailable or too old, report that the GitHub plugin runtime dependency is not available.                  |
+| `unknown flag: --depth` from `gh repo clone`                                    | `git clone` flags were passed before `--`.                                  | Pass clone flags after `--`, for example `gh repo clone owner/repo -- --depth=1`.                                                           |
+| `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.                                             |
+| Command affects or authenticates against the wrong repo                         | Stale `github.repo` default or authenticated command missing explicit repo. | Pass `--repo owner/repo` for the target repository, or update `github.repo` before retrying.                                                |
+| `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                                                                | Repo context is missing, stale, or the stored GitHub auth needs reconnect.  | Verify `--repo owner/repo` or `github.repo`, then retry the real command once so the runtime can reconnect automatically when needed.       |
+| `git push` fails with 401/403 or auth/permission output                         | Write auth was stale or the command is targeting the wrong repo.            | Verify the remote and repo context, retry the same push once, then confirm app permissions and installation scope if the retry still fails. |
+| 403 Forbidden                                                                   | App lacks required permission on repo or install scope is too narrow.       | Verify the repo context, then confirm GitHub App permissions and installation scope.                                                        |
+| `gh pr create` fails with auth/permission errors or tries to push interactively | The branch was not pushed first, or repo context is wrong.                  | Push the branch explicitly first, then rerun `gh pr create --repo owner/repo --head BRANCH ...`.                                            |
+| `git blame`, long log history, or old commits are missing after clone           | Repo was cloned shallow by design.                                          | Deepen incrementally with `git -C DIRECTORY fetch --depth=N origin`, or `git -C DIRECTORY fetch --unshallow` when full history is required. |
+| `sandbox setup failed (dnf install gh failed ...)`                              | `gh` package not available from the plugin runtime dependency bootstrap.    | Report the plugin runtime bootstrap failure; do not try to repair package installation from the skill workflow.                             |
 ## Retry guidance

package/skills/github-issues/SKILL.md ADDED Viewed

@@ -0,0 +1,90 @@
+---
+name: github-issues
+description: Create, update, comment on, label, and inspect GitHub issues via GitHub CLI with concise, evidence-backed content. Use when users ask to open, edit, view, close, reopen, or triage GitHub issues — including tracking bugs, features, or tasks. Prefer this skill over generic repository tools for any issue operation.
+allowed-tools: bash
+---
+# GitHub Issue Operations
+Issue create, update, comment, label, state, and inspection via `gh` CLI.
+## Reference loading
+| Operation                            | Load                                                                                                                                                                                                                                                                                                   |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Any operation                        | [references/api-surface.md](references/api-surface.md)                                                                                                                                                                                                                                                 |
+| `issue create`, `issue body rewrite` | [references/issue-examples.md](references/issue-examples.md), the matching type-specific guide ([issue-bug.md](references/issue-bug.md), [issue-feature.md](references/issue-feature.md), [issue-task.md](references/issue-task.md)), and [references/research-rules.md](references/research-rules.md) |
+| On failure                           | [references/troubleshooting-workarounds.md](references/troubleshooting-workarounds.md)                                                                                                                                                                                                                 |
+## Workflow
+### 1. Resolve operation and target
+- Determine whether the task is `create`, `update`, `comment`, `labels`, `state`, or read-only inspection.
+- Resolve repository (`owner/repo`). If not explicit, query channel config with `jr-rpc config get github.repo` before running any `gh` command. If still missing, ask the user.
+- Resolve the issue number for non-create operations.
+- Keep `--repo owner/repo` explicit on `gh` commands so the command itself targets the intended repository, not a stale default.
+### 2. Classify issue type
+- 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 guide:
+| Type      | Guide                                                      |
+| --------- | ---------------------------------------------------------- |
+| `bug`     | [references/issue-bug.md](references/issue-bug.md)         |
+| `feature` | [references/issue-feature.md](references/issue-feature.md) |
+| `task`    | [references/issue-task.md](references/issue-task.md)       |
+Follow [references/research-rules.md](references/research-rules.md) for cross-type research standards. Use [references/issue-examples.md](references/issue-examples.md) to calibrate structure and depth.
+**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. Remove empty sections.
+- Generalize session framing — strip channel references, slash commands, Slack thread IDs, user @mentions, and transcript fragments; replace with the underlying technical 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 action requester's real name. The action requester is the current `<requester>` or the person who explicitly asked you to create/update the issue, not necessarily the original reporter.
+**Attribution:**
+- Mention who raised the issue when clear from the thread. If the reporter differs from the action requester, keep them separate with durable body text such as `Reported by Alice.` or `Raised by Alice during incident triage.`
+- Attach screenshots from the thread as image links when present.
+- Include code snippets, related issues, and related PRs only when they materially improve the issue.
+### 4. Verify draft
+Before running the `gh` create/edit command, check each gate. If any fails, revise and re-check before executing:
+- Title length ≤ 60 characters.
+- Delegated-action footer is the last line when applicable, using the action requester's real name, not the reporter's name unless they are the same person.
+- 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.
+Run [references/issue-quality-checklist.md](references/issue-quality-checklist.md) for holistic soft-signal review when the draft warrants it.
+### 5. Execute
+- Use `gh issue` commands from [references/api-surface.md](references/api-surface.md).
+- Check duplicates silently before creating a new issue.
+### 6. Report result
+- Return canonical issue URL, issue number, issue type, and applied changes.
+## Guardrails
+- Require explicit confirmation only for close/reopen or destructive broad rewrites.
+- Do not overwrite issue fields unless explicitly requested. Prefer partial updates over full body replacement.
+- For `bug` issues, do not present a fix as definitive unless root-cause evidence is explicit.
+- If repository or installation access is missing, stop and return a concrete remediation message.

package/skills/github-issues/references/api-surface.md ADDED Viewed

@@ -0,0 +1,44 @@
+# GitHub CLI API Surface — issues
+All operations use `gh` CLI. Commands must be deterministic and non-interactive.
+## Repo scoping
+When the user omits `owner/repo`, resolve `github.repo` first with `jr-rpc config get github.repo`, then pass the resolved repo explicitly on the actual `gh` command.
+Treat explicit repo flags as command-targeting safety rails, not as a credential-scoping mechanism.
+## 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 comment`, `gh issue close`, `gh issue reopen` |
+## 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"` |
+## Config helpers
+```bash
+jr-rpc config get github.repo
+jr-rpc config set github.repo owner/repo
+```
+## Behavior notes
+- Prefer `--json` output for machine-readable parsing where available.
+- Use `gh api` for endpoints not fully covered by `gh issue` subcommands.
+- For automation, always fully specify `gh issue create` with `--title` and `--body` or `--body-file`; never rely on interactive prompts.
+- Keep `--repo owner/repo` explicit when working across repositories.
+- Return actionable errors for auth, permission, not-found, and validation failures.

package/skills/github-issues/references/issue-bug.md ADDED Viewed

@@ -0,0 +1,43 @@
+# Bug Issue Guide
+Load when issue type is `bug`. Cross-type rules (title length, delegated footer, generalization, compression) live in `SKILL.md` § Draft issue content.
+## Primary goal
+Produce a high-signal bug issue that drives root-cause discovery, not premature solutioning.
+## Shape
+A few bullets often suffice. Use headed sections only when complexity demands them.
+**Summary** — up to 3 sentences describing the failure and its impact. Short descriptive title (e.g. "OAuth token refresh fails in long-running operations").
+**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** — include only when the thread explicitly states what should happen
+- **Workaround** — current mitigation if one exists
+For simple bugs, skip sections and use flat bullet lists.
+## Research guidance
+Research informs what goes in the issue, not how structured it looks.
+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`).
+Include fix suggestions only when the thread discusses fixes. Do not present a fix as certain without explicit evidence.
+## Context generalization
+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

package/skills/{github → github-issues}/references/issue-examples.md RENAMED Viewed

@@ -69,6 +69,26 @@ Good scope — quantified and specific:
 >
 > Action taken on behalf of Jane Doe.
+## Distinct reporter/requester example
+Bad attribution:
+> The bot resolved the review thread even though the warning still applies.
+>
+> Action taken on behalf of Bojan Oro.
+Good attribution:
+> Warden can resolve its own review thread even when the underlying warning still appears valid and the PR remains blocked.
+>
+> Reported by Bojan Oro.
+>
+> - Observed on a PR where Warden left a review comment about a missing backport
+> - The review thread was later marked resolved by the bot
+> - The PR still showed a blocking warning
+>
+> Action taken on behalf of David Cramer.
 ## Feature example
 Bad framing:
@@ -111,5 +131,6 @@ Good framing — current state, gap, options:
 - 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)
+- Session-specific content (slash commands, channel references, raw transcript framing, or unrelated user chatter)
+- Conflating reporter and action requester when they differ
 - Missing delegated attribution footer on user-requested issue creation

package/skills/github-issues/references/issue-feature.md ADDED Viewed

@@ -0,0 +1,37 @@
+# Feature Issue Guide
+Load when issue type is `feature`. Cross-type rules (title length, delegated footer, generalization, compression) live in `SKILL.md` § Draft issue content.
+## Primary goal
+Propose an intentional improvement with clear current-state analysis and practical options.
+## Shape
+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 improvement. Short imperative title (e.g. "Support SAML SSO for enterprise orgs").
+**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 (include only when the thread discusses alternatives)
+For simple features, skip sections and use flat bullets describing the gap and desired capability.
+## Research guidance
+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
+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

package/skills/github-issues/references/issue-quality-checklist.md ADDED Viewed

@@ -0,0 +1,25 @@
+# Issue Quality Checklist
+Soft-signal review beyond the hard gates in `SKILL.md` § Verify draft. Use when the draft is non-trivial or the stakes warrant extra care.
+## Content signals
+- Summary is short and clear.
+- Analysis depth matches the issue type.
+- Verified claims have inline sources (file paths, PR/issue numbers, doc links).
+- Timeline statements use exact dates when known.
+- Confidence is explicit when certainty is low.
+- Concerns are included only when material, not speculatively.
+- Unknowns are called out, not guessed.
+## Anti-patterns to avoid
+- Overlong, sprawling bodies with no clear sections.
+- Confident solution claims that are weakly evidenced.
+- Speculative detail mixed into verified sections.
+## External guidance
+- GitHub docs, creating and structuring issues: https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/creating-an-issue
+- 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

package/skills/github-issues/references/issue-task.md ADDED Viewed

@@ -0,0 +1,36 @@
+# Task Issue Guide
+Load when issue type is `task`. Cross-type rules (title length, delegated footer, generalization, compression) live in `SKILL.md` § Draft issue content.
+## Primary goal
+Create a concise execution ticket for maintenance, cleanup, docs, refactors, or operational chores.
+## Shape
+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. Short imperative title (e.g. "Remove deprecated legacyAuth middleware").
+**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
+For simple tasks, skip sections and use flat bullets for scope and next step.
+## Research guidance
+- 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
+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

package/skills/{github → github-issues}/references/research-rules.md RENAMED Viewed

@@ -1,10 +1,10 @@
 # Research and Verification Rules
-Use this file for cross-type rules. Then apply the matching type-specific file:
+Cross-type research standards. Apply alongside the matching type-specific guide:
-- `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)
+- `bug`: [issue-bug.md](issue-bug.md)
+- `feature`: [issue-feature.md](issue-feature.md)
+- `task`: [issue-task.md](issue-task.md)
 ## Source Priority

package/skills/github-issues/references/troubleshooting-workarounds.md ADDED Viewed

@@ -0,0 +1,21 @@
+# GitHub CLI Troubleshooting — issues
+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 in the plugin runtime.                  | Verify `gh --version`; if it is unavailable or too old, report that the GitHub plugin runtime dependency is not available.            |
+| `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.                                       |
+| Command affects or authenticates against the wrong repo | Stale `github.repo` default or authenticated command missing explicit repo. | Pass `--repo owner/repo` for the target repository, or update `github.repo` before retrying.                                          |
+| `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                                        | Repo context is missing, stale, or the stored GitHub auth needs reconnect.  | Verify `--repo owner/repo` or `github.repo`, then retry the real command once so the runtime can reconnect automatically when needed. |
+| 403 Forbidden                                           | App lacks required permission on repo or install scope is too narrow.       | Verify the repo context, then 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`.                                                               |
+| `gh issue edit` does not change labels                  | Wrong flag usage or wrong repo context.                                     | Use repeated `--add-label/--remove-label` flags and keep `--repo owner/repo` explicit.                                                |
+| 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 verifying repo context.
+- Do not loop retries on repeated 401/403/404 validation errors.
+- For persistent permission problems, return explicit remediation and stop.

package/skills/github/SKILL.md DELETED Viewed

@@ -1,173 +0,0 @@
----
-name: github
-description: Manage GitHub issue workflows, source-code investigation, pull request operations, repository checkout, and implicit GitHub credentials via GitHub CLI with concise, evidence-backed content. Use when users ask to inspect implementation details in a repository, clone code, edit files, answer source-code questions from repo evidence, open/edit/view pull requests, or open/edit/inspect GitHub issues. Prefer this skill for repository and code tasks even when the repo concerns Sentry products.
-uses-config: github.repo
-allowed-tools: bash
----
-# GitHub Operations
-Issue workflows, pull request operations, and repository checkout via `gh` CLI.
-## Reference loading
-Load references conditionally based on the operation:
-| Operation                            | Load                                                                                                                                                                                        |
-| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Any operation                        | [references/api-surface.md](references/api-surface.md)                                                                                                                                      |
-| `clone`, `pull request create`       | [references/common-use-cases.md](references/common-use-cases.md)                                                                                                                            |
-| `source-code investigation`          | [references/research-rules.md](references/research-rules.md)                                                                                                                                |
-| `issue create`, `issue body rewrite` | [references/issue-examples.md](references/issue-examples.md), the matching type-specific template and type-specific rules, and [references/research-rules.md](references/research-rules.md) |
-| On failure                           | [references/troubleshooting-workarounds.md](references/troubleshooting-workarounds.md)                                                                                                      |
-## Workflow
-### 1. Resolve operation and target
-- Determine whether the task is `clone`, `source-code investigation`, an issue operation (`create`, `update`, `comment`, `labels`, `state`, or read-only inspection), a pull request inspection (`view`, `list`, `diff`, or `checks`), or a pull request mutation (`create`, `update`, `close`, or `merge`).
-- Resolve repository (`owner/repo`). If it is not explicit, query channel config with `jr-rpc config get github.repo` before running any `gh` or `git` command.
-- If config exists and is valid `owner/repo`, use it as the default and still pass it explicitly on subsequent `gh` commands instead of relying on ambient CLI context.
-- If repository is still missing, ask the user for `owner/repo`.
-- Resolve the issue number for non-create issue operations.
-- Resolve the pull request number for pull request operations that target an existing PR.
-- Keep `owner/repo` explicit on `gh` commands whenever the task targets a specific repository. This keeps the command pointed at the right repo and avoids accidental cross-repo mutations. Do not rely on a stale `github.repo` default when hopping between repos.
-### 2. Execute by operation type
-**Clone** → Follow the clone path below.
-**Source-code investigation** → Follow the source-code path below.
-**Issue operation** → Follow the issue path below.
-**Pull request inspection** → Follow the pull request inspection path below.
-**Pull request mutation** → Follow the pull request mutation path below.
----
-### Clone path
-- Default to a shallow clone.
-- Use exact command forms from [references/api-surface.md](references/api-surface.md) or [references/common-use-cases.md](references/common-use-cases.md).
-- Deepen incrementally only when the task needs repository history.
-- After cloning, check for `AGENTS.md` in the repo root (and `.github/AGENTS.md`) before making edits. Treat discovered instructions as hard constraints.
-- Report the local directory and whether the clone is shallow or full.
----
-### Source-code investigation path
-- Use this path for questions like "where is this implemented?", "how does this workflow work in code?", "is there already logic for X?", or "verify this from the repo."
-- Resolve repository (`owner/repo`). If the current workspace already contains the target repository, inspect local files directly before cloning anything.
-- If you need repository access outside the current workspace, keep `owner/repo` explicit on the authenticated command so the command itself targets the correct repository.
-- Default to a shallow clone when you need a fresh checkout; deepen only if the question truly needs history.
-- Prefer the narrowest deterministic evidence that answers the question: local file search, exact file reads, targeted clone inspection, existing issues/PRs, and tests.
-- Cite repository evidence in the reply: file paths, symbols, issue/PR numbers, or commit references when known.
-- If the available evidence is incomplete, say what is unknown instead of guessing.
----
-### Issue path
-#### 3. Classify issue type
-- 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.
-#### 4. Draft issue content
-Load the type-specific template and rules:
-| Type      | Template                                                                     | Research rules                                                       |
-| --------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| `bug`     | [references/issue-template-bug.md](references/issue-template-bug.md)         | [references/issue-type-bug.md](references/issue-type-bug.md)         |
-| `feature` | [references/issue-template-feature.md](references/issue-template-feature.md) | [references/issue-type-feature.md](references/issue-type-feature.md) |
-| `task`    | [references/issue-template-task.md](references/issue-template-task.md)       | [references/issue-type-task.md](references/issue-type-task.md)       |
-Follow [references/research-rules.md](references/research-rules.md) for cross-type research standards.
-- 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.
-#### 5. Execute operation
-- Use fully specified, non-interactive `gh` commands from [references/api-surface.md](references/api-surface.md).
-- Use [references/common-use-cases.md](references/common-use-cases.md) only when you need a concrete command pattern.
-- Check duplicates silently before creating a new issue. Only mention duplicates when relevant matches are actually found.
-- Treat GitHub auth as plugin-owned and turn-scoped. The skill determines whether GitHub credentials are available for the turn; explicit repo flags are still for command correctness and mutation safety.
-#### 6. Report result
-- Return canonical issue URL, issue number, issue type, applied changes, and confidence.
-- Include references used for verified claims.
-- Keep routine issue-creation steps silent. Do not post progress chatter about duplicate checks, drafting, credential issuance, or command execution before the final result.
-- Never mention silent duplicate checking in the final reply unless you actually found a relevant duplicate that changed the outcome.
-- If duplicate checking found no relevant matches, omit that fact entirely and report only the created issue, for example `Created issue #123: ...`, not `No duplicates found. Creating the issue now.`
----
-### Pull request inspection path
-#### 3. Execute inspection
-- Use exact read-only `gh pr` commands from [references/api-surface.md](references/api-surface.md).
-- Skip branch resolution and push logic for inspection-only work.
-#### 4. Report result
-- Return canonical PR URL, PR number when available, target repository, and the fields the user asked to inspect.
-- If the requested PR cannot be resolved, report the exact not-found or auth failure and stop.
----
-### Pull request mutation path
-#### 3. Resolve mutation inputs
-- For PR creation, resolve the base branch. Use the explicit user request when present; otherwise use the repository default branch.
-- For PR creation, resolve the head branch from the current checkout or user request.
-- For PR creation, if the current branch may not exist on the remote yet, push it explicitly before PR creation.
-#### 4. Execute pull request operation
-- For PR creation, do not rely on `gh pr create` to push or fork implicitly.
-- For PR creation, if the head branch is not already on the remote, run `git push` first. That push step needs GitHub write access for the remote repository.
-- If `git push` returns 401, 403, or another auth/permission error, verify the command is still targeting the right repository and retry once. If the error still clearly indicates bad or revoked credentials, rerun the real GitHub command and let the runtime trigger a reconnect flow.
-- After the branch exists remotely, run `gh pr create --repo owner/repo --head BRANCH ...`.
-- For PR creation, use `--head` so `gh` skips its hidden push/fork flow.
-- Treat `gh pr merge` as a contents mutation and keep repository context explicit so the command cannot hit the wrong repository.
-- Treat issue comments and label edits as issue mutations and keep repository context explicit on the command.
-#### 5. Report result
-- Return canonical PR URL, PR number when available, target repository, and applied changes.
-- If PR creation fails after explicit push + explicit repo scoping, report the exact auth or validation failure and stop.
-## Guardrails
-### Execution
-- 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.
-- Do not overwrite issue fields unless explicitly requested. Prefer partial updates over full body replacement.
-### Quality
-- Never claim verification without citing sources.
-- Answer source-code and implementation questions from repository evidence, not product framing or generic memory.
-- For `bug` issues, do not present a fix as definitive unless root-cause evidence is explicit.
-- If no relevant duplicates are found, continue directly to draft and create the issue, then report the created issue.
-### Scope
-- Issue workflows, pull request operations, and repository checkout. Do not execute repository admin mutations.
-- Default to shallow clones. Do not use a full clone unless the task requires repository history or the user asks for it.
-- If repository or installation access is missing, stop and return a concrete remediation message.

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

@@ -1,71 +0,0 @@
-# GitHub CLI API Surface
-All operations use `gh` CLI. Commands must be deterministic and non-interactive.
-## Authentication
-Load the GitHub skill first, then keep `--repo owner/repo` explicit on authenticated `gh` commands unless you intentionally rely on a verified `github.repo` default for the same repository.
-When the user omits `owner/repo`, resolve `github.repo` first with `jr-rpc config get github.repo`, then pass the resolved repo explicitly on the actual `gh` command.
-The runtime injects GitHub credentials implicitly for the current turn once the GitHub skill is active.
-Treat explicit repo flags as command-targeting safety rails that reduce accidental writes and wrong-repo mutations, not as a credential-scoping mechanism.
-## Capability to command mapping
-| Capability                   | Commands                                                                                    |
-| ---------------------------- | ------------------------------------------------------------------------------------------- |
-| `github.contents.read`       | `gh repo clone`, `git fetch`                                                                |
-| `github.contents.write`      | `git push`, `gh api` (create/update file contents), `gh pr merge`                           |
-| `github.issues.read`         | `gh issue view`, `gh api /repos/.../comments`                                               |
-| `github.issues.write`        | `gh issue create`, `gh issue edit`, `gh issue comment`, `gh issue close`, `gh issue reopen` |
-| `github.pull-requests.read`  | `gh pr view`, `gh pr list`, `gh pr diff`, `gh pr checks`                                    |
-| `github.pull-requests.write` | `gh pr create --head <branch>` after explicit push, `gh pr edit`, `gh pr close`             |
-## Command matrix
-| Operation                          | Command                                                                                                       |
-| ---------------------------------- | ------------------------------------------------------------------------------------------------------------- | -------- | ---------- |
-| Clone repository (default shallow) | `gh repo clone owner/repo [DIRECTORY] -- --depth=1`                                                           |
-| Deepen shallow clone               | `git -C DIRECTORY fetch --depth=N origin`                                                                     |
-| Convert shallow clone to full      | `git -C DIRECTORY fetch --unshallow`                                                                          |
-| 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"` |
-| Push branch before PR creation     | `git -C DIRECTORY push -u origin BRANCH`                                                                      |
-| Create pull request                | `gh pr create --repo owner/repo --head BRANCH --base BASE --title "..." --body-file PATH`                     |
-| Update pull request                | `gh pr edit NUMBER --repo owner/repo [--title "..."] [--body-file PATH]`                                      |
-| Close pull request                 | `gh pr close NUMBER --repo owner/repo`                                                                        |
-| Merge pull request                 | `gh pr merge NUMBER --repo owner/repo [--merge                                                                | --squash | --rebase]` |
-## Config helpers
-Resolve repo default:
-```bash
-jr-rpc config get github.repo
-```
-Set repo default:
-```bash
-jr-rpc config set github.repo owner/repo
-```
-## Behavior notes
-- Prefer `--json` output for machine-readable parsing where available.
-- Use `gh api` for endpoints not fully covered by `gh issue` subcommands.
-- Pass extra `git clone` flags after `--` (e.g. `gh repo clone owner/repo -- --depth=1`).
-- For automation, always fully specify `gh issue create` with `--title` and `--body` or `--body-file`; never rely on interactive prompts.
-- Before `gh pr create`, push the head branch explicitly, then use `--head` so `gh` does not trigger hidden push/fork behavior.
-- That explicit `git push` step requires GitHub write access to the remote repository.
-- If that explicit `git push` fails with 401/403 or another auth/permission error, verify the repo context and retry the same push once after clearing stale GitHub auth only when the error explicitly indicates bad credentials.
-- Keep `--repo owner/repo` explicit on authenticated GitHub commands when working across repositories.
-- `gh pr edit` is not a single-permission command: title/body/base/reviewer changes fit `github.pull-requests.write`, label, assignee, and milestone changes fit `github.issues.write`, and project flags are outside the current GitHub App capability model.
-- `gh pr close --comment` may need `github.issues.write`, and `gh pr close --delete-branch` needs `github.contents.write`.
-- Return actionable errors for auth, permission, not-found, and validation failures.

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

@@ -1,99 +0,0 @@
-# Common GitHub CLI Use Cases
-Use these patterns as direct execution playbooks.
-## 1) Clone a repository for local work
-Default to a shallow clone:
-```bash
-gh repo clone owner/repo -- --depth=1
-```
-Clone into a specific directory:
-```bash
-gh repo clone owner/repo worktree/repo -- --depth=1
-```
-## 2) Deepen a shallow clone only when needed
-```bash
-git -C worktree/repo fetch --depth=50 origin
-```
-Convert to a full clone:
-```bash
-git -C worktree/repo fetch --unshallow
-```
-## 3) Create a bug issue
-```bash
-gh issue create --repo owner/repo --title "OAuth token refresh fails in long-running thread" --body-file /vercel/sandbox/tmp/issue.md
-```
-`/vercel/sandbox/tmp/issue.md` should end with:
-```md
-Action taken on behalf of Jane Doe.
-```
-## 4) Patch issue title/body
-```bash
-gh issue edit 123 --repo owner/repo --title "Clarify retry semantics for lock contention" --body-file /vercel/sandbox/tmp/revised-issue.md
-```
-## 5) Close or reopen issue
-```bash
-gh issue close 123 --repo owner/repo --comment "Fixed in #456"
-```
-Reopen:
-```bash
-gh issue reopen 123 --repo owner/repo
-```
-## 6) Add implementation comment
-```bash
-gh issue comment 123 --repo owner/repo --body-file /vercel/sandbox/tmp/comment.md
-```
-## 7) Apply triage labels
-```bash
-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
-```
-## 8) Read issue details before mutation
-```bash
-gh issue view 123 --repo owner/repo --json number,title,state,labels,assignees,author,url,body
-```
-## 9) Read comment history in JSON
-```bash
-gh api /repos/owner/repo/issues/123/comments --method GET --header "Accept: application/vnd.github+json"
-```
-## 10) Create a pull request safely in automation
-Push the branch explicitly before creating the PR. This avoids `gh pr create`
-trying to push or fork implicitly.
-```bash
-git -C worktree/repo push -u origin BRANCH
-gh pr create --repo owner/repo --head BRANCH --base main --title "fix(repo): narrow GitHub repo scoping" --body-file /vercel/sandbox/tmp/pr.md
-```

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

@@ -1,40 +0,0 @@
-# Issue Quality Checklist
-Run this checklist before create/update mutation.
-## External Quality Signals
-- 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
-- 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. 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 DELETED Viewed

@@ -1,37 +0,0 @@
-# Bug Issue Template
-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. Use a short descriptive title (e.g. "OAuth token refresh fails in long-running operations").
-## 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** — 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
-- 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. 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.
-- 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 DELETED Viewed

@@ -1,36 +0,0 @@
-# Feature Issue Template
-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 improvement. Use a short imperative title (e.g. "Support SAML SSO for enterprise orgs").
-## 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 (include only when the thread discusses alternatives)
-For simple features, skip sections and use flat bullets describing the gap and desired capability.
-## Attribution
-- 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. 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.
-- 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 DELETED Viewed

@@ -1,35 +0,0 @@
-# Task Issue Template
-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. Use a short imperative title (e.g. "Remove deprecated legacyAuth middleware").
-## 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
-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. 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.
-- 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 DELETED Viewed

@@ -1,30 +0,0 @@
-# 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.
-## Research Guidance
-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.
-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`).
-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

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

@@ -1,27 +0,0 @@
-# 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.
-## Research Guidance
-Use these steps to investigate — they inform what goes into the issue, but do not dictate issue structure.
-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

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

@@ -1,25 +0,0 @@
-# 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 Guidance
-- 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

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

@@ -1,17 +0,0 @@
-# Sandbox Runtime Guidance
-This skill runs in the harness sandbox (`node22`) and commands execute via the `bash` tool.
-## 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>`.
-## Credential strategy
-1. After the GitHub skill is loaded, the runtime injects GitHub credentials implicitly for the current turn.
-2. Keep repository context explicit on `gh` and `git` commands so the command itself targets the correct repo.
-3. Credentials are valid only for the current turn. Do not persist tokens in files.
-4. If auth fails, verify the command still targets the correct repo, then retry the real GitHub command once so the runtime can reconnect automatically when needed.