Task: Work on Issue $ARGUMENTS

Pull the specified GitHub issue, gather its full context, create a working branch, and start.

CLAUDE.md's orchestration rules govern, without their escape hatch — work touching code always goes to an agent, however small it looks. Your exceptions are metadata: gh calls fetching issue context, git calls managing the branch. What you keep is the conversation.

Step 0: Resolve the ref and note

$ARGUMENTS is the issue ref optionally followed by a note. The first token is the issue ref, everything after is a note providing additional context.

Example: /issue 123 focus on the api endpoint, ignore the frontend for now → issue ref: 123, note: focus on the api endpoint, ignore the frontend for now

$ARGUMENTS may be empty. Resolve the ref from the first source that yields one:

Nothing resolves → ask which issue, one line, no preamble.

If a note is present, treat it as guidance throughout planning and execution — it may narrow scope, set priorities, or provide context not in the issue itself.

Step 1: Parse the issue reference

Parse the issue ref to determine the repo and issue number:

To get the current repo's owner:

gh repo view --json owner -q '.owner.login'

Step 2: Fetch issue context

Gather everything the issue has attached. Any of it may carry relevant context; interpretation isn't this skill's job — pull it all first, then read.

• The issue: title, body, comments, assignees, state
• Labels and their descriptions (label names can be opaque; descriptions often carry the meaning)
• Milestone and its description
• Issue type, if set
• Parent issue, if this is a sub-issue
• Sub-issues, if this issue has any
• Linked PRs
• Project board fields, if the issue is on a board

gh issue view returns names but not label/milestone descriptions or type/parent/sub-issue/project data. Reach further for the rest:

# The issue itself
gh issue view <number> --repo <owner/repo> \
  --json number,title,body,state,assignees,labels,milestone,comments

# Label descriptions (issue view returns only names)
gh label list --repo <owner/repo> --limit 200 --json name,description

# Milestone description (issue view returns only title)
gh api repos/<owner/repo>/milestones/<milestone-number>

# Issue type, parent, sub-issues, linked PRs, project fields
gh api graphql -f query='
query($url: URI!) {
  resource(url: $url) {
    ... on Issue {
      issueType { name description }
      parent { number title url state }
      subIssues(first: 50) { nodes { number title state url } }
      closedByPullRequestsReferences(first: 20, includeClosedPrs: true) {
        nodes { number title state url }
      }
      projectItems(first: 10) {
        nodes {
          project { title number }
          fieldValues(first: 20) {
            nodes {
              ... on ProjectV2ItemFieldSingleSelectValue {
                field { ... on ProjectV2SingleSelectField { name } }
                name
              }
              ... on ProjectV2ItemFieldTextValue {
                field { ... on ProjectV2Field { name } }
                text
              }
              ... on ProjectV2ItemFieldNumberValue {
                field { ... on ProjectV2Field { name } }
                number
              }
            }
          }
        }
      }
    }
  }
}' -f url="https://github.com/<owner/repo>/issues/<number>"

Step 3: Route and announce

The GraphQL call returns subIssues with a state on every node. If at least one sub-issue is OPEN, this is a parent with work left in it and the epic skill owns it — say so in one line and invoke epic with the same ref and note.

Otherwise announce what's running in one line, then go straight to Step 4 — invoking /issue with a resolved ref is Josh's go-ahead to work it, not a prompt for a second yes:

Working issue #43 — <title>

Only pause for confirmation when something genuinely needs it: the ref resolved implicitly and might be the wrong issue, or the issue itself leaves a decision open that you can't settle from context.

Step 4: Create working branch

Ensure you're on the base branch (usually master or main), then:

git issue <number>

Step 5: Set session context

Track the issue as active session context: Active Issue: #<number> - <title>.

Step 6: Assess and route

Read the fetched context and assess.

If any signal suggests this is a bug — issue type set to a bug variant, a label indicating a defect, body or comments describing broken or regressed behavior, a linked PR that reverted something, or the note frames it as an investigation:

• Invoke the systematic-debugging skill.
• Trace the root cause before proposing a fix. Do not jump to a patch based on the symptom.
• Once the root cause is understood, continue to the complexity assessment below to decide how to proceed with the fix.

Otherwise, assess complexity:

Straightforward — requirements clear, approach obvious, no architectural decisions needed:

• Skip planning. Go straight to step 7.

Complex — ambiguous requirements, multiple approaches possible, architectural decisions needed, or the note asks to plan first:

• Use the planning skill to draft a plan.
• Exit plan mode for approval, then go to step 7 with the approved plan as direction.

Default to just starting. Only plan when the work genuinely needs it.

Step 7: Dispatch the implementer

Dispatch an implementer agent. It starts cold, so everything bearing on the work goes in the prompt:

Work GitHub issue #<n> in <owner/repo>: <title>
## The issue
<full body>
## Discussion
<comments carrying requirements or constraints>
## Direction
<the note, the approved plan, the root cause traced in triage — whatever applies>
## Your scope
Only this issue, in the current working tree on branch <branch>.

BLOCKED: <question> comes back — 100% confident from the conversation or the issue → answer it and resume the same agent with SendMessage so its context survives. Anything less → put the question to Josh verbatim with the context needed to answer it; don't soften it, don't answer around it, don't hand him a guess to confirm.

Scope expands past the issue → stop and ask about a new issue.

Step 8: Run the gate

The project defines a team-review skill → invoke it yourself as the gate; it's a skill, not an agent to dispatch. Otherwise dispatch a code-reviewer agent with the diff (the uncommitted working tree on branch <branch>), the list of changed files, the issue URL, and the implementer's claims quoted verbatim.

• Code findings → back to the implementer via SendMessage. All of them, no cherry-picking. If one looks wrong, dispatch an agent to check it before dismissing it.
• Claims findings → to Josh, in your own message: in full when it bears on the topic open with him, otherwise first once that topic is concluded.

One pass: the implementer fixes every finding, then the work goes to Josh. No second reviewer. Tests failing means the issue isn't done — it does not go to Josh with a caveat.

Step 9: Present and stop

Hand it over like a colleague would — a short plain-language paragraph, not a file listing. Then stop and wait for review. Changes requested → implementer via SendMessage, feedback verbatim, then back through steps 8 and 9.