# Work On Issue

> Use when the user says "work on issue", "work on this issue", "implement issue", "/work-on-issue", or otherwise asks to implement a GitHub issue end-to-end (not merely validate it). Takes a GitHub issue URL or number (defaults to the just-validated issue). Implements the fix in an isolated worktree, verifies it, commits and pushes, and opens a PR that closes the issue. This is the default follow-…

- **Type:** Skill
- **Install:** `agentstack add skill-richkuo-rk-skills-work-on-issue`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [richkuo](https://agentstack.voostack.com/s/richkuo)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [richkuo](https://github.com/richkuo)
- **Source:** https://github.com/richkuo/rk-skills/tree/main/skills/work-on-issue

## Install

```sh
agentstack add skill-richkuo-rk-skills-work-on-issue
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# work-on-issue

Take a GitHub issue from "validated" to "PR open", autonomously and end-to-end: isolate the work in a fresh worktree, implement the fix to the codebase's conventions, verify it really works, commit and push, then open a pull request that closes the issue. The skill ends with the open PR — requesting review is the caller's job (work-on-issue-loop does it; standalone, the user decides). Don't stop to ask the user between steps — do the work and report at the end.

**This is the natural follow-on to validate-issue.** When validate-issue ends with `→ Reply "work on issue"`, the user replying "work on issue" lands here. The skill is also valid standalone — invoke it when the user asks to implement an issue without a prior validation pass.

**Implement the issue, not your memory of it.** Re-read the issue and any validation findings before writing code; the description can be stale or wrong (that's what validate-issue exists to catch). Build the fix the traced code supports, not the one the prose suggests.

## Input

The user provides one of:
- Nothing — **default to the issue just validated this session**, else the latest open issue (`gh issue list --limit 1`).
- `#` / `` / full URL / `owner/repo#N`.

The steps assume the issue belongs to the repo of the current checkout. If `owner/repo#N` or the URL points at a different repo, do not proceed against the local checkout — locate a local clone of that repo and work there, or stop and tell the user which repo needs to be checked out. (`gh issue view`/`gh pr create` accept `-R owner/repo`, but the implementation itself needs the matching working tree.)

## Steps

### 0. Resolve the issue and gate-check it

Resolve which issue to work (per Input above), then fetch it — before creating any worktree, both because the gates below may end the run and because the worktree slug needs the issue title:

```bash
gh issue view  --comments
gh pr list --state open --search "# in:title,body"
```

Two gates, checked while no worktree or code exists yet:

- **The issue must still be open.** If it's closed, stop and report — don't implement a resolved issue.
- **No existing PR may already address it** — discovering one later wastes the entire cycle, splits review, and orphans a branch. Inspect any search hit: a PR that merely mentions `#` in passing doesn't count, one that fixes it does. If a genuine PR exists, surface it and stop (or, if it's this session's own branch, continue on it).

### 1. Ensure an isolated worktree off the latest default branch

All implementation happens in a fresh worktree branched from the repo's current default branch — never on the default branch itself, never on a divergent checked-out branch. Detect the default branch; don't assume `main` (repos use `master`, `develop`, etc.):

```bash
DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name)
git fetch origin "$DEFAULT_BRANCH"
git branch --show-current   # where am I now?
```

- **If validate-issue already entered a worktree for this issue this session** (cwd is under `.claude/worktrees/issue--…`), confirm with `pwd` / `git branch --show-current` and proceed — do not create a second one.
- **Otherwise create and switch into one** with the native `EnterWorktree` tool (it creates under `.claude/worktrees/` — base ref verified below — AND switches the session cwd in one step — a bare `git worktree add` + `cd` leaves the session's tracked cwd on the old checkout, so always use the tool):

```
EnterWorktree(name: "issue--")
```

`` = the issue title kebab-cased to ≤5 words (drop filler, strip punctuation) — e.g. 873 "Scale-in / pyramiding support for open positions" → `issue-873-scale-in-pyramiding`. If a worktree for this issue already exists, enter it by `path`.

After the call, confirm the switch (`pwd` / `git branch --show-current`), state the path, and **verify the base** — EnterWorktree branches from `origin/` only when the `worktree.baseRef` setting is `fresh` (its default); set to `head`, it branches from the local HEAD, which may be stale or divergent:

```bash
git rev-parse HEAD "origin/$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name)"   # the two SHAs must match
```

If they differ on a worktree you **just created**, move it onto the fetched default with `git reset --hard origin/` — safe only because the brand-new branch carries no commits. Never reset a re-entered worktree that already has work on it. Do every later step from inside the worktree.

### 2. Understand the issue and the code

Read the issue body **and its comment thread**, already fetched in step 0 (maintainer clarifications and prior validation reports often live in comments), the validation findings if validate-issue produced them this session, and the repo's `CLAUDE.md` / architecture docs for the subsystem you're about to touch. Establish: which files change, what the correct fix is (per the traced code, not the prose), what tests prove it, and which conventions/invariants govern the area. If the issue's proposed sketch was marked ⚠️/❌ during validation, implement the **optimal direction for this repo**, not the original sketch — correctness and the codebase's patterns outrank issue loyalty.

### 3. Implement the fix

Build the absolute-best solution the issue calls for, evaluated as if cost, effort, time, token spend, and code volume were unlimited — they are not factors. The only constraints that override "best" are correctness and safety.

- **Follow existing conventions.** Read the surrounding code first; match its patterns, naming, error handling, and the repo's `CLAUDE.md` guardrails. Reuse existing helpers over new infrastructure.
- **Respect invariants.** Grep `CLAUDE.md`/guardrails and nearby comments for any invariant governing the values you write (ownership, single-source-of-truth, fail-closed, "X never into Y"). Route values through their authorized path, not the convenient one.
- **Write tests for the change** — new functionality and bug fixes both get tests (regression test the bug, not just the happy path). Match the repo's test layout and harness.
- **Prove regression tests are real (red → green).** For a bug fix, run the new test against the unfixed code first — write the test before the fix, or stash the fix — and watch it fail. A regression test that never failed proves nothing.
- Keep the diff scoped to the issue; don't smuggle in unrelated refactors.

### 4. Verify before claiming anything

Evidence before assertions: run the project's build, tests, and linters and confirm they pass before you commit. Check the repo's `CLAUDE.md` / `package.json` / Makefile for the exact commands (e.g. `go build ./...` + `go test -race ./...` + `gofmt -w`, `bun test` + `bun run build`, `uv run --no-sync python -m pytest` + `py_compile`). Report real results — if something fails, fix it or surface it; never paper over a failure.

### 5. Commit and push

Only after verification passes:

```bash
git status                    # review BEFORE staging — any stray artifacts, logs, local config?
git add -A                    # only if status showed nothing unrelated; otherwise stage files explicitly
git commit -F 
git push -u origin    # the worktree's issue-- branch
```

If `git status` shows anything unrelated to the change, don't `add -A` — stage the intended files by name and leave the strays out.

Commit message: a concise summary of the change, referencing the issue (match the repo's commit-title convention — e.g. `feat(#): …` / `fix(#): …` if the repo uses it). This is new work, so the footer uses the **Created** verb. **Honor the repo's footer convention (its `CLAUDE.md` takes precedence over this default)**:

```
---
Created with LLM:  |  | Harness: 
```

Fill `` (e.g. `Opus 4.8`) and `` (`high` by default). `` is whatever actually produced the change — `Claude Code` for an interactive session, or the GitHub Action identifier when running in CI (e.g. `anthropics/claude-code-action@v1`; the workflow states this identifier in your system prompt — use that value, and treat its absence as an interactive session). Never put time/effort estimates in the message body. No `Co-authored-by` trailer.

### 6. Open the PR

The duplicate-PR gate already ran in step 0; if significant time has passed since, re-run the `gh pr list` search cheaply before creating.

Shell state does **not** persist between Bash commands, so `$DEFAULT_BRANCH` from step 1 is gone here — re-detect it inline rather than assuming the variable survived:

```bash
gh pr create --base "$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name)" --head  --title "" --body-file 
```

- **Title:** match the repo's PR-title convention (the commit-title style is usually right).
- **Body must close the issue:** include `Closes #` so merging the PR resolves it. Summarize what changed and how it was verified; keep it scannable. Don't restate the whole issue.
- **Footer:** same convention as the commit — **Created** verb, repo footer format (global default `Created with LLM:  |  | Harness: `, harness resolved per step 5: `Claude Code` interactively, the Action identifier in CI). No `Co-authored-by` trailer.

Capture the PR number/URL from the command output.

### 7. Report to the user

The skill ends here — do **not** trigger an `@claude` review or wait on CI; requesting review belongs to the caller (work-on-issue-loop posts the trigger itself; standalone, the user decides whether and when to request one).

Terse summary: the worktree/branch, what you implemented (one or two lines), the verification result, the commit SHA, the PR URL, and that it closes #. The work is done and the PR is open — not waiting on the user.

**Follow-on work named in the deliverables must not silently drop.** If the PR body, commit message, or any doc the diff adds names follow-on work ("own issue", "future work", "not yet wired"), state it in the report as **unfiled** — under work-on-issue-loop, its step 4.5 files these once review converges; standalone, tell the user the issues still need filing.

**Cap this report at 55 words, ELI18** — plain language, no jargon, as if explaining the outcome to a smart 18-year-old with no context on this codebase or its internals.

## Guardrails

| Situation | Action |
|-----------|--------|
| About to implement on the default branch or a divergent checked-out branch | Stop — enter the isolated worktree first (step 1) |
| Fresh worktree's HEAD doesn't match `origin/` | `worktree.baseRef` may be `head` — reset the just-created, commit-free branch onto `origin/` before implementing |
| Worktree for this issue already exists | Enter it by `path`; don't create a duplicate |
| Issue lives in a different repo than the current checkout | Stop — work in a clone of that repo, or tell the user which repo to check out |
| Issue is already closed | Stop and report — don't implement a resolved issue |
| An open PR already addresses the issue | Don't start a duplicate — catch this in step 0, before a worktree exists; surface it (or continue on it if it's this session's branch) |
| Issue description conflicts with what the code actually does | Trust the traced code; implement the real fix, note the discrepancy in the PR body |
| Issue's proposed sketch was ⚠️/❌ in validation | Implement the optimal direction for this repo, not the original sketch |
| Fix touches money / data integrity / security / auto-protective logic | Implement the safest correct design from first principles; verify the invariant isn't violated |
| Anywhere the default branch is needed (fetch, worktree base, `--base`) | Detect it (`gh repo view --json defaultBranchRef`), re-detecting inline where used — shell variables don't persist between commands |
| Tempted to skip or soften tests because "it's a small change" | Small changes break too; write the regression test and watch it fail on the unfixed code (red → green) |
| Tests/build/lint fail locally | Fix or surface it — never commit, push, or claim success on a failing tree |
| `git status` shows files unrelated to the change | Don't `git add -A` — stage the intended files by name |
| Writing the PR body | Include `Closes #` (without it the merge doesn't resolve the issue) and end with the repo's footer convention — **Created** verb, no `Co-authored-by` |
| Tempted to trigger an `@claude` review or wait on CI after opening the PR | Don't — the skill ends with the open PR; review requests are the caller's job |
| Tempted to pause and ask the user mid-flow | Don't — implement, verify, commit, push, open the PR, then report |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [richkuo](https://github.com/richkuo)
- **Source:** [richkuo/rk-skills](https://github.com/richkuo/rk-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-richkuo-rk-skills-work-on-issue
- Seller: https://agentstack.voostack.com/s/richkuo
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.