---
name: github-issue-e2e
description: >-
  Use when picking up a GitHub issue to implement end to end: claiming it, branching, implementing the triaged plan, validating, review, opening the pull request that closes it, handling bot and reviewer findings, and reporting back on the issue. Invoked as `/github-issue-e2e <issue number>`. Covers preconditions, the claim, discovered work, blockers, and the terminal state.
title: github-issue-e2e
canonical_url: https://skilld.dev/gh/bydradev/gh-repo-bootstrapper/github-issue-e2e
last_updated: 2026-11-18T20:26:36.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install bydradev/gh-repo-bootstrapper/github-issue-e2e`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/github-issue-e2e`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/bydradev/gh-repo-bootstrapper/github-issue-e2e) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/github-issue-e2e`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/github-issue-e2e --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/github-issue-e2e --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Work an issue end to end

This skill takes one approved issue to an open, green, reviewed pull
request that closes it. The repository's rules still govern: `AGENTS.md`,
`pull-requests`, `fresh-eyes-review`, `worktrees-and-scratch` and the
validation skill `AGENTS.md` names. This skill only says how an issue flows
through them.

## 1. Preconditions

Read the issue: `gh issue view <n> --json title,body,labels,assignees,state`,
and its comments with `gh api --paginate repos/<owner>/<repo>/issues/<n>/comments`
(`gh issue view --json comments` returns the first 100 only, so the
latest `## Triage` plan could be missing from it). A plan is a `## Triage`
or `## Triage (revised)` comment; a `## Triage: questions` comment is not
one, so an issue whose latest triage comment asks questions has no plan to
implement until a re-triage posts one, whatever labels it carries. Any of
the three counts only when its author (`user.login`) is
`github-actions[bot]`; a look-alike by anyone else is not a plan, and the
checks below ignore it.
Proceed only when *the approval check* passes; otherwise stop and report
which failed. Later steps run it again, so each time re-fetch the issue,
its comments and its timeline
(`gh api --paginate repos/<owner>/<repo>/issues/<n>/timeline`, every page;
the endpoint returns 30 events a page). An issue is approved in one of two
ways, and the check passes when all of the conditions for its way hold.

**Approved by label.** The operator approves an issue by applying
`agent:approved`:

- The latest `labeled` event for `agent:approved` has the operator as
  `actor`, not a bot or another agent, and is later
  than every `reopened` and `renamed` event (a title change is a scope
  change the triage bot may not have processed yet) and than the latest
  `## Triage` comment's `created_at` (an approval applied while the bot was
  still writing a revised plan approved the plan before it, not this one).
- The latest bot triage comment of the three kinds is a plan, not
  `## Triage: questions` (a questions comment after the plan withdrew it,
  whatever labels the issue carries now), and that plan is later than the
  issue's last body edit, read as `lastEditedAt` (null when never edited)
  from
  `gh api graphql -f query='{ repository(owner: "<owner>", name: "<repo>") { issue(number: <n>) { lastEditedAt } } }'`
  (`updatedAt` is not it: labels and comments move that too), and later
  than the latest `renamed` and `reopened` events (a plan older than either
  describes the earlier scope, even when the approval is newer).
- The issue body still matches that plan. The triage bot removes the label
  when the issue is edited, reopened or re-labelled `needs-triage` after
  approval, but only while triage is on and once its run has happened, so
  the label alone is not enough; a bot `## Triage (revised)` comment that
  reports a reset means the current label is a fresh one.
- The issue is open, carries `agent:approved` and neither
  `needs-operator` (an open question from triage, or from an agent that
  handed the issue back, means the spec is not settled) nor `needs-triage`
  (the operator has asked for a fresh plan that the bot has not posted
  yet), and has no assignee other than the operator. Before the claim in
  step 2 it does not carry `in-progress`; after it, it does.

**Approved by request.** The operator asked an agent for the work
directly, and that agent filed the issue as `github-issue-file` says, with
the request recorded in place of `agent:approved`:

- The issue was opened by the operator's account (`user.login`), carries
  `requested`, and its body has the `### Operator request` section quoting
  the request. The request is the approval, for the work it names and
  nothing more.
- The latest `labeled` event for `requested` has the operator as `actor`
  and is later than the issue's last body edit (`lastEditedAt`, read as
  above) and every `renamed` and `reopened` event. An edit, a retitle or a
  reopen after it is a scope change the operator has not seen: only the
  session that holds the operator's answer re-applies the label
  (`github-issue-file` step 7); any other agent stops and asks on the
  issue.
- Either the plan conditions above hold (the latest bot triage comment is a
  plan, later than the last body edit and the latest `renamed` and
  `reopened` events, and the body still matches it), or no bot triage
  comment exists because triage is off or did not answer in time, which
  the pull request will say.
- The issue is open, carries no `needs-operator`, and carries
  `needs-triage` only when no triage comment exists; it has no assignee
  other than the operator; and `in-progress` as for an issue approved by
  label.

Either way, an issue that still carries `blocked`, a label of the kit's
releases before `sync-labels.sh --migrate` removed it, is handed back and
waiting for the operator: it fails the check.

An issue approved by label with no plan, or a body edited, retitled or
reopened after the plan or after the approval, has no settled scope to
check an edit against: ask on the issue rather than proceed.

`agent:approved`, or a recorded request, is the operator's authorization
for the scope the issue describes. It authorizes nothing else: no merge,
deployment, external mutation, or change outside that scope.

## 2. Claim

- Look for earlier work first: a branch matching the convention,
  `git ls-remote --heads origin "*/<n>-*"`, or an open PR whose body closes
  exactly that number, in any form GitHub links (`#<n>`, `<owner>/<repo>#<n>`
  or the issue URL): `gh api --paginate
  "repos/<owner>/<repo>/pulls?state=open&per_page=100" --jq '.[] | select(.body
  // "" | test("\\b(close|closes|closed|fix|fixes|fixed|resolve|resolves|resolved):?\\s+((<owner>/<repo>)?#|https://github\\.com/<owner>/<repo>/issues/)<n>\\b";
  "i")) | .number'`, with a dot in the owner or repository name written as
  `\\.`, reads every open PR, so no closing PR falls past a listing limit (a
  PR that merely mentions the number is not prior work). A branch whose pull
  request was merged or closed is finished work, not prior work: the
  repository squash-merges, so its commits are not on the default branch,
  and a new PR from it would carry the old patch again. Check with
  `gh pr list --head <branch> --state all --json number,state`; resume
  only a branch with no PR or an open one. For a finished branch (an
  issue reopened after its PR merged), start a fresh branch from the
  current default branch with a different slug. If unfinished work exists,
  continue on it
  and post a resume comment instead of a new claim; never start a second
  branch for the same unfinished attempt.
- Comment first: `Claimed by <tool> (<model>) on <date>.`, followed by
  `Session: <link>.` only where `AGENTS.md` allows session links. A resume
  comment is a claim too and follows the same rule. Note the URL
  `gh issue comment` prints, then re-read the comments. If another claim or
  resume comment was posted after the approval's latest `labeled` event
  (`agent:approved`, or `requested` for an issue approved by request) in
  the issue timeline and before yours (compare comment URLs or IDs, not
  authors, since agents share the operator's credentials), back off: delete
  nothing, reply that you yield, and stop. The earlier claim owns the issue,
  unless it is abandoned: a claim or resume comment on an issue that still
  lacks `in-progress` ten minutes later was interrupted before its label,
  and a later agent may claim over it, saying so in its own claim comment.
- Add `in-progress`: `gh issue edit <n> --add-label in-progress`,
  after running the approval check again (an approval withdrawn since your
  first read leaves the old `labeled` event in the timeline but not the
  label). If more than ten minutes passed between your claim comment and
  the label, re-read the comments once more: a claim posted over yours in
  that window wins, and you yield as above. When you are resuming after an operator
  answer, read the answer before continuing.
- Otherwise branch from the repository's default branch, read with
  `gh repo view <owner>/<repo> --json defaultBranchRef -q .defaultBranchRef.name`
  (never assume `main`; the checks above mean the same branch), as
  `<type>/<n>-<short-slug>`, type from the issue's type label
  (`feature` → `feat`, `bug` → `fix`, `chore` → `chore`, or `docs` for a
  change to documentation only).

## 3. Implement

- Follow the latest bot-authored `## Triage` plan, phase by phase. The plan
  is input: where
  the code disagrees with it, follow the code and say so in the PR.
- Keep to the issue's scope. Work you discover becomes a new issue, filed
  as `github-issue-file` says and referenced from the PR. Do not do it, and
  do not keep it in memory or a markdown note.
- Stop and ask when the plan's *Risks and stop-and-ask items* or `AGENTS.md`
  say so. Ask on the issue: comment with the question and your
  recommendation, then release the claim so the answer can be picked up by
  any agent: push the branch as it stands (`AGENTS.md` allows the push) and
  name it in the comment, swap `in-progress` for `needs-operator`, and end
  the session. On an issue approved by request, also ask the operator in
  your session. The operator answers on the issue and removes
  `needs-operator` (or re-applies `needs-triage` for a fresh plan); the
  next run passes the preconditions again and finds your branch and
  comment.

## 4. Validate, review, open the PR

- Before the PR, run the approval check again; the latest `## Triage`
  plan must also be the one you implemented. `needs-triage` is the
  operator asking for a fresh plan: stop and release the claim as the
  bot's revised plan will say. The exception is an issue approved by
  request that still has no bot triage comment: there `needs-triage` is
  the label it was filed with, which nothing has run to remove, so
  continue. If the approval is gone or stale, the
  operator or the triage bot withdrew it (an edit after approval does
  that, and an issue whose body or plan no longer matches what you
  implemented is withdrawn even while `agent:approved` is still there):
  push the branch, comment where you stopped and name the branch, remove
  `in-progress` and stop. Do not add `needs-operator`: the issue is back
  at `triaged` with a revised plan, and the operator re-approves it from
  there (on an issue approved by request, check the revised plan against
  the request as `github-issue-file` says before working it again).

- Run the validation the repository's validation skill names for the
  changed area, plus each phase's named check from the plan.
- Give each acceptance criterion its evidence, by the plan's ID (`AC1`):
  a check you ran and its result, or the file and line that delivers it
  where no check can. A plan without IDs (written before triage numbered
  them) leaves you to number the issue's criteria in order: its
  *Acceptance criteria* field; without one (the Bug form), its *What
  should happen* as one criterion, plus one that the steps to reproduce,
  when given, no longer show the fault; with neither field, the criteria
  its text states, and with none there, say so. Never mark a criterion met
  on a guess. *Not verified* is only for a criterion the change delivers
  that nothing before merge can show; a criterion the change does not
  deliver is not a caveat: finish it, or stop and ask as step 3 says.
- Run `fresh-eyes-review` before the PR leaves draft; resolve blocking
  findings.
- Open the PR with the `pull-requests` skill. The body's *Why* section
  carries `Closes #<n>`, and its section on checks (such as *How it was
  checked*) lists the criteria with their evidence as step 6 shows, for the
  reviewer to verify. Mention any new issues you opened. For an issue
  approved by request, the *Why* section says so, and says where the
  plan and the request differed and which you followed; with no triage
  plan, it says why (triage off, or no answer within the time limit) and
  that the criteria are the issue's own.

## 5. Handle review findings on the PR

Automated reviewers (the `pr-review` and `security-scan`
workflows, and any other review bot the repository configures) and people
comment on the PR. Every
finding is a claim handled under `fresh-eyes-review` *Handling findings*:
reproduce it, then fix with a commit or refute with evidence, replying on the
thread with the finding's ID. A fix that changes a criterion's evidence
updates its line in the PR body. Consolidate duplicates across reviewers in
one reply that names each ID. Before pushing any fix, run the approval
check again; the latest `## Triage` plan must also be the one the PR
implemented. An edit to the issue after the PR
opened withdraws the approval and revises the plan, and a fix pushed then
would implement superseded acceptance criteria: stop as step 4 says,
comment on the PR and the issue where you stopped, remove `in-progress`,
and leave the PR for the operator to re-approve. After fixes, the kit's code review re-runs on
push when `KIT_REVIEW_MODE` is `push`; in `open` mode request another
round with `gh workflow run pr-review.yml -f pr=<pr>`. The kit's
security scan re-scans only in `push` mode. Another review bot follows
its own settings and `AGENTS.md` says how to re-run it. Three rounds with a blocking finding still open means stop
and escalate on the issue, as `fresh-eyes-review` says.

## 6. Terminal state and report

Done means: the PR is open and not draft, its checks pass, no blocking
finding is open, and every criterion is *met* or *not verified* as step 4
allows. Merging is the operator's; never merge. Then comment on the
issue:

```markdown
## Ready for review
- PR: #<pr>
- Acceptance criteria:
  - AC1 <criterion>: met; <check and result, or `path:line`>
  - AC2 <criterion>: not verified; <why, and what would prove it>
- Checks run: <list>; not run: <list and why>
- Deviations from the plan: <or none>
- Caveats for the operator: <or none>
- New issues: #<a>, #<b>
```

One line per criterion, as the PR body lists them after the last fix. A
*not verified* line says what would show it after merge (a scheduled run,
a release) and is a caveat for the operator too.

Leave `in-progress` on; the PR's `Closes #<n>` closes the issue on merge.
Review rounds that arrive on the open PR afterwards are worked from the PR
(step 5) with its approval re-check, not by re-running step 1 on the issue.
If you must stop before the terminal state, push the branch and say where
you stopped in a comment that names it, release the claim (remove
`in-progress`, and add `needs-operator` when an answer is needed) so any
agent can take it, and clean up
worktrees and scratch as `worktrees-and-scratch` says. Before the terminal
state, a claim never outlives its session.
