GitHub Issue Solve Skill

Automation skill for solving GitHub issues by implementing solutions and creating pull requests.

Purpose

This skill helps you:

1. Analyze GitHub issues and understand requirements
2. Implement features or fixes in the codebase
3. Create feature branches and commit changes
4. Create pull requests with proper descriptions

Prerequisites

This skill can use:

• ghx (default): Must be attempted first for context collection
• gh CLI (fallback): Use only when ghx is unavailable or fails

ghx here means the ghx skill (for example skills/ghx/scripts/ghx.sh), not a standalone ghx binary on PATH.

Environment & Paths

• GITHUB_OUTPUT_DIR: Where this skill writes artifacts
  • Default: system-recommended output directory if provided by caller; otherwise a temp dir /tmp/holon-ghissue-*
• GITHUB_CONTEXT_DIR: Where ghx writes collected data
  • Default: ${GITHUB_OUTPUT_DIR}/github-context
• GITHUB_TOKEN / GH_TOKEN: Token used for GitHub operations (scopes: repo or public_repo)

Inputs & Outputs

• Inputs: ${GITHUB_CONTEXT_DIR}/github/issue.json, ${GITHUB_CONTEXT_DIR}/github/comments.json (produced via ghx by default; fallback via gh commands only if ghx fails)
• Outputs (agent writes under ${GITHUB_OUTPUT_DIR}):
  • summary.md
  • manifest.json

Definition of Done (Strict)

The run is successful only if all of the following are true:

1. Code changes are implemented for the target issue.
2. Changes are pushed to a branch.
3. A GitHub PR is actually created or updated using gh.
4. PR existence is verified via gh pr view.
5. ${GITHUB_OUTPUT_DIR}/summary.md and ${GITHUB_OUTPUT_DIR}/manifest.json include publish result details (pr_number and pr_url).

Workflow

1. Context Collection

If context is not pre-populated, always follow this decision order:

1. Attempt ghx collection first.
2. If ghx is unavailable or fails, fall back to gh issue view / gh api and write equivalent context files under ${GITHUB_CONTEXT_DIR}/github/.
3. Record the collector and fallback reason (if any) in outputs:
   • context_collector: ghx or gh
   • fallback_reason: non-empty only when context_collector=gh
     • Example: ghx command not found in PATH
     • Example: ghx context collect failed with exit code 1

2. Analyze Issue

Read the collected context:

• ${GITHUB_CONTEXT_DIR}/github/issue.json: Issue metadata (title, body, labels, assignees)
• ${GITHUB_CONTEXT_DIR}/github/comments.json: Discussion comments

Understand:

• What feature or fix is requested
• Any specific requirements or constraints
• Related issues or PRs mentioned

3. Implement Solution

Create a feature branch and implement the solution:

# Create feature branch
git checkout -b feature/issue-<number>

# Make your changes to the codebase
# ... implement the feature or fix ...

# Commit changes
git add .
git commit -m "Feature: <description>"

# Push to remote
git push -u origin feature/issue-<number>

4. Generate Artifacts

Create the required output files:

${GITHUB_OUTPUT_DIR}/summary.md

Human-readable summary of your work:

• Issue reference and description
• What was implemented
• Key changes made
• Testing performed

${GITHUB_OUTPUT_DIR}/manifest.json

Execution metadata:

{
  "provider": "github-issue-solve",
  "issue_ref": "holon-run/holon#502",
  "context_collector": "ghx|gh",
  "fallback_reason": "",
  "branch": "feature/issue-502",
  "status": "completed|failed",
  "commits": ["abc123", "def456"]
}

5. Create Pull Request

Use a direct gh publish flow (single mandatory path):

ISSUE_NUMBER=<issue number>
HEAD_BRANCH="$(git branch --show-current)"
BASE_BRANCH="${BASE_BRANCH:-main}"
PR_TITLE="Fix #${ISSUE_NUMBER}: <short title>"
PR_BODY_FILE="${GITHUB_OUTPUT_DIR}/summary.md"

EXISTING_PR_NUMBER="$(gh pr list --head "$HEAD_BRANCH" --json number --jq '.[0].number // empty')"

if [ -n "$EXISTING_PR_NUMBER" ]; then
  gh pr edit "$EXISTING_PR_NUMBER" --title "$PR_TITLE" --body-file "$PR_BODY_FILE" --base "$BASE_BRANCH"
  PR_NUMBER="$EXISTING_PR_NUMBER"
else
  gh pr create --base "$BASE_BRANCH" --head "$HEAD_BRANCH" --title "$PR_TITLE" --body-file "$PR_BODY_FILE"
  PR_NUMBER="$(gh pr list --head "$HEAD_BRANCH" --json number --jq '.[0].number // empty')"
fi

if [ -z "$PR_NUMBER" ]; then
  echo "ERROR: failed to resolve PR number after publish" >&2
  exit 1
fi

PR_URL="$(gh pr view "$PR_NUMBER" --json url --jq .url)"
if [ -z "$PR_URL" ]; then
  echo "ERROR: failed to resolve PR url after publish" >&2
  exit 1
fi

Treat publish execution as mandatory completion work, not optional cleanup.
Update ${GITHUB_OUTPUT_DIR}/summary.md and ${GITHUB_OUTPUT_DIR}/manifest.json with pr_number and pr_url.

Output Contract

Required Outputs

1. ${GITHUB_OUTPUT_DIR}/summary.md: Human-readable summary

   • Issue reference and description
   • Implementation details
   • Changes made
   • Testing performed

2. ${GITHUB_OUTPUT_DIR}/manifest.json: Execution metadata

   {
     "provider": "github-issue-solve",
     "issue_ref": "holon-run/holon#502",
     "context_collector": "ghx|gh",
     "fallback_reason": "",
     "branch": "feature/issue-502",
     "status": "completed|failed",
     "commits": ["abc123"],
     "pr_number": 123,
     "pr_url": "https://github.com/holon-run/holon/pull/123"
   }

Failure Rules

• If PR create/edit or PR verification fails, mark the run as failed.
• Do not report success when only artifacts were generated without a PR side effect.
• On failure, write actionable publish error details and next steps in ${GITHUB_OUTPUT_DIR}/summary.md.
• If ghx is available but not attempted first for context collection, treat as process failure and correct before reporting success.

Git Operations

You are responsible for all git operations:

# Create feature branch
git checkout -b feature/issue-<number>

# Stage changes
git add .

# Commit with descriptive message
git commit -m "Feature: <description>"

# Push to remote
git push -u origin feature/issue-<number>

GitHub CLI Operations

You MAY use these commands:

• gh issue view <number> - View issue details
• gh issue comment <number> - Comment on issues
• gh pr create / gh pr edit - Create or update PR
• gh pr view <number> - Verify PR details after publish

Important Notes

• You are running HEADLESSLY - do not wait for user input or confirmation
• Attempt ghx first for context collection; use gh only as explicit fallback with documented reason
• Create feature branches following the pattern feature/issue-<number> or fix/issue-<number>
• Write clear commit messages describing what was changed
• Include "Closes #" in PR body to auto-link the issue
• Run tests if available before creating the PR
• Do not mark success until gh pr view returns a valid PR URL

Reference Documentation

See references/issue-solve-workflow.md for detailed workflow guide.