You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
ref(github-code): Add edit workflow, verification, and on-behalf-of attribution
Extend the github-code skill from a GitHub CLI reference into a compact
repo-edit and PR workflow skill, folding in the high-value rules from
code-change that were previously only in reference files.
Key additions:
- Core rules: instruction precedence, no-guessing guardrails, no fake
check claims
- Resolve target: validation path selection (scoped checks > targeted
tests > full suites), baseline capture for risky work, pre-existing
failure separation
- Investigation: read referenced context, inspect real product context
for UI/docs, know failure shape before editing bugs, re-root-cause
after failed fix
- Edit: keep public surfaces minimal, remove introduced duplication,
solve the behavior not just the tests, compact checklist for
multi-step work, pause-and-plan for non-obvious work
- Verify: explicit pre-packaging validation step
- Commit: on-behalf-of Co-authored-by trailers inline, footer ordering,
line length
- PR: draft by default, reviewer-facing prose, session link footer,
Action taken on behalf of footer, handle resolution before assignment
- api-surface.md: branch, status, log, diff, commit commands; default
PR creation to --draft
Intentionally not included: full advisor protocol (orchestration-level),
diff-quality gate (separate skill), exhaustive verification harness
table (conditional detail), multi-viewport screenshot protocol.
Co-authored-by: David Cramer <david@sentry.io>
- Resolve the target repo: explicit request wins, then `github.repo` config. Run `jr-rpc config get github.repo` standalone — never chain with `cd`, pipes, `gh`, or `git`.
21
+
- Keep `--repo owner/repo` explicit on all `gh` commands; use `git -C PATH` for local repos.
22
+
- Do not treat this skill's files or `/skills/...` as target repository source.
23
+
- Read repo-local instructions (`AGENTS.md`, `.github/AGENTS.md`, nested equivalents) before editing. When repo, task-specific, and skill instructions conflict, follow the narrower rule.
24
+
- Do not overwrite or revert unrelated user changes.
25
+
- Do not guess architecture, upstream intent, or feedback validity without reading the relevant code, comments, or failing output.
26
+
- Do not claim checks ran unless they did. Do not declare a fix complete without running the chosen check or stating why no credible check was available.
27
+
- Stop on: missing repo access, ambiguous target, destructive op without confirmation, or unresolved auth failure.
17
28
18
29
## Workflow
19
30
20
-
### 1. Resolve operation and target
31
+
### 1. Resolve target and state
21
32
22
-
- 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`).
23
-
- Resolve repository from the requested action: explicit target wins; otherwise use `<configuration>``github.repo`. If absent, run standalone `jr-rpc config get github.repo`.
24
-
- Preserve non-target GitHub references when they materially support the work.
25
-
- Run `jr-rpc config get github.repo` as its own bash command. Do not combine it with `cd`, `&&`, pipes, or any `gh` or `git` command.
26
-
- After resolving a configured repo, pass it explicitly to the next `gh` command with `--repo owner/repo`; do not rely on implicit GitHub CLI repository discovery.
27
-
- Resolve the pull request number for operations targeting an existing PR.
28
-
- Keep `--repo owner/repo` explicit on `gh` commands so the command itself targets the intended repository, not a stale default.
33
+
Identify `owner/repo`, local checkout path, default branch, and current branch.
- repo-local instructions that override this skill
36
41
37
-
---
42
+
Choose a validation path before editing:
38
43
39
-
### Clone path
44
+
- changed-file or package-scoped checks before broad suites
45
+
- targeted tests before full runs
46
+
- repo-native scripts, fixtures, playgrounds, or smoke checks before one-off scaffolding
40
47
41
-
- Default to a shallow clone; deepen incrementally only when the task needs history.
42
-
- Use exact command forms from [references/api-surface.md](references/api-surface.md).
43
-
- After cloning, check for `AGENTS.md` in the repo root (and `.github/AGENTS.md`) before making edits. Treat discovered instructions as hard constraints.
44
-
- Report the local directory and whether the clone is shallow or full.
48
+
For risky, user-visible, or long-running changes, capture a baseline before editing. If the baseline already fails, record it as pre-existing.
45
49
46
-
---
50
+
Prefer existing local checkouts over cloning. Default to shallow clones.
47
51
48
-
### Source-code investigation path
52
+
### 2. Investigate before editing
49
53
50
-
- 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."
51
-
- If the current workspace already contains the target repository, inspect local files directly before cloning.
52
-
- Do not treat this skill's `SKILL.md`, bundled references, or `/vercel/sandbox/skills/...` as target repository source code. If no checkout of the target repo is present, inspect the configured GitHub repository by cloning it shallowly or reading files through `gh` before answering.
53
-
- Prefer the narrowest deterministic evidence: local file search, exact file reads, targeted clone inspection, existing issues/PRs, tests.
54
-
- Cite repository evidence in the reply: file paths, symbols, issue/PR numbers, or commit references when known.
55
-
- If evidence is incomplete, say what is unknown instead of guessing.
- Read referenced issues, PRs, specs, policies, designs, or incidents when the task points to them.
65
+
- For product copy, docs, design, or UI work, inspect the real product/project context before inventing wording or layout.
66
+
- Before editing a bug, know the failure shape: what breaks, where, and under what condition.
67
+
- After a failed fix attempt or strong correction, stop patching symptoms — re-read the evidence and restate the root cause before editing again.
68
+
- If the task is investigation-only, answer from evidence without editing.
69
+
70
+
### 3. Edit safely
71
+
72
+
- Smallest coherent change that satisfies the request.
73
+
- Follow repo-local style, patterns, and API boundaries.
74
+
- Keep interfaces, exports, config, and public surfaces no broader than the requirement needs.
75
+
- When the change touches related call sites or representations, remove duplication or split logic introduced by the change before finalizing.
76
+
- No drive-by refactors or speculative cleanup.
77
+
- Do not optimize only for passing tests; solve the requested behavior.
78
+
- After meaningful edits, run the smallest relevant repo-real check.
79
+
- On check failure, inspect root cause before patching again.
80
+
81
+
For multi-step or risky work, keep a compact checklist of intent, touched files, verification state, next step, and blockers.
82
+
83
+
For non-obvious architecture, security-sensitive, concurrency, or repeated-failure work, pause after investigation with evidence, risks, and a proposed plan before pushing ahead.
84
+
85
+
### 4. Verify before packaging
86
+
87
+
Before committing and creating a PR for code, config, or docs-as-code changes:
88
+
89
+
- Run the chosen validation path. Separate pre-existing failures from regressions.
90
+
- For docs or instruction-only changes, do a content consistency review instead of claiming automated validation.
91
+
- If no credible check exists, say so explicitly.
92
+
93
+
### 5. Commit
94
+
95
+
Default format when the repo does not specify otherwise:
96
+
97
+
```
98
+
<type>(<scope>): <Subject>
99
+
```
100
+
101
+
Types: `feat`, `fix`, `ref`, `docs`, `test`, `build`, `ci`, `chore`. Imperative present tense, no trailing period, no agent/tool branding. Keep lines under 100 characters.
58
102
59
-
### Pull request inspection path
103
+
Body only when it helps reviewers understand _why_.
60
104
61
-
- Use read-only `gh pr` commands from [references/api-surface.md](references/api-surface.md); skip branch resolution and push logic.
62
-
- When inspecting PR comments or feedback, query both conversation comments (`--json comments`) and review comments (`gh api .../pulls/{number}/comments` and `.../reviews`). Bot review feedback lives in the review comments API, not conversation comments.
63
-
- Return canonical PR URL, PR number when available, target repository, and the fields the user asked to inspect.
64
-
- If the PR cannot be resolved, report the exact not-found or auth failure and stop.
105
+
Footer order: `Fixes`/`Refs` lines, then `Co-authored-by` trailers.
65
106
107
+
#### On-behalf-of commits
108
+
109
+
If the commit is authored by a bot and a human requested the work, add a trailer:
110
+
111
+
```
112
+
Co-authored-by: Full Name <email>
113
+
```
114
+
115
+
Resolve name and email from evidence — requester context, Slack profile (`slackUserLookup`), GitHub profile, or repo commit history. If email cannot be confirmed, use `Full Name <noreply>` and note the gap in the PR body.
116
+
117
+
### 6. Create or update PR
118
+
119
+
Before creating:
120
+
121
+
1. Changes committed on a non-default branch.
122
+
2. Push the branch explicitly: `git push -u origin BRANCH`.
- Draft PRs unless the user or repo says otherwise.
128
+
- Reuse an existing PR for the branch; only open a new one when explicitly asked or the work is materially distinct.
129
+
- After new commits, re-evaluate title and body against the current diff.
130
+
131
+
**Title:**`<type>(<scope>): <Subject>` — same rules as commits, no agent branding.
132
+
133
+
**Body:**
134
+
135
+
- Reviewer-facing prose, not diff narration.
136
+
- What changed and why; what was verified; what remains unverified or risky.
137
+
- Issue references when relevant.
138
+
- No checkbox boilerplate, no PII or customer data in public repos.
139
+
140
+
**Footers** (in order):
141
+
142
+
1. Issue references (`Fixes #N`, `Refs SENTRY-N`), if any.
143
+
2.`Action taken on behalf of Full Name.` — when on-behalf-of.
144
+
3. Session link — when `gen_ai.conversation.id` is available:
145
+
146
+
```
66
147
---
148
+
[View Session in Sentry](https://sentry.sentry.io/traces/?project=4510944073809921&query=gen_ai.conversation.id%3A%22<url-encoded conversation id>%22)
149
+
```
150
+
151
+
**Assignment:** resolve GitHub handles from evidence (`gh api search/users`, org membership, repo history) before assigning reviewers or the requester. Skip assignment when the handle cannot be confirmed.
152
+
153
+
### 7. Report result
154
+
155
+
Return: repo, branch, PR URL/number (when applicable), checks run with results, pre-existing failures if any, checks not run and why.
67
156
68
-
### Pull request mutation path
157
+
On failure, report the exact command and error. Do not claim success from partial state.
69
158
70
-
#### 3. Resolve mutation inputs
159
+
Before finishing, reconcile any plan or checklist stated earlier — mark items as done, blocked, or cancelled.
71
160
72
-
- For PR creation credential/order questions, explicitly answer that repository context comes first, then `git push` pushes the branch with GitHub remote write access, then `gh pr create` runs against the pushed branch with pull-request permissions.
73
-
- For PR creation, resolve the base branch (explicit user request wins; otherwise repository default).
74
-
- Resolve the head branch from the current checkout or user request.
75
-
- If the head branch may not exist on the remote yet, push it explicitly before PR creation.
161
+
## Operation-specific notes
76
162
77
-
#### 4. Execute
163
+
**Clone** — shallow by default; deepen only when history is needed. Read repo instructions after cloning, before editing.
78
164
79
-
- Run `git push` first so `gh pr create` does not trigger hidden push/fork behavior; then `gh pr create --repo owner/repo --head BRANCH ...`.
80
-
- 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 fails, report the exact command failure and the GitHub App installation/permission remediation.
81
-
- Treat `gh pr merge` as a contents mutation and keep repository context explicit.
165
+
**Source investigation** — use local files first, otherwise clone shallowly or use `gh`. Cite evidence: file paths, symbols, PRs, issues, command output.
82
166
83
-
#### 5. Report result
167
+
**PR inspection** — read-only `gh pr` and `gh api` commands. Query both conversation comments (`--json comments`) and review comments (`gh api .../pulls/{n}/comments` and `.../reviews`).
84
168
85
-
- Return canonical PR URL, PR number when available, target repository, and applied changes.
86
-
- If PR creation fails after explicit push + explicit repo scoping, report the exact auth or validation failure and stop.
169
+
**PR mutation** — push before create. Retry once on auth failure after verifying repo targeting. Treat merge, close-with-delete, and force-push as confirmation-required. No admin mutations.
87
170
88
171
## Guardrails
89
172
90
-
- Require explicit confirmation only for destructive merges or force operations.
91
-
- Answer source-code questions from repository evidence, not product framing or generic memory.
92
-
- Default to shallow clones; do not use a full clone unless the task requires repository history or the user asks for it.
93
-
- If repository or installation access is missing, stop and return a concrete remediation message.
94
-
- GitHub App auth is host-managed; do not ask the user to reconnect a GitHub account.
95
-
- Do not execute repository admin mutations.
173
+
- Default shallow clones; deepen only when needed.
174
+
- Confirm before destructive merges or force operations.
175
+
- Answer source questions from repo evidence, not product framing or memory.
176
+
- GitHub App auth is host-managed; do not ask users to reconnect accounts.
177
+
- Stop and return concrete remediation on missing access or permissions.
![sentry-junior[bot]](https://avatars.githubusercontent.com/in/2960336?v=4&size=40){kind=avatar}
0 commit comments