fix(github): Skip duplicate-check narration when creating issues (#117)

dcramer · claude · web-flow · commit cda4e687f491 · 2026-03-24T12:15:17.000-07:00
Add a guardrail to the GitHub skill that suppresses negative duplicate-search reporting (e.g. "no duplicates found") when the user explicitly asks to create an issue. The agent still searches for duplicates as part of its research, but only surfaces results when matches are actually found and are relevant. Additionally restructures the GitHub skill for clarity: - Merge `github-issue-api.md` into `api-surface.md` to eliminate duplicate command references - Add conditional reference loading table so the agent only loads files relevant to the current operation - Separate clone and issue paths into distinct workflow branches - Group guardrails by concern (execution, quality, scope) - Remove delegated footer instruction from SKILL.md (already in every template) Adds an eval to verify the dupe-narration behavior. Fixes #113 --------- Co-authored-by: Claude <noreply@anthropic.com>
diff --git a/packages/junior-github/skills/github/SKILL.md b/packages/junior-github/skills/github/SKILL.md
@@ -8,11 +8,24 @@ allowed-tools: bash
 
 # GitHub Operations
 
-Use this skill for GitHub issue workflows in the harness. Issues are the primary surface. Repository checkout is limited to `gh repo clone` guidance and execution when local code context is needed.
+Issue workflows 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`            | [references/sandbox-runtime.md](references/sandbox-runtime.md)                                                                               |
+| `create`           | Type-specific template + research rules (see step 3)                                                                                         |
+| `create`, `update` | [references/issue-quality-checklist.md](references/issue-quality-checklist.md), [references/issue-examples.md](references/issue-examples.md) |
+| On failure         | [references/troubleshooting-workarounds.md](references/troubleshooting-workarounds.md)                                                       |
+| Credential issues  | [references/sandbox-runtime.md](references/sandbox-runtime.md)                                                                               |
 
 ## Workflow
 
-1. Confirm operation and target:
+### 1. Resolve operation and target
 
 - Determine `clone`, `create`, `update`, `comment`, `labels`, `state`, or read-only inspection.
 - Resolve repository (`owner/repo`) and issue number for non-create issue operations.
@@ -21,19 +34,30 @@ Use this skill for GitHub issue workflows in the harness. Issues are the primary
 - If config exists and is valid `owner/repo`, use it as default.
 - If repository is still missing, ask the user for `owner/repo`.
 
-2. Handle repository checkout first when operation is `clone`:
+### 2. Execute by operation type
+
+**Clone** → Follow the clone path below.
+**Issue operation** → Follow the issue path below.
+
+---
+
+### Clone path
 
-- Default to a shallow clone for local inspection or one-off edits:
+- Default to a shallow clone:
   - `gh repo clone owner/repo [directory] -- --depth=1`
 - Pass extra `git clone` flags only after `--`.
-- Use a full-history clone only when the task explicitly needs history-heavy operations such as `git blame`, `git bisect`, tag/release archaeology, or broad commit-log analysis.
-- If the initial shallow clone is insufficient, deepen incrementally instead of recloning:
+- Use full-history clone only when the task needs `git blame`, `git bisect`, tag/release archaeology, or broad commit-log analysis.
+- Deepen incrementally instead of recloning:
   - `git -C <directory> fetch --depth=<n> origin`
   - `git -C <directory> fetch --unshallow`
-- When cloning a fork, keep the default upstream remote behavior unless the user asks for a different remote name.
-- After checkout, report the local directory and whether the clone is shallow or full. Stop here for clone-only requests.
+- When cloning a fork, keep the default upstream remote behavior unless the user asks otherwise.
+- Report the local directory and whether the clone is shallow or full.
+
+---
+
+### Issue path
 
-3. Classify issue type before drafting:
+#### 3. Classify issue type
 
 - Use explicit user type when provided (`bug`, `feature`, `task`).
 - Otherwise infer from intent:
@@ -42,51 +66,53 @@ Use this skill for GitHub issue workflows in the harness. Issues are the primary
   - `task`: maintenance, cleanup, docs, refactor, operational chore.
 - Default to `task` when uncertain.
 
-4. Draft issue content:
+#### 4. Draft issue content
+
+Load the type-specific template and research 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.
 
-- 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).
-- When creating a new issue on behalf of a user, append a final attribution line at the end of the body in the form `Action taken on behalf of <name>.`
-- Use the clearest available user identifier from conversation context. Prefer a human name, then stable handle, and do not omit attribution for delegated mutations.
 
-5. Execute operation:
+#### 5. Execute operation
 
-- Select the matching declared capability for the operation:
+- Issue the matching capability credential before executing:
   - Read-only (`gh issue view`, comment reads via `gh api`): `github.issues.read`
   - Create/update/state changes: `github.issues.write`
   - Comments: `github.issues.comment`
   - Labels: `github.labels.write`
-- Repository checkout does not need a GitHub issue capability. Use `gh repo clone` directly.
 - 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) when you need the GitHub CLI credential delivery details.
 
-6. Report result:
+#### 6. Report result
 
-- Return canonical issue URL, issue number, issue type, applied changes, and confidence for issue workflows.
-- For clone operations, return the repository, local directory, clone mode (`shallow` or `full`), and any follow-up deepen/unshallow action taken.
+- Return canonical issue URL, issue number, issue type, applied changes, and confidence.
 - Include references used for verified claims.
 
 ## 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.
-- Default to shallow clones for efficiency. Do not use a full clone unless the task requires repository history or the user asks for it.
+- Do not overwrite issue fields unless explicitly requested. Prefer partial updates over full body replacement.
+
+### Quality
+
 - 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.
+- Do not report negative duplicate-search results to the user (e.g. "no duplicates found"). Searching for duplicates is expected, but only mention duplicates when matches are actually found and are relevant to surface.
+
+### Scope
+
+- Issue workflows plus repository checkout only. Do not execute pull-request or 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.
-- Scope is issue workflows plus repository checkout. Do not execute pull-request or repository admin mutations in this skill.
diff --git a/packages/junior-github/skills/github/references/api-surface.md b/packages/junior-github/skills/github/references/api-surface.md
@@ -1,37 +1,41 @@
 # GitHub CLI API Surface
 
-This skill supports issue workflows plus repository checkout via `gh repo clone`.
+All operations use `gh` CLI. Commands must be deterministic and non-interactive.
 
-All operations use `gh` CLI.
+## 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.
 
 ## Capability to command mapping
 
-| Capability | Commands |
-| --- | --- |
-| none required | `gh repo clone` |
-| `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` |
+| Capability              | Commands                                                                |
+| ----------------------- | ----------------------------------------------------------------------- |
+| none required           | `gh repo clone`                                                         |
+| `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 |
-| --- | --- |
-| 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"` |
-
-## Credential + config helper commands
+| 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"` |
+
+## Credential and config helpers
 
 Resolve repo default:
 
@@ -45,12 +49,6 @@ Set repo default:
 jr-rpc config set github.repo owner/repo
 ```
 
-Pass extra `git clone` flags after `--`:
-
-```bash
-gh repo clone owner/repo -- --depth=1 --filter=blob:none
-```
-
 Issue scoped credentials:
 
 ```bash
@@ -59,3 +57,10 @@ jr-rpc issue-credential github.issues.write
 jr-rpc issue-credential github.issues.comment
 jr-rpc issue-credential github.labels.write
 ```
+
+## 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`).
+- Return actionable errors for auth, permission, not-found, and validation failures.
diff --git a/packages/junior-github/skills/github/references/github-issue-api.md b/packages/junior-github/skills/github/references/github-issue-api.md
diff --git a/packages/junior/evals/conversational/skill-workflows.eval.ts b/packages/junior/evals/conversational/skill-workflows.eval.ts
@@ -67,6 +67,22 @@ describe("Conversational Evals: Skill Workflows", () => {
     thread_ts: "17000000.default-repo",
   };
 
+  slackEval("skills: github issue create skips dupe narration", {
+    overrides: {
+      enable_test_credentials: true,
+      plugin_packages: ["@sentry/junior-github"],
+      test_credential_token: "eval-github-token",
+      skill_dirs: ["skills"],
+    },
+    events: [
+      mention(
+        "Create an issue for adding rate limiting to the API endpoint in getsentry/junior",
+      ),
+    ],
+    criteria:
+      "The assistant creates a GitHub issue without narrating duplicate-search results. The reply must not mention checking for duplicates, searching for similar issues, or reporting that no duplicates were found. The reply should proceed directly to issue creation and report the result.",
+  });
+
   slackEval("skills: default repo setup via natural language", {
     overrides: {
       enable_test_credentials: true,
